feat(simulation): bmv workshop gate measurements + hydrology prototype #198

2026-07-23T19:27:56+02:00

jpmschweitzer commented

2026-07-23 19:27:56 +02:00

Summary

The body-map-viewer workshop gate measurements (brief appendix ①–⑤): the batch that had to land before workshop round 1, per the measurement-gated format Jeroen signed off. Every number MEASURED (release, 16-core/Rayon 14/RX 9070), nothing extrapolated — the T-1143 planetary-rung post-mortem is cited in-doc as the cautionary tale. All timings post-date a background-load closure (Factorio) with stability re-runs; each doc carries the environment note.

① T-1177 — equilibrium hydrology solver prototype (`server/src/atlas/hydrology_equilibrium.rs`)

Priority-flood fill + basin grouping + topographic-saddle spill points + moisture-governed endorheic classification (reuses the reserved RIVER_DOWNSTREAM_TERMINAL sentinel) + Dijkstra overflow/carving. Pure function, deterministic (D-010), no stateful sim — 15 unit tests incl. byte-identity determinism proofs. Verdict: settled hydrology VIABLE — 512×256 ~24 ms/body; all 273 bodies Rayon-parallel ~0.7–0.8 s; 8.3M cells ~5.7 s single-thread (no production path needs it synchronously). Cliff representation delivered (red flag 4): dominant height + channel_depth + cliff_edge. Finding: gorge carving is structurally rare — priority-flood finds true spill levels; zero carved cells at production scales (investigated, explained in-doc, workshop question).

② T-1178 — production-path derive at real canvas sizes (`server/tests/bmv_gridunit_bench.rs`)

Parallel throughput HOLDS: ~190–220 ns/cell flat from 330K→8.3M cells through the real build_district_window_layer (called above the wire clamp — the clamp lives in the caller). 330K ≈ 64 ms, 2.07M ≈ 0.4 s, 8.3M ≈ 1.7–1.8 s (7.5–8.8×). Single-thread flat ~1.65 µs/cell, matches the prior 4,096-cell baseline within 8%. Cross-validated on three bodies (incl. real courses).

③ T-1154 — block/tile rung costs (same bench file)

Block/tile ≈ 1.8–1.9 µs/cell — same band as District/Quarter; verified: the octave cutoff buys ZERO below District spacing (wavelength table bottoms at 128 m). Deepest-step realistic canvas (216×384 m @ 1 m = 83K cells): ~17 ms parallel. voxel_relief already in the Atlas path; voxel_mosaic untouched by it. Go/no-go: Block GO; Tile GO on cost, conditional on viewport-sized canvases (the D-226(d) governance boundary, not a cost limit).

④ T-1179 — wire-size encoding table (`server/tests/wire_encoding_bench.rs`)

Real GJ338Bd canvases, five encodings, measured round-trips. PNG-per-field wins everywhere (330K: 638 KB = 0.32× raw, and fastest at 5.4/3.6 ms enc/dec); RLE loses to raw (elev/temp near-noise per cell). The tagged-envelope migration is foreclosed as necessary: best case is 21× the 30 KB windowed ceiling at the smallest size (563× at 8.3M). Corrected measured density: 6.00 B/cell raw rmp (docs claimed 7).

⑤ T-1180 — Godot ImageTexture upload (windowed, RX 9070)

Non-issue: 8.3M px RGBA8 create ≈ 3.2 ms median, ~2.4–2.9 ms frame-delta spike — never near the 16.6 ms budget. L8 is 4–9× cheaper at every size. Recommendation: texture.update reuse on step-cross; L8 for single-channel planes. (Headless renderer fakes uploads — windowed-only measurement, documented.)

Deliverables

Four results docs under docs/workshops/body-map-viewer/measurements/ + the brief's measurement appendix rewritten from owners/effort to MEASURED headlines. The workshop round-1 gate is satisfied — /workshop-start body-map-viewer unblocks on merge (T-1176's four blocker edges close with these tickets).

Verification

Full gate green on push: fmt, clippy -D warnings, cargo test (1893 lib + all integration binaries), cargo deny. New bench code is all #[ignore]d release tests — zero impact on the regular suite. Hydrology determinism proved twice (unit + at-scale). pql store integrity verified post-batch via full pql plan rebuild + byte-identical diff.

