feat(simulation): zoom-ladder foundations — derive_at_metres, window par_iter, granularity carrier (T-1149/T-1151/T-1150) #191

2026-07-22T00:28:41+02:00

jpmschweitzer commented

2026-07-22 00:28:41 +02:00

Summary

Zoom-ladder foundations — migration steps 1–3 of the T-1143 design pass (docs/architecture/atlas-zoom-ladder-t1143.md §8), implementing the D-166 2026-07-21 amendment's Phase-4 ladder condition. Three tickets in dependency order: T-1149 (keystone), T-1151, T-1150.

T-1149 — `derive_at_metres` + octave cutoff (the keystone)

derive_district's fractional-metres interior is now the metres-addressable derive_at_metres(..., wx, wy, ..., min_wavelength_m); derive_district is a thin DistrictPos-quantizing wrapper calling it with cutoff 0.0. All four golden/believability/derivation harnesses pass byte-identical — the acceptance bar for the extraction. enveloped_fbm/terrain_detail/voxel_relief gain the min_wavelength_m cutoff (octaves below it skipped, amplitude weighting preserved, norm==0 guarded); cutoff 0.0 is asserted bit-identical to pre-change output. Hard truncate only — the amplitude-fade-near-cutoff refinement is a documented seam pending T-1153's visual A/B, not speculative code.

Measured (release, 4096-cell sweeps, new server/tests/zoom_ladder_bench.rs, run with --ignored): district spacing 1.200 µs/cell; quarter spacing with 512 m cutoff 1.165 µs/cell. This replaces the design doc's "contested — unmodified pipeline" numbers with cutoff-active measurements; they land inside the doc's ~1.2–1.4 µs/cell release estimate.

T-1151 — window build parallelization

build_district_window_layer dispatches one Rayon task per row over a pure derive_window_cell, scattered row-major. A cfg(test) serial path backs the bit-identical parallel-vs-serial golden.

T-1150 — granularity carrier (five touch points + aliasing tests)

#[serde(default)] window_granularity (1 = district, 4 = quarter) and window_min_wl_m on AtlasLayerRequest — additive, no sixth demux shape; an old frame without the fields decodes unchanged (tested). Quarter mode is Option B full reclassification at 512 m over the same world rect ((4n)×(4n) cells); WIRE_CAP_CELLS = 4096 clamps quarter n to 16 (the design doc's worked example — the first draft said 32 and a failing test caught it).

The design pass's five aliasing touch points all carry granularity + min_wl: layer echo fields, server FIFO-256 cache key (5-tuple), per-connection coalescing key, client request codec (fields omitted at default for byte-compat), client LRU key. The mandated aliasing regressions exist on both ends: identical (body, center, n) at granularity 1 vs 4 → distinct server cache entries with correct per-granularity payload shapes, and distinct client cache keys (gdUnit). Writing the server test surfaced a real queue-contention subtlety (the whole-body AnalyzeBody item competes with both DeriveWindow items — test uses a 3-thread queue).

Client requests stay district-granularity by default; quarter requests arrive with T-1153's rung selection.

Fixture note

client/tests/fixtures/msgpack/atlas_response_ready_with_window.msgpack regenerated (231→254 bytes) — the layer struct grew two echoed fields; content verified (granularity: 1, min_wl_m: 0). server/tests/gen_fixtures.rs updated to match the new struct shape.

Verification

Golden harnesses byte-identical: believability, cascade layer0→1, seed determinism, proof-room tick-10, all 37 derivation-harness tests, bridge_tcp.
cargo test --lib 1798/1798; full suites via the pre-push gate.
gdlint zero warnings on all touched GDScript; cold parse clean (fresh import).

Tickets: T-1149, T-1150, T-1151

