Implement M9.4 revision-tagged microscopic environment rendering

Add SDL-free owned EnvironmentPresentation copied from M6.3 views (no
store pointers or validation tokens), a single-slot EnvironmentLayer that
rejects foreign/regressed updates and reports none/current/stale against
observed authority watermarks, and a bounded camera projection with
explicit missing, not-requested, present-zero, undefined-moisture and
stale encodings (at most 2313 clipped rectangles, reused buffer).

The engineering app renders a local in-memory fixture authority with
configurable refresh cadence and layer selection. ADR-0080 records the
decision; validation evidence and limits are in VALIDATION.md.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
This commit is contained in:
dingo
2026-10-01 17:45:53 -04:00
co-authored by Claude Opus 5.5
parent bb0412cd0f
commit feca07f791
20 changed files with 1393 additions and 62 deletions
+7 -1
View File
@@ -404,7 +404,13 @@ from injected events.
cursor-anchored zoom, bounded sequence/tick intentions and focus/UI/backlog
suppression implemented under ADR-0079. Camera round trips and native event
regressions are recorded in engineering/VALIDATION.md. The app uses local
fixture ticks, not server time. Next gate: M9.4.
fixture ticks, not server time.
**M9.4 status (2026-10-01):** owned revision-tagged environment presentations,
ordered freshness (none/current/stale) and bounded camera-projected rendering
with explicit missing, unrequested, present-zero and undefined encodings under
ADR-0080. A local in-memory fixture authority stands in for server views until
M9.7. Evidence in engineering/VALIDATION.md. Next gate: M9.5.
**Goal:** a native desktop cellular viewer/controller with input, camera, renderer,
readable organism/environment views and a real development-server connection.
+16 -10
View File
@@ -2,17 +2,23 @@
## Current gate — 2026-10-01
M9.3 adds local-mm pan/zoom camera mapping and bounded sequence/tick input
intentions ([ADR-0079](adr/0079-camera-and-input-intentions.md)). Focus loss,
UI capture/release and saturated event batches cancel held input. WASD controls
an intention indicator; arrows/wheel navigate the presentation fixture. See
[CLIENT.md](engineering/CLIENT.md) and [VALIDATION.md](engineering/VALIDATION.md).
Updated remote Gitea client execution remains unverified locally.
M9.4 renders microscopic environment views
([ADR-0080](adr/0080-environment-presentation.md)). The client copies M6.3 views
into owned, revision-tagged presentations; `EnvironmentLayer` rejects foreign or
regressed updates and shows none/current/stale against observed authority
watermarks. Habitats, terrain cells and voxel boundaries project through the
M9.3 camera into at most 2313 clipped rectangles, with explicit missing,
not-requested, present-zero, undefined-moisture and stale encodings. See
[ENVIRONMENT_RENDERING.md](engineering/ENVIRONMENT_RENDERING.md) and
[VALIDATION.md](engineering/VALIDATION.md). Remote Gitea client execution of the
extended CI stage remains unverified locally.
Next: **M9.4**, rendering microscopic environment views. The client displays a
camera-controlled fixture, not organisms or a connected world. Its tick is a
local input fixture counter. No deployment, simulation rules, persistent formats
or world state changed in M9.3.
Next: **M9.5**, organism and debug views. The app's environment comes from a local
in-memory fixture authority, not a connected region; its tick is a fixture counter.
No deployment, simulation rules, persistent formats or world snapshots changed.
M9.3 added local-mm pan/zoom camera mapping and bounded sequence/tick input
intentions ([ADR-0079](adr/0079-camera-and-input-intentions.md)).
The sections below retain earlier milestone delivery history.
+69
View File
@@ -0,0 +1,69 @@
# ADR-0080: Revision-tagged environment presentation
## Status
Accepted for the M9.4 engineering client. Colours, ramps and thresholds are
presentation choices, not physical scales, biology or final player UI.
## Context
M6.3 views carry typed quantities, explicit absence, tick, field watermark and
per-chunk revisions, but also private store identities and validation tokens.
The renderer must not retain those, must not turn missing data into zero, and
must not grow geometry with world size. M9.7 will receive views from a server,
so the presentation boundary cannot depend on local store objects.
## Decision
Add an SDL-free, owned `EnvironmentPresentation` (include/evo/client/
environment_view.hpp): one Z slice of at most 256 copied cells, each with voxel,
chunk revision, habitat box/volume, substrate, terrain material/fill, per-field
presence (`not_requested`, `missing`, `present`) with fg/pJ quantity, and moisture
status. `create` validates mask/presence consistency, habitat geometry, slice,
strict (x, y) order and bounds; `present_environment` adapts a local M6.3 view and
copies no tokens or store pointers. The type is the transport-neutral input for
later server views; it is not a capability and never authorizes consumption.
`EnvironmentLayer` holds at most one presentation and the newest observed authority
revision (identity, tick, field watermark). It rejects other worlds/frames and any
regression of tick, field revision or a shared voxel's chunk revision; equal
revisions are accepted (new footprint). A presentation is `stale` when an observed
revision is ahead of it or the host reports failed validation; `none` when absent.
Restore/reconnect to another lineage requires explicit `reset`.
`build_environment` (include/evo/render/environment.hpp) projects cells through
the M9.3 camera into clipped logical rectangles, in cell order: terrain square,
habitat encoding, voxel outline, then a status chip and legend. Encodings: present
values on a fixed log2 density ramp (quantity/habitat um^3 over [-30, 12]); present
zero black; missing a magenta checker; not requested a hollow grey outline; zero
water capacity a distinct "undefined" colour. Stale dims fills and outlines voxels
amber; the chip is green/amber/red for current/stale/none. Small cells collapse to
one encoded rectangle. Output is at most 256*9+9 rectangles in a caller-reused
buffer; no textures, caches or per-world allocation exist.
The engineering app owns an in-memory local fixture authority (FieldStore +
ChunkStore) that performs conserved same-channel water moves via the public API and
refreshes views at a configurable cadence. It is never persisted or published and
is replaced by M9.7 server views. No new dependency, simulation rule or format.
## Alternatives considered
- Render directly from `EnvironmentView`: retains store identities/tokens and
couples the renderer to local stores; rejected.
- Auto-ranged colour scale per view: hides absolute change between refreshes.
- Textures/field images: unnecessary for 256 bounded habitats; adds GPU lifetime.
- Silently keeping the newest arrival: out-of-order updates could roll back state.
## Benefits
Explicit absence/zero/unrequested/undefined/stale presentation, bounded memory and
work, deterministic output and SDL-free tests; rendering cannot mutate resources.
## Costs
Fixed ramp clamps extreme densities; one Z slice and one field per frame. Global
field watermark marks whole views stale (ADR-0052 conservatism).
## Risks
Colour choices are not accessibility-qualified; human visual and colour-vision
review remain M9.8 work. Validation of authority revisions is only as honest as
the host/server supplying them; M9.6/9.7 must authenticate and bound them.
## Consequences
M9.5 adds organism presentation on the same frame budget; M9.7 builds
`EnvironmentPresentation` from protocol views and feeds server watermarks to
`observe`. Changing ramp/encoding semantics requires updating this ADR and tests.
+1
View File
@@ -91,3 +91,4 @@ design. No unadopted candidate is a link dependency of the proof.
- [ADR-0077: Scoped native client dependencies](0077-scoped-native-client-dependencies.md) - SDL 3.4.16 window/events and 2D renderer for the opt-in M9.1 probe; no simulation dependency.
- [ADR-0078: Native client lifecycle](0078-native-client-lifecycle.md) - main-thread RAII application, immutable presentation frames and explicit surface/device failure handling.
- [ADR-0079: Camera and input intentions](0079-camera-and-input-intentions.md) - local-mm projection, bounded sequence/tick intentions, focus/UI capture and explicit host event ordering.
- [ADR-0080: Environment presentation](0080-environment-presentation.md) - owned revision-tagged environment presentations, ordered freshness and bounded explicit missing/stale rendering.
+14 -2
View File
@@ -1,4 +1,4 @@
# Native client boundary (M9.2–M9.3)
# Native client boundary (M9.2–M9.4)
Implemented scope: desktop lifecycle and primitive presentation, not gameplay.
ADR-0077 selects SDL; ADR-0078 defines its ownership and view boundary.
@@ -9,7 +9,9 @@ flowchart LR
App --> Frame[Owned immutable render Frame]
Platform --> Render[Private SDL renderer]
Frame --> Render
Future[Later M9.4 view projection] -. copied presentation values .-> Frame
World[M6.3 EnvironmentView] -- copied once --> Views[EnvironmentPresentation / Layer]
Views --> Env[build_environment + Camera]
Env -- bounded rectangles --> Frame
```
`include/evo/client/application.hpp` and `include/evo/render/frame.hpp` contain
@@ -47,6 +49,16 @@ specified in [CAMERA_INPUT.md](../engineering/CAMERA_INPUT.md) and ADR-0079.
UI capture and event-backlog handling suppress held world input; sequence/tick
intentions do not confer server authority. M9.6 owns session binding.
M9.4 ([ENVIRONMENT_RENDERING.md](../engineering/ENVIRONMENT_RENDERING.md),
ADR-0080) adds SDL-free `client/environment_view.hpp` and
`render/environment.hpp`. A presentation copies at most 256 cells of one Z slice
from a view and retains no store, token or native handle. `EnvironmentLayer`
holds one presentation, rejects foreign or regressed revisions and reports
none/current/stale against observed authority watermarks. The projection emits
at most 2313 clipped rectangles with explicit missing, unrequested, present-zero,
undefined and stale encodings. The client libraries link the headless world
library read-only; no world or simulation target links client code.
Failure tests inject actual SDL events, including foreign window IDs, with no
test-only production hooks. Real device failures and physical DPI/input require
manual hardware qualification at M9.8. The native client is opt-in and never
+4 -2
View File
@@ -44,8 +44,10 @@ No Steam ID, socket, Kubernetes API, logger clock or storage handle belongs in
the simulation state. Durable account references live in orchestration mapping.
M9.2 implements the opt-in [native client boundary](CLIENT_ARCHITECTURE.md):
copied immutable presentation frames and one main-thread platform owner. It does
not yet project biological views or connect to a region server.
copied immutable presentation frames and one main-thread platform owner. M9.4
projects owned copies of M6.3 environment views (ADR-0080); the dependency runs
world -> client views -> render only. It does not yet render organisms or connect
to a region server.
| Boundary | Owns | Must not own |
|---|---|---|
+5 -4
View File
@@ -71,8 +71,9 @@ Tab toggle is processed in event order, so subsequent presses after that toggle
belong to its new capture state.
The standalone host uses an increasing **local fixture tick**, not server time.
It draws a world-anchored rectangle, a capture indicator and an intention dot.
Camera panning uses 400 logical units/second with elapsed time clamped to 0.1 s;
wheel zoom uses 2^(steps/4). These are presentation controls. No network messages,
world modifications or organism actions occur. M9.6 must bind intention ticks
It draws a capture indicator, an intention dot and (since M9.4) the environment
fixture. Camera panning uses 400 logical units/second with elapsed time clamped to
0.1 s; wheel zoom uses 2^(steps/4). These are presentation controls. Input never
sends network messages, modifies the world or acts for an organism; the M9.4
fixture authority's own water moves are independent of input. M9.6 must bind intention ticks
and counters to secure sessions; the server independently validates all requests.
+14 -6
View File
@@ -1,9 +1,11 @@
# Native engineering client (M9.2–M9.3)
# Native engineering client (M9.2–M9.4)
This opens a resizable native window containing a camera-controlled presentation fixture.
It does not simulate a world, connect to a server or implement cellular gameplay.
This opens a resizable native window showing camera-controlled environment habitats
from a local in-memory fixture authority (M9.4). It does not run an ecosystem,
connect to a server or implement cellular gameplay.
Contract: [client architecture](../architecture/CLIENT_ARCHITECTURE.md), ADR-0078.
Camera/input: [contracts and limits](CAMERA_INPUT.md), ADR-0079.
Environment: [presentation and encodings](ENVIRONMENT_RENDERING.md), ADR-0080.
## Build and run
@@ -25,14 +27,18 @@ Close the window to exit. `--renderer software` or `--renderer vulkan` requests
one explicit backend, without fallback. `--frames N` exits after N bounded steps
(including paused steps), maximum 100000; `--hidden` opens without showing the
window and pauses drawing. These options permit unattended smoke checks.
Usage errors exit 2, lifecycle failures exit 1, orderly exit returns 0.
`--layer NAME` selects the displayed field or `moisture`; `--refresh-every N`
(1..1000 fixture authority ticks) delays view refresh so the stale state is visible.
Usage errors exit 2, lifecycle/fixture failures exit 1, orderly exit returns 0.
Engineering controls: arrow keys pan, mouse wheel zooms around the pointer, WASD
updates the small intention indicator without moving the world fixture. Tab
toggles UI capture: the top-left bar turns orange and navigation/movement input
is suppressed. Leaving capture/focus loss requires fresh presses. This is a
focus exercise, not the final player UI. The host's input tick is a local fixture
counter and is never interpreted as authoritative server time.
counter and is never interpreted as authoritative server time. The top-right
chip shows environment freshness (green current, amber stale, red none); the
bottom-left legend shows the value ramp.
For native X11 regression on a CI host:
@@ -40,7 +46,9 @@ For native X11 regression on a CI host:
xvfb-run -a env SDL_VIDEO_DRIVER=x11 ./build/client/evo-client-lifecycle-tests
```
CTest uses the dummy driver. The lifecycle suite runs 32 open/destroy rounds,
CTest uses the dummy driver. `client-environment` is an SDL-free suite for
presentation validation, ordering/freshness, encodings, seams and bounds; it
prints an `environment_profile` line (rectangles, bytes, microseconds per build). The lifecycle suite runs 32 open/destroy rounds,
resize/scale queries, non-unit drawable-scale pixel checks, minimize/restore,
show/hide, focus/foreign events, reset/loss and close. Separate process checks
exercise initialization failure. Tests stay active under NDEBUG. Synthetic
+92
View File
@@ -0,0 +1,92 @@
# M9.4 microscopic environment rendering
Decision: [ADR-0080](../adr/0080-environment-presentation.md). Headers:
`include/evo/client/environment_view.hpp` (presentation values, freshness) and
`include/evo/render/environment.hpp` (rectangle projection). Neither includes SDL.
Dependency direction: world (read-only views) -> client views -> render
environment -> immutable `Frame` -> private SDL renderer. Nothing flows back.
```cpp
auto view = world::query_environment(fields, terrain, tick, footprint, mask);
auto presentation = client::present_environment(*view, slice_z); // owned copy
layer.accept(std::move(*presentation)); // rejects foreign/regressed
layer.observe({identity, authority_tick, field_watermark}); // later: stale?
render::build_environment(rects, layer.current(), layer.freshness(), camera, display);
```
## Presentation values
A presentation is one Z slice of 1..256 cells, strictly ordered by voxel (x, y),
with the source revision (world/frame, tick, field watermark) and request mask.
Cells copy chunk revision, the habitat box and volume, substrate, terrain material
and fill, per-field presence/quantity and moisture status. Validation rejects
inconsistent presence vs mask, quantities on non-present fields, habitat boxes
outside their voxel, volume mismatch, out-of-range voxels, mixed slices,
duplicates/unsorted cells and invalid saturation. No store pointer, ChunkView
token, native handle or authority capability is retained. A presentation stays
valid after its source stores are destroyed.
## Freshness and update ordering
`EnvironmentLayer` keeps at most one presentation (no history or queue) and the
newest observed authority revision. `accept` rejects another world/frame
(`foreign_world`) or any regression of tick, field watermark or a shared voxel's
chunk revision (`regressed`) without mutation. Equal revisions are accepted so a
camera-driven footprint change can replace the cells. `observe` records the
authority's latest revision (also before the first presentation); a regressed or
foreign watermark rejects. Freshness is:
| State | Meaning | Presentation |
|---|---|---|
| none | nothing accepted (or reset) | red chip, no cells |
| current | presentation equals newest observed revision | green chip |
| stale | authority advanced, or host validation failed (`mark_stale`) | amber chip, dimmed fills, amber voxel outlines |
A late presentation newer than the displayed one but older than the observed
watermark is accepted and shown stale. Restore/reconnect requires `reset`;
ADR-0052 restored stores are different owners, so their revisions need not continue.
## Encodings
Each visible cell emits: terrain square (material colour blended from void by fill;
unknown material IDs are cyan), habitat encoding, then a voxel outline when the voxel
is at least 8 logical units wide. Habitat encodings:
| Data | Encoding |
|---|---|
| present, nonzero | ramp(log2(quantity / habitat um^3) mapped from [-30, 12]) |
| present zero | black fill |
| requested but missing | 2x2 magenta/dark checker |
| not requested | hollow grey outline |
| moisture with zero water capacity | rust "undefined" fill |
| moisture available | ramp(saturation) linear in [0, 1] |
Mass is fg, energy pJ; both use density per cubic micrometre of the habitat's
effective volume. Values outside the ramp clamp to its ends; the eight-step legend
(bottom-left) shows the ramp, not physical units. Habitats under 4 logical units
collapse to one rectangle in the encoding's primary colour, so missing remains
magenta and not-requested grey. Nothing is interpolated between habitats and no
value is inferred from material IDs.
## Geometry and resource bounds
Projection uses the CAMERA_INPUT formula on voxel edges, so shared edges between
neighbouring voxels (including signed chunk seams) are computed from identical
world coordinates. Edges may lie on the exclusive world bound. Cells fully outside
the viewport emit nothing; others clip to `[0, width] x [0, height]` before float
conversion. Output is at most `256 * 9 + 9 = 2313` rectangles, within the 4096
frame limit including host UI. `build_environment` clears and reserves the
caller's buffer once; reuse keeps capacity constant. No textures or caches exist.
## Engineering app
`evo-client` hosts a local in-memory fixture authority: 16x8 habitats at z=-16000
with varied boxes, varying water and organic energy, present-zero phosphorus and
never-opened nitrogen/incident energy. Every 60 frames it advances its tick and
moves 1/8 of one site's water to a neighbour through `FieldStore::transfer`.
`--refresh-every N` (1..1000, default 1) refreshes the view every N authority ticks;
between refreshes the observed watermark shows the stale state. `--layer` selects
`water`, `nitrogen`, `phosphorus`, `organic-carbon`, `organic-nitrogen`,
`organic-phosphorus`, `organic-other`, `organic-energy`, `incident-energy`, `heat`
or `moisture`. The fixture is never persisted or published; M9.7 replaces it with
server views. It is not biology, an ecosystem or a world-generation rule.
+60
View File
@@ -3284,3 +3284,63 @@ No full headless suite or TSan rerun; owned client state remains main-thread-onl
No physical keyboard/IME, human visual, real multi-monitor DPI, Wayland or real
GPU-failure qualification is claimed from injected events and Xvfb. No network
traffic, database, world mutation or deployment operation was introduced.
## M9.4 microscopic environment rendering — 2026-10-01
Implemented ADR-0080 and ENVIRONMENT_RENDERING.md: owned revision-tagged
`EnvironmentPresentation` copied from M6.3 views (no tokens/store pointers),
single-slot `EnvironmentLayer` ordering/freshness, and bounded camera-projected
rendering with explicit missing, not-requested, present-zero, undefined-moisture
and stale encodings. The app shows a local in-memory fixture authority (finite
same-channel water moves via `FieldStore::transfer`); it is not a server view.
Executed:
- Windows MSVC 19.44 Release via `tools/windows-check.ps1 -Preset client -Action
check` (run as a child `powershell.exe`): 4/4 labeled tests, including the new
`client-environment` suite. App runs with `--frames 240/300`, `--refresh-every
2`, `--layer organic-carbon` exited 0; `--layer bogus` exited 2;
`SDL_VIDEO_DRIVER=evo-invalid` still fails at SDL initialization (error 2),
after fixture creation, so `client-init-failure` keeps testing the SDL path.
- Linux GCC 14 Release (`build/client-probe-linux`, probe + client): 6/6 labeled
tests; native Xvfb/X11 lifecycle suite; X11 app runs (moisture, refresh 3).
- Clang 19 Debug ASan/UBSan (`build/client-asan`): 4/4 labeled tests, native X11
lifecycle, hidden X11 app (refresh 2), visible X11 moisture app and dummy-driver
nitrogen app (400 frames, refresh 3) with leak detection, no suppressions.
- clang-tidy 19 with warnings-as-errors on the four new/changed translation units:
passed after reserving a test vector, widening a test product, and annotating
two intentional out-of-range enum inputs (the rejection under test).
Repository-wide clang-format 19 check passed.
- Tests cover: synthetic known fields (exact ramp colour for log2 density -3,
present zero, missing checker geometry, hollow unrequested outline, undefined
zero-capacity moisture, collapsed small habitats); seams across chunk
boundaries -16/0/16 at three zooms, three centres and two DPI ratios, compared
with `Camera::world_to_screen`; voxels on the exclusive world bound; stale
updates (older tick, chunk-revision regression, foreign world, regressed and
pre-presentation watermarks, late-but-stale presentations, reset); failed
local validation after a field transfer; unchanged field/terrain snapshots
after presenting/rendering; presentations outliving their stores; 20 invalid
presentation shapes; 330 camera/mode/freshness combinations over 256 cells,
all within viewport, the 2313 bound, constant buffer capacity and Frame
limits including host UI.
- Profile (`environment_profile`, 256 visible cells, stale, nitrogen layer,
checker detail): 1701 rectangles; 53,248 presentation-cell bytes; 46,260-byte
reused output buffer; mean build 13.4 us (MSVC Release, this workstation),
6.6 us (GCC 14 Release, WSL2), 175 us (Clang ASan Debug). Indicative only; no
frame-time threshold is claimed.
- Visual sanity check: the fixture's output was rasterized offline for water,
stale, nitrogen (missing), moisture and organic-carbon (not requested). This
raised the not-requested outline from grey 140 to 210 for contrast with rock.
This is not human/colour-vision acceptance.
- Headless: a fresh MSVC Release directory with both client options OFF built
`evo-sim`; seed 123456 / eight entities / 1000 ticks replayed with unchanged
`d61ad5bf0c928c76`, `replay_verified=true`.
Limits: pre-existing `build/release` failed to link untouched headless objects
(unresolved MSVC STL `__std_rotate`/`__std_find_first_not_of_trivial_pos_1`),
consistent with stale objects from a different STL build; the fresh directory
above passed, and that directory was left as found. Docker/Gitea execution of the
extended `ci-client` stage was not observed locally. No full headless suite or
TSan rerun (headless sources unchanged; client state is main-thread-only). No
physical DPI, real GPU, Wayland, accessibility or human visual acceptance is
claimed. No network traffic, database, deployment or persistent format changed.