Tickets: T-1177, T-1178, T-1154, T-1179, T-1180.

## Summary The **body-map-viewer workshop gate measurements** (brief appendix ①–⑤): the batch that had to land before workshop round 1, per the measurement-gated format Jeroen signed off. Every number MEASURED (release, 16-core/Rayon 14/RX 9070), nothing extrapolated — the T-1143 planetary-rung post-mortem is cited in-doc as the cautionary tale. All timings post-date a background-load closure (Factorio) with stability re-runs; each doc carries the environment note. ### ① T-1177 — equilibrium hydrology solver prototype (`server/src/atlas/hydrology_equilibrium.rs`) Priority-flood fill + basin grouping + topographic-saddle spill points + moisture-governed endorheic classification (reuses the reserved `RIVER_DOWNSTREAM_TERMINAL` sentinel) + Dijkstra overflow/carving. Pure function, deterministic (D-010), no stateful sim — 15 unit tests incl. byte-identity determinism proofs. **Verdict: settled hydrology VIABLE** — 512×256 ~24 ms/body; all 273 bodies Rayon-parallel ~0.7–0.8 s; 8.3M cells ~5.7 s single-thread (no production path needs it synchronously). **Cliff representation delivered** (red flag 4): dominant height + `channel_depth` + `cliff_edge`. **Finding:** gorge carving is structurally rare — priority-flood finds true spill levels; zero carved cells at production scales (investigated, explained in-doc, workshop question). ### ② T-1178 — production-path derive at real canvas sizes (`server/tests/bmv_gridunit_bench.rs`) **Parallel throughput HOLDS**: ~190–220 ns/cell flat from 330K→8.3M cells through the real `build_district_window_layer` (called above the wire clamp — the clamp lives in the caller). 330K ≈ 64 ms, 2.07M ≈ 0.4 s, 8.3M ≈ 1.7–1.8 s (7.5–8.8×). Single-thread flat ~1.65 µs/cell, matches the prior 4,096-cell baseline within 8%. Cross-validated on three bodies (incl. real courses). ### ③ T-1154 — block/tile rung costs (same bench file) Block/tile ≈ 1.8–1.9 µs/cell — same band as District/Quarter; **verified: the octave cutoff buys ZERO below District spacing** (wavelength table bottoms at 128 m). Deepest-step realistic canvas (216×384 m @ 1 m = 83K cells): **~17 ms parallel**. `voxel_relief` already in the Atlas path; `voxel_mosaic` untouched by it. **Go/no-go: Block GO; Tile GO on cost, conditional on viewport-sized canvases** (the D-226(d) governance boundary, not a cost limit). ### ④ T-1179 — wire-size encoding table (`server/tests/wire_encoding_bench.rs`) Real GJ338Bd canvases, five encodings, measured round-trips. **PNG-per-field wins everywhere** (330K: 638 KB = 0.32× raw, and fastest at 5.4/3.6 ms enc/dec); RLE loses to raw (elev/temp near-noise per cell). **The tagged-envelope migration is foreclosed as necessary**: best case is 21× the 30 KB windowed ceiling at the smallest size (563× at 8.3M). Corrected measured density: 6.00 B/cell raw rmp (docs claimed 7). ### ⑤ T-1180 — Godot ImageTexture upload (windowed, RX 9070) **Non-issue**: 8.3M px RGBA8 create ≈ 3.2 ms median, ~2.4–2.9 ms frame-delta spike — never near the 16.6 ms budget. **L8 is 4–9× cheaper at every size.** Recommendation: `texture.update` reuse on step-cross; L8 for single-channel planes. (Headless renderer fakes uploads — windowed-only measurement, documented.) ### Deliverables Four results docs under `docs/workshops/body-map-viewer/measurements/` + the brief's measurement appendix rewritten from owners/effort to MEASURED headlines. **The workshop round-1 gate is satisfied** — `/workshop-start body-map-viewer` unblocks on merge (T-1176's four blocker edges close with these tickets). ### Verification Full gate green on push: fmt, clippy `-D warnings`, `cargo test` (1893 lib + all integration binaries), cargo deny. New bench code is all `#[ignore]`d release tests — zero impact on the regular suite. Hydrology determinism proved twice (unit + at-scale). pql store integrity verified post-batch via full `pql plan rebuild` + byte-identical diff. Tickets: T-1177, T-1178, T-1154, T-1179, T-1180.