## Summary Zoom-ladder foundations — migration steps 1–3 of the T-1143 design pass (`docs/architecture/atlas-zoom-ladder-t1143.md` §8), implementing the D-166 2026-07-21 amendment's Phase-4 ladder condition. Three tickets in dependency order: **T-1149** (keystone), **T-1151**, **T-1150**. ### T-1149 — `derive_at_metres` + octave cutoff (the keystone) `derive_district`'s fractional-metres interior is now the metres-addressable `derive_at_metres(..., wx, wy, ..., min_wavelength_m)`; `derive_district` is a thin DistrictPos-quantizing wrapper calling it with cutoff 0.0. **All four golden/believability/derivation harnesses pass byte-identical** — the acceptance bar for the extraction. `enveloped_fbm`/`terrain_detail`/`voxel_relief` gain the `min_wavelength_m` cutoff (octaves below it skipped, amplitude weighting preserved, `norm==0` guarded); cutoff 0.0 is asserted bit-identical to pre-change output. Hard truncate only — the amplitude-fade-near-cutoff refinement is a documented seam pending T-1153's visual A/B, not speculative code. **Measured** (release, 4096-cell sweeps, new `server/tests/zoom_ladder_bench.rs`, run with `--ignored`): district spacing **1.200 µs/cell**; quarter spacing with 512 m cutoff **1.165 µs/cell**. This replaces the design doc's "contested — unmodified pipeline" numbers with cutoff-active measurements; they land inside the doc's ~1.2–1.4 µs/cell release estimate. ### T-1151 — window build parallelization `build_district_window_layer` dispatches one Rayon task per row over a pure `derive_window_cell`, scattered row-major. A `cfg(test)` serial path backs the **bit-identical parallel-vs-serial golden**. ### T-1150 — granularity carrier (five touch points + aliasing tests) `#[serde(default)] window_granularity` (1 = district, 4 = quarter) and `window_min_wl_m` on `AtlasLayerRequest` — additive, no sixth demux shape; an old frame without the fields decodes unchanged (tested). Quarter mode is Option B full reclassification at 512 m over the same world rect ((4n)×(4n) cells); `WIRE_CAP_CELLS = 4096` clamps quarter `n` to 16 (the design doc's worked example — the first draft said 32 and a failing test caught it). The design pass's five aliasing touch points all carry granularity + min_wl: layer echo fields, server FIFO-256 cache key (5-tuple), per-connection coalescing key, client request codec (fields omitted at default for byte-compat), client LRU key. **The mandated aliasing regressions exist on both ends**: identical `(body, center, n)` at granularity 1 vs 4 → distinct server cache entries with correct per-granularity payload shapes, and distinct client cache keys (gdUnit). Writing the server test surfaced a real queue-contention subtlety (the whole-body `AnalyzeBody` item competes with both `DeriveWindow` items — test uses a 3-thread queue). Client requests stay district-granularity by default; quarter requests arrive with T-1153's rung selection. ### Fixture note `client/tests/fixtures/msgpack/atlas_response_ready_with_window.msgpack` regenerated (231→254 bytes) — the layer struct grew two echoed fields; content verified (`granularity: 1, min_wl_m: 0`). `server/tests/gen_fixtures.rs` updated to match the new struct shape. ### Verification - Golden harnesses byte-identical: believability, cascade layer0→1, seed determinism, proof-room tick-10, all 37 derivation-harness tests, `bridge_tcp`. - `cargo test --lib` 1798/1798; full suites via the pre-push gate. - gdlint zero warnings on all touched GDScript; cold parse clean (fresh import). Tickets: T-1149, T-1150, T-1151

jpmschweitzer added 2 commits 2026-07-22 00:28:41 +02:00

feat(simulation): T-1149 derive_at_metres extraction + min_wavelength octave cutoff afff859a2c

Extract derive_district's fractional-metres interior into the metres-
addressable derive_at_metres(seed, body, params, ta, wx, wy, climate,
min_wavelength_m) — the zoom ladder's keystone (design doc §8 step 1).
derive_district is now a thin DistrictPos-quantizing wrapper calling it
with cutoff 0.0; all four golden/believability/derivation harnesses pass
byte-identical.

enveloped_fbm/terrain_detail/voxel_relief gain min_wavelength_m: octaves
below the cutoff are hard-truncated (amp still advances so surviving
octaves keep relative weight; norm==0 guarded). Amplitude-fade-near-
cutoff is documented as a seam, not built — the pop-risk A/B needs the
client ladder (T-1153). Cutoff 0.0 is bit-identical to pre-change
output, asserted by test.

Measured (release, 4096-cell sweeps, zoom_ladder_bench.rs): district
spacing 1.200µs/cell (cutoff 0) / 1.201µs (cutoff 2048m — all octaves
survive, plumbing check); quarter spacing 1.165µs/cell (cutoff 512m).
Matches the design doc's ~1.2-1.4µs/cell release estimate.

