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
+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.