jpmschweitzer added 4 commits 2026-07-23 19:27:56 +02:00

feat(simulation): equilibrium hydrology solver prototype + bench (T-1177) 05f9630cb4

Priority-flood fill with basin grouping, topographic-saddle spill points,
moisture-governed endorheic classification (reuses the reserved
RIVER_DOWNSTREAM_TERMINAL sentinel), and Dijkstra overflow/carving. Pure
function of (elevation, sea_level, climate) — deterministic per D-010, no
stateful simulation. 15 unit tests incl. determinism proofs and direct
carving-mechanism verification; #[ignore]d release benches at 512x256 /
768x432 / 3840x2160 plus the 273-bodies-parallel production shape.

Workshop gate measurement (1) for body-map-viewer: settled hydrology is
VIABLE per body-open (~24 ms at 512x256; ~0.7-0.8 s all 273 bodies).

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

test(simulation): gridunit derive + wire encoding benches (T-1178, T-1154, T-1179) 53a4c65d62

bmv_gridunit_bench: production build_district_window_layer par_iter path at
330K/2.07M/8.3M cells (throughput holds, ~190-220 ns/cell parallel), block
(128m) and tile (1m/4m) spacing costs, the 83K-cell deepest-step viewport
shape, and the verified zero-savings octave-cutoff finding below District
spacing. wire_encoding_bench: real GJ338Bd derived canvases through
derive_at_metres, five encodings (raw rmp / bit-packed / RLE / PNG-per-field
/ PNG-of-packed) with measured bytes + encode/decode round-trips; corrected
raw density 6.00 B/cell. All #[ignore]d release tests.

Workshop gate measurements (2)(3)(4) for body-map-viewer.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

docs(meta): body-map-viewer measurement results + brief appendix (T-1177/T-1178/T-1154/T-1179/T-1180) 473b654787

Four results docs under docs/workshops/body-map-viewer/measurements/ and the
brief's measurement appendix rewritten from owners/effort to MEASURED
headlines: settled hydrology viable (~24 ms/body, 273 bodies ~0.8 s);
parallel derive throughput holds 330K-8.3M cells (~64 ms / ~1.8 s); block+tile
cost-cleared (deepest step 83K cells ~17 ms); PNG-per-field smallest and
fastest with the tagged-envelope migration foreclosed by byte math (21x the
ceiling at the smallest size); texture upload a non-issue (8.3M px ~3.2 ms,
L8 4-9x cheaper). All numbers post-date the background-load closure with
stability re-runs. The workshop round-1 gate is satisfied.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

style(simulation): fmt + clippy fixes for the measurement batch (gate bounce) 976d4016e9

cargo fmt across the four new files; needless_range_loop x2 (enumerate /
iter_mut) and identity_op in hydrology_equilibrium.rs. cargo test was green
on the bounced push — lint-only fixes.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

jpmschweitzer referenced this issue from a commit

2026-07-23 20:00:53 +02:00

fix(simulation): PR #198 review round — spillway split, courses disclosure, appendix fidelity

jpmschweitzer added 1 commit 2026-07-23 20:00:53 +02:00

fix(simulation): PR #198 review round — spillway split, courses disclosure, appendix fidelity 3f6b3ec928

Tyre C2: DownstreamTarget::OpenSpillway added — success (open low ground,
complete carved path) split from EdgeUnreachable (strict search exhaustion);
both doc comments exact; test updated. Tyre C3: determinism docstring
corrected (no BTreeMap; the endorheic f64 gate stated as deterministic-by-
derivation). Hoshe H1: vacuous cliff_edge test replaced by
single_basin_bowl_never_carves_a_gorge asserting the known-empty outcome.
Hoshe H2/H3: courses-force-empty disclosure at rect_window_replica and in
the results doc; courses.len() print added to the square production-fn
bench — measured 3/6/10 courses in window (NOT courses-empty, verified
twice); 'faithful stand-in' claim retracted for a precise scope statement;
GJ1c 18-course run identified as the sole production-density rate. Tyre C1:
appendix (4) headline rephrased — the tagged-envelope migration cannot be
dodged by payload optimization (byte math), field-count-rule trigger is a
workshop synthesis call; appendix (2) scope split per-shape.