feat(simulation): T-1151 window par_iter + T-1150 granularity carrier (five touch points + aliasing tests) 3e87fd5b4f

T-1151: build_district_window_layer dispatches one Rayon task per row
(pure derive_window_cell via derive_at_metres), scattered row-major into
the flat arrays; a cfg(test) serial path backs the bit-identical
parallel-vs-serial golden.

T-1150: serde-default window_granularity (1=district, 4=quarter) +
window_min_wl_m on AtlasLayerRequest — additive, no sixth demux shape,
old frames decode unchanged (tested). Quarter mode = full
reclassification at 512m spacing over the same world rect ((4n)x(4n)
cells); WIRE_CAP_CELLS=4096 enforces n*granularity <= cap (quarter
clamps n to 16, the design doc's worked example). Granularity + min_wl
key ALL five touch points: DistrictWindowLayer echo, server FIFO-256
cache key (now a 5-tuple), per-connection coalescing key, client
request codec (omitted-at-default wire fields), client LRU key.

Mandatory aliasing regressions on both ends: identical (body, center, n)
at granularity 1 vs 4 produce distinct cache entries and correct
per-granularity payload shapes (server, 3-thread queue to avoid the
AnalyzeBody thread contention found while writing it) and distinct
client cache keys (gdUnit). Replay fixture regenerated — the layer
struct grew two echoed fields (231->254 bytes, content verified).

Client requests stay district-granularity by default — quarter requests
arrive with T-1153's rung selection.

jpmschweitzer referenced this issue from a commit

2026-07-22 00:54:04 +02:00

fix(simulation): PR #191 review round — n-clamp mirror, min_wl band quantization, coalescing coverage, fixture consumer

jpmschweitzer added 2 commits 2026-07-22 00:54:04 +02:00

fix(simulation): PR #191 review round — n-clamp mirror, min_wl band quantization, coalescing coverage, fixture consumer 0159a63cc2

All seven Hoshe/Tyre findings addressed, none retracted:
- n-clamp/echo/staleness triangle (Tyre C1): client _clamp_window_n_mirror
  (bit-for-bit twin of the server clamp, canonicalize_district_center
  precedent) applied before _n is stored/sent; server test pins the
  quarter n=32 -> echo 16 contract.
- min_wl band quantization (Hoshe 1/Tyre C3): quantize_min_wl_m snaps to
  MIN_WL_BANDS_M {0, 32768, 16384, 8192, 4096} before cache key and echo
  (design doc §5's unbounded-key fix), reusing the one true
  OCTAVE_WAVELENGTHS_M array; docstrings now state the server-quantizes/
  client-sends-raw split; same-band cache-sharing test.
- coalescing granularity axis (Hoshe 2): two tests pin different-
  granularity requests as separate in-flight slots and same-granularity
  coalescing unchanged.
- orphaned fixture (Hoshe 3): test_protocol.gd consumer decodes
  atlas_response_ready_with_window.msgpack through the real IPC path and
  asserts the new fields.
- atlas_window_request coverage (Hoshe 4): new test file — stale-drop on
  granularity mismatch, old-server-shape defaults accepted, clamp mirror
  formula + wiring. First draft's quarter-via-request_now test would have
  passed for the wrong reason (request_now resets granularity by design
  until T-1153) — split into formula pin + reachable-path wiring proof.
- granularity type seam (Tyre C2): field + resolver docstrings state
  finer-only integer multiples with resolve_window_granularity as the
  single widening point; matching contract note added to the D-226
  T-1143-rulings amendment.

cargo --lib 1807/1807; goldens bit-identical; gdlint clean.

style(simulation): cargo fmt on the fix round + governance amendment typo (Hoshe nit) 1ce4085901

jpmschweitzer commented

2026-07-22 00:54:09 +02:00

Review: zoom-ladder-foundations → main (type: code)

Reviewers: Hoshe (code quality / QA) + Tyre (architecture). Both reviewed at 3e87fd5b4; fix round 0159a63cc (+ fmt/typo 1ce408590) re-confirmed by both.

Hoshe (QA): APPROVE (after fix round)

Initial verdict REQUEST_CHANGES — bit-identity, five-touch-point, clamp-boundary, and parallel-determinism claims all verified directly (including hand-checking the n=17 quarter-clamp boundary); four findings, all fixed, none retracted:

#	Location	Issue	Resolution
1	layer_proxy.rs serve_district_window	`min_wl_m` was an unclamped wire passthrough — design doc §5's band quantization silently scope-cut, reopening the unbounded-cache-key thrash it exists to close	`quantize_min_wl_m` snaps to `MIN_WL_BANDS_M` (aligned to the now-`pub(crate)` `OCTAVE_WAVELENGTHS_M` — one true array) before cache key AND echo; 6 tests incl. same-band-shares-one-cache-entry
2	gen_queue.rs window_supersede_key	Coalescing key's new granularity axis had zero test coverage despite a specific doc claim	Two tests: different granularity → 2 in-flight slots; same → still coalesces to 1
3	atlas_response_ready_with_window.msgpack	Regenerated fixture had NO consumer anywhere in client/tests — silent bit-rot	test_protocol.gd decodes it through the real IPC path and asserts the new fields
4	atlas_window_request.gd	The staleness guard — the function that actually consumes the echo — had no test file at all	New test_atlas_window_request.gd: granularity-mismatch stale-drop, old-server-shape defaults-accepted with cache-hit proof, clamp-mirror formula + wiring

Re-confirmation rigor: ran the suites live (1807/1807 lib, 593/593 atlas, exactly +9 expected tests), hand-checked quantize_min_wl_m tie-breaks at band midpoints, and ran the client clamp mirror against the server formula across 200k randomized (raw_n, granularity) pairs — zero mismatches. Accepted Dudley's disclosed test-scoping deviation (quarter isn't requestable through request_now until T-1153 — a literal test would have exercised an unreachable path; his first draft did exactly that and he caught it himself).

Tyre (Architecture): APPROVE (after fix round)

Initial verdict REQUEST_CHANGES — "polish and forward-safety, not correctness of what ships"; three findings, all fixed, none retracted:

#	Location	Issue	Resolution
C1	serve_district_window ↔ atlas_window_request.gd	n-clamp/echo/staleness triangle: a quarter n=32 request would echo the clamped n=16 and be silently dropped as stale — "window never loads," armed for T-1153	Client `_clamp_window_n_mirror` (bit-for-bit twin, canonicalize_district_center precedent) applied before `_n` is stored/sent in both request paths; server test pins quarter n=32 → echo 16 through a real handle_atlas_request
C2	window_granularity type	u32 encoding silent about the rungs Jeroen's floor ruling unlocked and the coarser-than-district direction (design risk R5)	Contract stated in the field doc, the resolver doc (single widening point, coarser-direction prohibition → R5 redesign), and a matching governance line on the D-226 T-1143-rulings amendment
C3	window_min_wl_m doc	§5 band-quantization dropped silently	Superseded by Hoshe #1's full implementation — "went past my minimum ask; removes the T-1153 cache-thrash hazard entirely rather than deferring it"

Confirmed-good for the record: coalescing extension is the §3 progressive-refinement behavior (one in-flight slot per rung), determinism discipline clean (no f32 on the wire, order-preserving par_iter with serial golden twin), helper layering right for T-1152/T-1153, R2 stepped-temperature documented at the code site.

Verdict: APPROVED

Verification: goldens byte-identical across the extraction (believability, cascade, seed-determinism, proof-room, 37 derivation-harness tests); full gdUnit 3396/3396; cargo --lib 1807/1807; measured costs land inside the design doc's release estimate (district 1.200 µs/cell, quarter 1.165 µs/cell with 512 m cutoff), replacing the doc's "contested" figures. One gate bounce (cargo fmt on fix-round test code) auto-fixed.

Tickets: T-1149, T-1150, T-1151

# Review: zoom-ladder-foundations → main (type: code) Reviewers: Hoshe (code quality / QA) + Tyre (architecture). Both reviewed at `3e87fd5b4`; fix round `0159a63cc` (+ fmt/typo `1ce408590`) re-confirmed by both. ## Hoshe (QA): APPROVE (after fix round) Initial verdict REQUEST_CHANGES — bit-identity, five-touch-point, clamp-boundary, and parallel-determinism claims all verified directly (including hand-checking the n=17 quarter-clamp boundary); four findings, all fixed, none retracted: | # | Location | Issue | Resolution | |---|----------|-------|------------| | 1 | layer_proxy.rs serve_district_window | `min_wl_m` was an unclamped wire passthrough — design doc §5's band quantization silently scope-cut, reopening the unbounded-cache-key thrash it exists to close | `quantize_min_wl_m` snaps to `MIN_WL_BANDS_M` (aligned to the now-`pub(crate)` `OCTAVE_WAVELENGTHS_M` — one true array) before cache key AND echo; 6 tests incl. same-band-shares-one-cache-entry | | 2 | gen_queue.rs window_supersede_key | Coalescing key's new granularity axis had zero test coverage despite a specific doc claim | Two tests: different granularity → 2 in-flight slots; same → still coalesces to 1 | | 3 | atlas_response_ready_with_window.msgpack | Regenerated fixture had NO consumer anywhere in client/tests — silent bit-rot | test_protocol.gd decodes it through the real IPC path and asserts the new fields | | 4 | atlas_window_request.gd | The staleness guard — the function that actually consumes the echo — had no test file at all | New test_atlas_window_request.gd: granularity-mismatch stale-drop, old-server-shape defaults-accepted with cache-hit proof, clamp-mirror formula + wiring | Re-confirmation rigor: ran the suites live (1807/1807 lib, 593/593 atlas, exactly +9 expected tests), hand-checked `quantize_min_wl_m` tie-breaks at band midpoints, and ran the client clamp mirror against the server formula across **200k randomized (raw_n, granularity) pairs — zero mismatches**. Accepted Dudley's disclosed test-scoping deviation (quarter isn't requestable through `request_now` until T-1153 — a literal test would have exercised an unreachable path; his first draft did exactly that and he caught it himself). ## Tyre (Architecture): APPROVE (after fix round) Initial verdict REQUEST_CHANGES — "polish and forward-safety, not correctness of what ships"; three findings, all fixed, none retracted: | # | Location | Issue | Resolution | |---|----------|-------|------------| | C1 | serve_district_window ↔ atlas_window_request.gd | n-clamp/echo/staleness triangle: a quarter n=32 request would echo the clamped n=16 and be silently dropped as stale — "window never loads," armed for T-1153 | Client `_clamp_window_n_mirror` (bit-for-bit twin, canonicalize_district_center precedent) applied before `_n` is stored/sent in both request paths; server test pins quarter n=32 → echo 16 through a real handle_atlas_request | | C2 | window_granularity type | u32 encoding silent about the rungs Jeroen's floor ruling unlocked and the coarser-than-district direction (design risk R5) | Contract stated in the field doc, the resolver doc (single widening point, coarser-direction prohibition → R5 redesign), and a matching governance line on the D-226 T-1143-rulings amendment | | C3 | window_min_wl_m doc | §5 band-quantization dropped silently | Superseded by Hoshe #1's full implementation — "went past my minimum ask; removes the T-1153 cache-thrash hazard entirely rather than deferring it" | Confirmed-good for the record: coalescing extension is the §3 progressive-refinement behavior (one in-flight slot per rung), determinism discipline clean (no f32 on the wire, order-preserving par_iter with serial golden twin), helper layering right for T-1152/T-1153, R2 stepped-temperature documented at the code site. ## Verdict: APPROVED Verification: goldens byte-identical across the extraction (believability, cascade, seed-determinism, proof-room, 37 derivation-harness tests); full gdUnit 3396/3396; cargo --lib 1807/1807; measured costs land inside the design doc's release estimate (district 1.200 µs/cell, quarter 1.165 µs/cell with 512 m cutoff), replacing the doc's "contested" figures. One gate bounce (cargo fmt on fix-round test code) auto-fixed. Tickets: T-1149, T-1150, T-1151

jpmschweitzer closed this pull request

2026-07-22 00:54:52 +02:00

jpmschweitzer referenced this issue from a commit

2026-07-22 00:58:25 +02:00

chore(meta): T-1149/T-1150/T-1151 to review — PR #191 up (zoom-ladder foundations)

jpmschweitzer referenced this issue from a commit

2026-07-22 00:58:25 +02:00

chore(meta): zoom-ladder foundations done — T-1149/T-1150/T-1151 closed (PR #191 merged, double review + fix round); T-1152/T-1153/T-1154 now unblocked

jpmschweitzer referenced this issue from a commit

2026-07-22 16:50:30 +02:00

fix(client): T-1153 — clamp _held_n at the viewer's single write site (live eyeball round blocker)

jpmschweitzer referenced this issue from a commit