feat(simulation): T-1170 + T-1168 — river course invention, coast termination, riparian signal #197
Assignees
jpmschweitzer (Jeroen Schweitzer)
Clear assignees
jpmschweitzer (Jeroen Schweitzer)
No Assignees
Notifications
Due Date
No due date set.
Dependencies
No dependencies set.
Reference: jpmschweitzer/settled-reach#197
Reference in New Issue
Block a user
Summary
The T-1170 + T-1168 batch: rivers become real geometry at every rung, and the vegetation layer learns to answer for them. The dots are gone — courses meander, terminate at the drawn coast, and refine with zoom exactly like the coastline does. Also closes the mouth-semantics debt (pole-edge drains stop masquerading as river mouths) and restructures the T-1172 water clip per plan.
The design pass (before any code — full ruling:
docs/architecture/river-courses-t1170.md)A three-audit workflow (two Si code-truth audits + a Dudley cost probe) fed Tyre's binding ruling. The keystone: course geometry is invention, not skeleton — so the wave-1 carrier rule refines three-way: rung-independent discrete features ride whole-body; continuous fields ride windowed per-cell arrays; rung-indexed invented detail rides the windowed payload regardless of geometric kind (courses are the coast crinkle's vector sibling; no ceiling impact — content of the one windowed payload, not a second query). This dissolves the two-waterline terminus fork: the server invents each course at a known rung in the same pass that computes that rung's water verdicts. Region's straight skeleton chords turn out to be the rung-truncated course — one function, every rung, no special cases. The
TERMINALsentinel is reserved now, so future endorheic basins (Jeroen's Okavango interest) become additive, not a wire migration. Captured in D-226 + D-227.Server (Dudley)
river_downstream: Vec<u8>onRiverNetwork(D8 pointers + MOUTH/EDGE_DRAIN/reserved-TERMINAL sentinels), captured wherefdirwas being discarded. Pole-edge drains reclassified out ofmouths— on the golden fixture 16 of 19 "mouths" were grid artifacts (exactly Jeroen's "circles with no sea in sight").river_course.rs— Stage A rung-independent valley-seeking control path (bilinear-scored candidates, never full re-derivation) + Stage B rung-indexed perpendicular warp on global arc-length (window-independence: the window crops, never re-parametrizes), sine taper to zero at cell-centre anchors (confluences meet C0 for free), amplitude ≤ min(8% chord, half-cell). Mouth termination walks stations against the window's own rung-consistent water verdict with 6-iteration bisection. Wire:courses: Vec<RiverCourse>onDistrictWindowLayer, bbox-culled and window-cropped (~1–2 KB typical).near_perennial_water— a scale-free point-to-polyline distance predicate (D-239 §8 governed 1–3 m class-scaled bands) threaded through both derive paths; never touchesmoisture_q. Honestly sub-cell at every Atlas rung (the visible payoff arrives at tile rungs; the Nile-corridor widening is a one-constant design call, flagged to Jeroen).Client (Stig)
atlas_window_geometry_nature.gd(line-cap pressure valve); visibility tables split per Ruling 5c — Quarter rivers return (the pre-announced revisit), with width/opacity companion tables as Araminta's single revisit point.Live rounds (the eyeball check, again)
Araminta's pixel audit of the first course captures caught a uniform 1 px hairline where trunk should draw 2.2 px — and caught the lead's "class grading confirmed" claim resting on hue-sampling alone (retracted in the record). Stig's A/B bracket localized the cause to Godot's line-rasterizer stroke-width floor (~1.0 canvas units collapses to hairline; the compensation arithmetic was correct). Fix: a floor-clamped stroke-width variant on every stroke site, radii proven unaffected; 14-test pin suite with the exact floor-engagement numbers; class question resolved with printed ground truth (the original window genuinely single-drawable-class; multi-class rendering confirmed at a confluence window; the drive now prints per-course tables every run).
Presentation (Araminta)
Region chords approved as rendered; all table values confirmed final (0.9/1.4/2.2 px, 0.8/0.9/1.0, District trunk+tributary / Quarter all three); single-teal stays (width+opacity is sufficient class vocabulary); mouth treatment unchanged. Aesthetic refinements (source tapering, thickness tuning, the RimWorld-reference techniques) deliberately parked in T-1175 per Jeroen's single-pass ruling.
Verification
Server: full
cargo testgreen including all golden binaries; benches recorded in the design doc. Client: full suite 3942/3942; three revert-verification rounds across the batch; gdlint zero-new (28 = main's baseline). Governance validates. Follow-ups filed en route: T-1174 (batch/window sampling divergence, pre-existing), T-1175 (polish collector).Tickets: T-1170, T-1168. Governance: D-226 course-carrier note, D-227 invention-family amendment, design doc
river-courses-t1170.md.A2 (river_course.rs): Stage A rung-independent valley-seeking control path (chord/8 stations, k=5 bilinear-scored candidates + continuity penalty); Stage B rung-indexed perpendicular warp on GLOBAL arc-length (window-independence, Ruling 1e), band chord/2 down to min_wavelength_m hard-truncate, sine taper to zero at anchors, amplitude min(8% chord, half-cell) slope/class-scaled. SeedDomain::RiverCourse=17, distinct salt. Wire: RiverCourse{edge_id,class,points,terminus} on DistrictWindowLayer.courses (serde-default); bbox-culled, window- cropped +1 station. TerrainAnalysisCache retains Layer1Output (the gen_queue:626 discard, Ruling 4b). A3: mouth termination walks stations sampling the window's OWN rung-consistent morphology verdict, 6-iteration bisect; land-at-anchor probes one segment then None; EdgeDrain never probes. A5: near_perennial_water point-to-segment predicate (D-239 §8 governed bands 1-3m class-scaled) threaded through both batch and window paths; Region always false; never touches moisture_q. Discipline closed: dormant zoom-ladder bench run + numbers recorded in the design doc (District 3.009/1.785, Quarter 1.823 us/cell, Region window 0.617ms); course-cost bench CAUGHT a real +12-36% per-cell riparian scan regression -> precomputed bbox O(1) reject (60ns->2.2ns/call), final delta +3.4-6.9% at budget; three determinism tests (overlapping-window byte-identity, cross-rung amplitude bound, warp-stream cross-correlation r<0.3); goldens: window sweep gained a verified course-bearing position (pure append), new river_course golden at both rungs, believability verified unchanged. Revert-verification discovered the pole-row branch is structurally unreachable (flow_direction bounds-check) — the real edge-drain path is k<0 flat-plateau; test fixture rewritten to exercise reality. scale.rs stale comment fixed. Full cargo test green. Tickets: T-1170, T-1168 Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>Tyre — architectural review, PR #197 (river-courses → main)
Verdict: REQUEST_CHANGES — two non-blocking corrections + one working-tree cleanup before merge. The ruling implemented with high fidelity; no bounces. cracks knuckles — this is the ruling doing the work exactly as designed. Every primitive composed cleanly, and the two-stage split delivered the cross-rung unification I got excited about in the ruling.
Issues
[minor, fix]
resolve_mouth_terminusprobe is dead arithmetic + wrong magnitude label —layer_proxy.rs:1434:probe = (b.0 + dx / len * len, b.1 + dy / len * len)simplifies to(b.0 + dx, b.1 + dy)— the/len * lenis a no-op, and the step is one segment length, not "one cell length" as Ruling 3e specified and the comment claims. At District spacing segment-length ≈ cell-length so it's functionally near-right, but write it honestly:let step = station_spacing_m; probe = (b.0 + dx/len*step, b.1 + dy/len*step). Correctness-adjacent, not load-bearing (degenerate land-at-anchor path, bounded/rare).[minor, capture] Boxing comment causal claim is inaccurate —
gen_queue.rs:274: the comment saysBodyWorldState"grew past clippy's large-enum-variant threshold when it began retainingLayer1Output(T-1170 Ruling 4b)." It did not.BodyWorldStategained exactly oneVec<u8>(river_downstream, ~1 B/river-cell) on its nestedRiverNetwork. TheLayer1Outputretention (Ruling 4b) lives inTerrainAnalysisCache(session cache), NOT onBodyWorldState. The box is correct and worth keeping —BodyWorldStatewas already a large variant — but the reason is misattributed. Reword to: "BodyWorldStateis a large struct; boxing keepsGenCompletionsmall so the 15+ other variants don't carry its footprint by value." No code change.[cleanup, must] Working tree not clean — untracked scratch file
client/tmp_drive_courses.gd(self-labeled "deleted after use") must be removed before merge (per write-discipline: scratch belongs underclaude/, not inclient/).server/tests/zoom_ladder_bench.rshas an uncommittedcargo fmtreflow — commit it or discard it; don't merge with it dangling.Governance capture (accompanies, not blocking)
zoom_compensated_stroke_widthfloors at 1.0 canvas-local unit (honest — below it Godot's line rasterizer collapses everything to hairline). But becausecompensated = size/view_zoom, the floor engages harder the deeper you zoom in: at District/Quarter fit (~3.75/7.5) the 0.9–2.2 px class table already divides to 0.12–0.59, all sub-floor. Consequence: Ruling 5c's per-class WIDTH differentiation is inert at every shipping zoom — classes stay distinguishable by opacity only until T-1175 (Polygon2D strips). This is acceptable pre-polish honest degradation and T-1175 already scopes it (item 1 + source-taper item 2), but it should be an explicit note on D-226 so the "trunk widest" promise isn't read as live. One sentence.drainage.rs—flow_directionbounds-checks before assigningfdir, so the "flow points past row 0" branch inextract_river_networkcan never fire; the real EDGE_DRAIN case isk < 0) is well-documented in the test comment but deserves one line in the D-226 course-carrier note or the ruling doc, since it refines the mechanism I ruled.The 7 architecture questions — verified answers
invent_courses_near_windowpassesstep_m(neverwin_x0) andoverlapping_windows_produce_byte_identical_course_points(layer_proxy.rs:2754) proves byte-identity across two different-centered windows — PASSES. 3c taper-to-zero + hard caps:amplitude_never_exceeds_hard_caps+stage_a_endpoints_are_the_true_cell_centresenforce both — PASSES. 3e rung-consistent termination samplesderive_at_metres(...).morphology_zone(not raw ocean_frac), 6-iter bisect, one-probe extension, None-on-still-land — faithful. No deviations rise to a bounce.courses: Vec<RiverCourse>is a field INSIDEDistrictWindowLayer(#[serde(default)]), NOT a newAtlasLayerResponsefield. Cache keyDistrictWindowKeyunchanged (courses ride the same echo key). Invention runs inside the existingDeriveWindowitem (build_district_window_layer), no new work-item class. Windowed-family ceiling untouched. Exactly Ruling 1b/1c.Layer1Outputretained onTerrainAnalysisCache(correct locus — whole thing, not just RiverNetwork; it's small vs TerrainAnalysis's ~1.5-2 MB, and the window path needs the fulll1handle).BodyWorldStategrew by ~1 B/river-cell only. Box is right; comment misattributes why (issue 2). No CACHE_CAPACITY footprint concern — the fat retention is the 8-entryTerrainAnalysisCache, not the 50-bodyBodyWorldStateCache.#[ignore]print bench asserting onlycourses_seen > 0(not a hard <5% gate) — correct call; a hard threshold on a ~1 ms micro-bench would be flaky. The bbox precompute onInventedCoursestays within derive-don't-store: it's a cache-adjacent perf field on an invention product (computed once ininvent_course, read-only), not stored world state — legitimate.build_edgesskips it, sentinel reserved, no wire migration when endorheic lands).pql decisions validate→{"ok":true}.Test evidence (all green at HEAD
958de5420)cargo build --testsclean · river_course 20/20 · drainage 21/21 (incl. pole-drain + downstream) · layer_proxy 53/53 (incl. overlapping-windows determinism + window/batch riparian agreement) · cascade_golden 1/1 (mouths-lose-poledrains + river_downstream re-pin) · window_derivation_golden 5/5 (incl. river_course_golden + rung-station-count divergence) · believability_harness 1/1 unchanged (Discipline item 4 confirmed — the point test correctly does not fire at harness spacing) · derivation_harness 37/37. Discipline item 1 dormant benches run + recorded MEASURED in atlas-zoom-ladder-t1143.md.— Tyre
Tyre — final verdict, PR #197 @
f9ab3088aAPPROVE. Re-verified all six commits past my reviewed
958de5420. Every item landed; the one find I missed was caught by Hoshe and fixed the right way. cracks knuckles — this is the batch closing clean.My two issues — both fixed, both correct
station_spacing_mthreaded crop→crop_course_to_window→resolve_mouth_terminus; the deaddx/len*lenreplaced with a true unit step(ux,uy)*station_spacing_m— one real cell length, per Ruling 3e. The new comment even improves on my find: it notes the final Stage-B segment can be shorter than a cell near the taper-to-zero anchor, so this was a genuine correctness fix, not cosmetic.Hoshe's blocking find — the second instance of my own Ruling 2b anti-pattern (
d256233fa)This is the one my review missed and I want to name it plainly:
extract_river_networkcomputed the seaward neighbor(nr,nc)to decide the MOUTH sentinel, then threw it away — andbuild_edgesplaceholder-pointed mouth edges at themselves (zero chord). That madeinvent_coursereturn its degenerate 1-point course andresolve_mouth_terminusdead code on every real mouth → all mouths resolvingNone→ and because Ruling 3g retired the District/Quarter clip on the promise of real termini, mouths would vanish at District/Quarter. Ship-visible. It is the exact "we had the true answer in hand and threw it away" pattern I named in Ruling 2b for the interior pointers — and there were two instances, not one. The fix is architecturally right:river_seaward: Vec<(u16,u16)>additive/serde-default parallel array, captured in the SAME extraction pass (zero new grid pass — the A1/Ruling 2a discipline), read bybuild_edgesto give mouth edges a real one-cell seaward chord;EdgeDraincorrectly stays zero-length (never probes water). Permanent acceptanceall_real_gj1c_mouths_resolve_to_mouth_terminus_not_none3/3, revert-verified failing. Good catch, clean fix.The three new pins + ring-radius fix — reviewed, sound
270dba014): confirmscrop_course_to_windowreads onlylast_infor the true-end test — my crop logic is correct; the pin guards it. Test-construction sanity assertions (anchor genuinely cut, terminus genuinely in-window) are properly guarded.c804f2c23): the "course over water" report was a genuine not-a-bug — an estuarine tail plus a probe-side wire-clamp (n=32 serving as 16 at Quarter). Determination reads correctly; pinning the invariant on a real live window is the right disposition.f9ab3088a): third member of the Godot sub-canvas-unit rasterizer family — at Quarter fit the compensated ring radius (0.667 canvas) fell below the floored stroke (1.0) anddraw_arcfilled its own hole (blob, not ring); floored at 2x stroke, live-verified hollow. Same honest-degradation posture as the stroke-width floor I already blessed. All three regimes queued for the T-1176 render-mechanism discussion — correct forward contract.Governance
Both my sentences landed verbatim-close in D-226: (a) stroke-floor width-inertness with the opacity-only honest framing + T-1175 supersession ("the 'trunk widest' promise is design intent, not current pixels"); (b) the structurally-unreachable pole-row discovery.
pql decisions validate→{"ok":true}.Test evidence @
f9ab3088aFull
cargo test(all binaries) GREEN — 1879 lib + every integration binary, 0 failed. Goldens: cascade_golden 1/1, window_derivation_golden 6/6 (incl. newriver_course_mouth_samples_are_non_degenerate), believability_harness 1/1, derivation_harness 37/37, layer_proxy 56/56 (incl. the two new mouth pins + overlapping-windows determinism), drainage 22/22.One transparency note for the record: my first full-suite run immediately after switching the worktree to the tip showed the two new mouth-terminus pins failing; every subsequent run — the tests in isolation (6/6), the full layer_proxy suite (5/5 consecutive), and the whole server suite — is stably green. Diagnosis: a stale incremental-build artifact during the tree transition, not product non-determinism and not persistent flakiness (the assertions are deterministic and reproducibly pass). Flagging it only so it's on the record; it is not an objection.
No remaining objections. Ship it.
— Tyre
Review: river-courses → main (type: code + visual sign-off)
Branch tip reviewed:
f9ab3088a(all fix rounds included). Reviewers: Tyre (architecture — his own binding ruling), Hoshe (QA), Araminta (presentation).Tyre (Architecture): APPROVE (after one fix round)
Initial REQUEST_CHANGES: two minor fixes (dead arithmetic in the mouth probe — now a true one-cell-spacing step via
station_spacing_mthreading, which his re-verify upgraded to "a genuine correctness fix" since Stage-B segments shrink near the taper anchor; a misattributed boxing comment — reattributed to variant-size balancing), a cleanup item, and two governance sentences (both landed in D-226: the stroke-floor makes per-class course width differentiation inert at every shipping zoom — classes distinguish by opacity alone until T-1175; and the pole-row edge-drain branch is structurally unreachable, the real mechanism being interiork<0). His fidelity sweep confirmed every ruling rule implemented, the carrier exactly as designed (courses as windowed-payload content, no ceiling movement, no new work-item class), and — on the record at his own insistence — that Hoshe's blocking find was the instance his review missed: the second recurrence of his own Ruling 2b anti-pattern.Hoshe (QA): APPROVE (after one fix round) — the batch's decisive find
His blocking find:
extract_river_networkcomputed the seaward neighbor then discarded it,build_edgesplaceholder-pointed mouth edges at themselves — zero chord, degenerate one-point courses,resolve_mouth_terminusdead code on every real mouth, all mouths resolvingNone, and (because Ruling 3g retired the District/Quarter clip on the promise of real termini) mouths would have vanished at those rungs. Ship-visible, invisible to every existing test (goldens filtered Interior-only). Fixed viariver_seaward(additive, captured in the same extraction pass), with a 3/3 GJ1c acceptance test he revert-verified himself.The live rounds that followed produced three permanent pins, each from a falsified-or-confirmed hypothesis rather than assumption: the upstream-only-crop case (hypothesis that crops destroy the flag: falsified — the crop reads only
last_in; the existing test's whole-course-by-construction blind spot demonstrated live, then closed); the walk/paint agreement invariant on the exact live Quarter window (the apparent course-over-drawn-water was a genuine estuarine tail — 178 land stations out of frame — plus a probe-side wire-clamp trap: Quarter n=32 serves as n=16; the lead's "tens of km past coast" read was wrong by two orders — the terminus sits ~240 m from the painted crossing); and the ring-radius floor (below). His final wire-data check also resolved the lead's last capture question as not-a-bug: the estuary bends back on itself, the terminus is genuinely the polyline's last point.Also fixed on his findings: the missing B3 arrival-redraw spy tests (Stig caught two masking paths building them — a second pre-existing redraw route and a state-resetting simulation shortcut — and rebuilt against real production triggers) and the A1 golden characterization (attractors are count-parity, not byte-identical — the
water_distcascade from the mouths cleanup, now stated accurately in the golden's own doc).Araminta (presentation): APPROVED
Region chords, all width/opacity/visibility table values confirmed final; her earlier pixel audit drove the stroke-width floor discovery (Godot's line rasterizer collapses sub-1.0-canvas-unit strokes to hairline — the compensation arithmetic was correct; the value died at the driver), and the final round added the family's third member: ring radius below stroke width turns
draw_arcinto a filled blob — floored at 2× stroke, live-bracketed (1×=blob, 1.5×=recovers, 2×=clean).The Godot sub-canvas-unit rasterizer family (recorded in D-226, queued for T-1176)
Three regimes discovered across this batch, all born from immediate-mode drawing inside a zoom-scaled canvas: stroke widths floor to hairline below 1.0 canvas units; every stroke site needs per-call compensation (two escaped the first sweep); ring radii below stroke width degenerate. This evidence file feeds Jeroen's queued render-mechanism design discussion (T-1176).
Verification at tip
Server: full
cargo test— 1879 lib + every integration binary, zero failures; goldens re-pinned deliberately with rationale (cascade, window-derivation +course sweep, new course golden with Mouth coverage); course-cost bench +3.0–6.9% within the <5% budget across runs; the dormant zoom-ladder bench finally run and recorded. Client: full suite 3956/3956; three revert-verification rounds plus both reviewers independently re-breaking the load-bearing fixes.pql decisions validateclean.Verdict: APPROVED
Tickets: T-1170, T-1168. Governance: D-226 course-carrier note + implementation notes, D-227 invention-family amendment, design doc
river-courses-t1170.md. Filed en route: T-1174 (sampling divergence), T-1175 (polish collector), T-1176 (render-mechanism discussion).Pull request closed