Hydrology unit suite 15/15; atlas lib suite 679 green; benches compile.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

jpmschweitzer commented

2026-07-23 20:04:17 +02:00

Review: bmv-measurements → main (type: code)

Branch tip reviewed: 3f6b3ec92 (fix round included). Reviewers: Hoshe (QA), Tyre (architecture).

Tyre (Architecture): APPROVE (after one fix round)

Initial REQUEST_CHANGES, three findings — all fixed, all re-verified at tip:

C1 (the blocking one, lead-authored): the brief appendix's ④ headline said the tagged-envelope migration was "foreclosed as necessary" — an ambiguous phrase reading as the inversion of the T-1179 doc it summarized, and it connected byte math to the D-226 §2 field-count rule the doc itself had carefully kept separate. Fixed: the headline now states the measured fact (no encoding brings a step canvas near the existing windowed-payload budget — the migration cannot be dodged by payload optimization) and explicitly defers the field-count-rule trigger to workshop synthesis.
C2: DownstreamTarget::EdgeUnreachable collapsed two opposite outcomes (successful open-ground spillway with a real carved path vs genuine search exhaustion) onto one failure-named variant — a semantics conflation feeding directly into the workshop's wire-terminus decision. Fixed: OpenSpillway split out as the explicit success variant; EdgeUnreachable narrowed to strict exhaustion; both doc comments exact; his re-verify confirmed the whole-grid no-boundary case correctly remains EdgeUnreachable.
C3: determinism docstring named an unused BTreeMap and over-claimed "all comparisons integer" past the endorheic f64 gate. Fixed: truthful collection list; the float gate documented as deterministic-by-derivation.

His cleared list (explicitly, against over-rewriting): prototype placement in the production lib is fine as-is (zero non-test callers, documented inert); the drainage.rs fill duplication is justified and convention-coherent; the TERMINAL sentinel proposal is clean per his own T-1170 Ruling 2c; and the zero-gorge finding is a demonstrated structural property of priority-flood, not a bug explained away.

Hoshe (QA): APPROVE (after one fix round)

Initial REQUEST_CHANGES, four findings — all fixed, all re-verified at tip with suites re-run by him (15/15 hydrology, 679/679 atlas lib):

H1: cliff_edge_implies_positive_channel_depth was provably vacuous (its branch never executes on the bowl fixture). Fixed: replaced by single_basin_bowl_never_carves_a_gorge asserting the known-empty outcome directly; the carving invariant stays covered by the direct mechanism test.
H2: every rectangular-canvas bench number ran with courses forced empty (&[]) — excluding the riparian per-cell cost production pays — with zero disclosure in the bench or its doc. Fixed: disclosure at the replica loop's definition, the module doc, the results doc (new "Courses in window" column + dedicated disclosure section), and inline at the 83K deep-step bench, citing the measured excluded cost (+0.09–0.21 ms, <5%).
H3: the square-vs-rectangle "faithful stand-in" convergence claim risked validating courses-empty against courses-empty. Fixed by measurement: courses.len() printed and run twice — the square rows are courses-light (3/6/10 in window, deterministic), so the 0.3% agreement validates loop mechanics; the claim was retracted and replaced with the precise scope, with the GJ1c 18-course run (195.0 ns/cell) identified as the sole production-density rate.
H4: appendix ② claimed "incl. real courses / through the real function" as a blanket over per-shape-different numbers. Fixed: the row now states both call paths, their course densities, and the single production-density measurement.

Verification at tip

Full gate green on push: cargo fmt --check, clippy --all-targets -D warnings, full cargo test (1893 lib + every integration binary), cargo deny. All new bench code #[ignore]d — zero impact on the regular suite. Hydrology determinism proved at unit and at scale. Both reviewers independently re-verified every fix at the tip; Hoshe re-ran the suites himself.

Verdict: APPROVED

Tickets: T-1177, T-1178, T-1154, T-1179, T-1180. The body-map-viewer workshop round-1 measurement gate (①–④, plus non-gating ⑤) is satisfied with honestly-scoped numbers.

## Review: bmv-measurements → main (type: code) Branch tip reviewed: `3f6b3ec92` (fix round included). Reviewers: Hoshe (QA), Tyre (architecture). ### Tyre (Architecture): APPROVE (after one fix round) Initial REQUEST_CHANGES, three findings — all fixed, all re-verified at tip: - **C1 (the blocking one, lead-authored):** the brief appendix's ④ headline said the tagged-envelope migration was "foreclosed as necessary" — an ambiguous phrase reading as the *inversion* of the T-1179 doc it summarized, and it connected byte math to the D-226 §2 *field-count* rule the doc itself had carefully kept separate. Fixed: the headline now states the measured fact (no encoding brings a step canvas near the existing windowed-payload budget — the migration cannot be dodged by payload optimization) and explicitly defers the field-count-rule trigger to workshop synthesis. - **C2:** `DownstreamTarget::EdgeUnreachable` collapsed two opposite outcomes (successful open-ground spillway with a real carved path vs genuine search exhaustion) onto one failure-named variant — a semantics conflation feeding directly into the workshop's wire-terminus decision. Fixed: `OpenSpillway` split out as the explicit success variant; `EdgeUnreachable` narrowed to strict exhaustion; both doc comments exact; his re-verify confirmed the whole-grid no-boundary case correctly remains `EdgeUnreachable`. - **C3:** determinism docstring named an unused `BTreeMap` and over-claimed "all comparisons integer" past the endorheic f64 gate. Fixed: truthful collection list; the float gate documented as deterministic-by-derivation. His cleared list (explicitly, against over-rewriting): prototype placement in the production lib is fine as-is (zero non-test callers, documented inert); the drainage.rs fill duplication is justified and convention-coherent; the TERMINAL sentinel proposal is clean per his own T-1170 Ruling 2c; and the zero-gorge finding is a demonstrated structural property of priority-flood, not a bug explained away. ### Hoshe (QA): APPROVE (after one fix round) Initial REQUEST_CHANGES, four findings — all fixed, all re-verified at tip with suites re-run by him (15/15 hydrology, 679/679 atlas lib): - **H1:** `cliff_edge_implies_positive_channel_depth` was provably vacuous (its branch never executes on the bowl fixture). Fixed: replaced by `single_basin_bowl_never_carves_a_gorge` asserting the known-empty outcome directly; the carving invariant stays covered by the direct mechanism test. - **H2:** every rectangular-canvas bench number ran with courses forced empty (`&[]`) — excluding the riparian per-cell cost production pays — with zero disclosure in the bench or its doc. Fixed: disclosure at the replica loop's definition, the module doc, the results doc (new "Courses in window" column + dedicated disclosure section), and inline at the 83K deep-step bench, citing the measured excluded cost (+0.09–0.21 ms, <5%). - **H3:** the square-vs-rectangle "faithful stand-in" convergence claim risked validating courses-empty against courses-empty. Fixed by measurement: `courses.len()` printed and run twice — the square rows are courses-light (3/6/10 in window, deterministic), so the 0.3% agreement validates loop mechanics; the claim was retracted and replaced with the precise scope, with the GJ1c 18-course run (195.0 ns/cell) identified as the sole production-density rate. - **H4:** appendix ② claimed "incl. real courses / through the real function" as a blanket over per-shape-different numbers. Fixed: the row now states both call paths, their course densities, and the single production-density measurement. ### Verification at tip Full gate green on push: `cargo fmt --check`, `clippy --all-targets -D warnings`, full `cargo test` (1893 lib + every integration binary), cargo deny. All new bench code `#[ignore]`d — zero impact on the regular suite. Hydrology determinism proved at unit and at scale. Both reviewers independently re-verified every fix at the tip; Hoshe re-ran the suites himself. ### Verdict: APPROVED Tickets: T-1177, T-1178, T-1154, T-1179, T-1180. The body-map-viewer workshop round-1 measurement gate (①–④, plus non-gating ⑤) is satisfied with honestly-scoped numbers.

jpmschweitzer closed this pull request

2026-07-23 20:06:11 +02:00

jpmschweitzer referenced this issue from a commit

2026-07-23 20:06:34 +02:00

chore(meta): close bmv measurement batch — T-1177/T-1178/T-1154/T-1179/T-1180 done (PR #198 merged, dual review, one fix round); T-1176 workshop gate open

Pull request closed

This pull request cannot be reopened because the branch was deleted.

Sign in to join this conversation.

1 Participants

Notifications

Due Date

No due date set.

Dependencies

No dependencies set.

Reference: jpmschweitzer/settled-reach#198