fix(ui): T-1172 — clip rivers against the drawn waterline (two-waterline reconciliation) #196

2026-07-23T11:42:06+02:00

jpmschweitzer commented

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

Summary

T-1172 (Jeroen's hands-on report on the merged rivers overlay: "the rivers seem to be continuing under the waterline of the ocean"). The fix chain from mechanism confirmation through Tyre's architecture ruling to a live-verified draw-time clip.

The mechanism, and the ruling that shaped the fix

The map had two waterlines: the river skeleton is extracted against the raw 512×256 heightmap sea level (rung-independent graph), while the drawn ocean is the derived morphology verdict — and Tyre's analysis proved the drawn coastline is rung-indexed by construction (warp_fbm's cutoff admits more crinkle octaves at finer rungs — a family of curves, not one). Two sizing corrections along the way: the coast warp is hard-capped sub-pixel (WARP_AMPLITUDE_CAP_PX = 0.75 ≈ 57 km max on Lendel), so the ocean-crossing trails were never warp displacement — they're Region morphology aggregation painting low raw-land shelves as sea. And because no single server-side waterline is well-defined, server-side reconciliation was rejected on well-definedness, not cost: the clip belongs at the draw site, where the rung on screen is known. Captured as a D-226 two-waterline note. The clip carries retirement markers for T-1170, whose course invention terminates rivers at the invented coast with real geometry.

The fix

New pure module atlas_window_water_clip.gd: resolve a river dot/confluence/mouth to the composite cell the viewer currently holds (single-window direct; tile mode selects the containing tile using each tile's own echoed n with nearest-wrap re-expression) and skip the draw if that cell's morphology verdict is water (OpenOcean/Lake — the same verdict the terrain painter used, at the same rung). Strict drop, no snap; offshore mouths suppressed (Tyre's ruling, flagged to Jeroen as the one taste call); basins untouched; fail-open wherever no composite data has arrived — the clip refines presentation, never gates data. The _pos split feeds the same wrap-resolved district to both the draw position and the clip test so they can never disagree about the wrap image.

The live round that made it real

The first implementation passed 49 green tests and removed 133 pixels in the live capture. Dossier diagnosis (with the painter's cell math traced side-by-side) found the tile-mode wrap resolution inverted relative to the painter: the query was wrapped toward a tile's raw canonical center instead of wrapping the tile's center toward held_center — seam tiles tested containment against the wrong wrap-image and read real-but-wrong-location land cells. The stub tests were green because stub and code shared the assumption. Fix mirrors the painter exactly; the index formula (confirmed correct throughout) is now factored into shared AtlasWindowGeometry.cell_index_for_local_offset(). Post-fix verification: 1082 traced positions cross-checked against actual painted pixels — 0 real mismatches; the regenerated Region capture shows every dot and mouth on land, no ocean-crossing trails.

Two harness traps found and fixed during diagnosis (in the lead's untracked drive scratch): the canvas_items stretch factor between a non-base-viewport root.size and screenshot pixels, and mid-arrival snapshots (round 1's faint result was partly a 4-of-6-tiles capture — the drive now waits for is_fully_arrived()).

Test discipline

46 clip tests + 4 shared-index tests + 9 overlay integration tests; the one pre-existing test that encoded the buggy wrap direction as correct was replaced (positive + negative wrap-semantics tests — the negative is the reliable revert discriminator); a wire-accurate seam-tile fixture derived from the live trace ships with an honestly-documented proof limit (a single-tile fixture is mathematically incapable of distinguishing the wrap directions — recorded in the test doc rather than shipping a misleading name). Revert-verified with precise attribution both rounds. Seven sibling suites regression-free; real-driver smoke re-run; gdlint zero-new (28 = main's count).

Tickets: T-1172. Governance: D-226 two-waterline note. Retires into T-1170.

## Summary T-1172 (Jeroen's hands-on report on the merged rivers overlay: "the rivers seem to be continuing under the waterline of the ocean"). The fix chain from mechanism confirmation through Tyre's architecture ruling to a live-verified draw-time clip. ### The mechanism, and the ruling that shaped the fix The map had **two waterlines**: the river skeleton is extracted against the raw 512×256 heightmap sea level (rung-independent graph), while the drawn ocean is the derived morphology verdict — and Tyre's analysis proved the drawn coastline is **rung-indexed by construction** (`warp_fbm`'s cutoff admits more crinkle octaves at finer rungs — a family of curves, not one). Two sizing corrections along the way: the coast warp is hard-capped **sub-pixel** (`WARP_AMPLITUDE_CAP_PX = 0.75` ≈ 57 km max on Lendel), so the ocean-crossing trails were never warp displacement — they're Region morphology *aggregation* painting low raw-land shelves as sea. And because no single server-side waterline is well-defined, server-side reconciliation was rejected on **well-definedness, not cost**: the clip belongs at the draw site, where the rung on screen is known. Captured as a D-226 two-waterline note. The clip carries retirement markers for T-1170, whose course invention terminates rivers at the invented coast with real geometry. ### The fix New pure module `atlas_window_water_clip.gd`: resolve a river dot/confluence/mouth to the composite cell the viewer currently holds (single-window direct; tile mode selects the containing tile using each tile's **own echoed n** with nearest-wrap re-expression) and skip the draw if that cell's morphology verdict is water (`OpenOcean`/`Lake` — the same verdict the terrain painter used, at the same rung). Strict drop, no snap; offshore mouths suppressed (Tyre's ruling, flagged to Jeroen as the one taste call); basins untouched; **fail-open** wherever no composite data has arrived — the clip refines presentation, never gates data. The `_pos` split feeds the same wrap-resolved district to both the draw position and the clip test so they can never disagree about the wrap image. ### The live round that made it real The first implementation passed 49 green tests and removed **133 pixels** in the live capture. Dossier diagnosis (with the painter's cell math traced side-by-side) found the tile-mode wrap resolution **inverted relative to the painter**: the query was wrapped toward a tile's raw canonical center instead of wrapping the tile's center toward `held_center` — seam tiles tested containment against the wrong wrap-image and read real-but-wrong-location land cells. The stub tests were green because stub and code shared the assumption. Fix mirrors the painter exactly; the index formula (confirmed correct throughout) is now factored into shared `AtlasWindowGeometry.cell_index_for_local_offset()`. Post-fix verification: **1082 traced positions cross-checked against actual painted pixels — 0 real mismatches**; the regenerated Region capture shows every dot and mouth on land, no ocean-crossing trails. Two harness traps found and fixed during diagnosis (in the lead's untracked drive scratch): the `canvas_items` stretch factor between a non-base-viewport `root.size` and screenshot pixels, and mid-arrival snapshots (round 1's faint result was partly a 4-of-6-tiles capture — the drive now waits for `is_fully_arrived()`). ### Test discipline 46 clip tests + 4 shared-index tests + 9 overlay integration tests; the one pre-existing test that encoded the buggy wrap direction as correct was **replaced** (positive + negative wrap-semantics tests — the negative is the reliable revert discriminator); a wire-accurate seam-tile fixture derived from the live trace ships with an honestly-documented proof limit (a single-tile fixture is mathematically incapable of distinguishing the wrap directions — recorded in the test doc rather than shipping a misleading name). Revert-verified with precise attribution both rounds. Seven sibling suites regression-free; real-driver smoke re-run; gdlint zero-new (28 = main's count). Tickets: T-1172. Governance: D-226 two-waterline note. Retires into T-1170.

jpmschweitzer added 4 commits 2026-07-23 11:42:06 +02:00

chore(meta): T-1172 filed — river skeleton draws over drawn ocean (two-waterline disagreement, Jeroen's hands-on report) 48340cb6f6

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

docs(meta): D-226 two-waterline note (T-1172 — Tyre's rung-indexed-coast ruling) 7c5dc35b38

The drawn coastline is a family of curves indexed by rung (warp cutoff
admits more octaves at finer rungs), so no single authoritative server-
side waterline exists — reconciliation is a presentation-frame
operation at the draw site; the skeleton stays rung-independent. Clip
retires into T-1170's coast-terminating courses.

Tickets: T-1172

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

fix(ui): T-1172 — clip river dots/confluences/mouths against the drawn waterline 9914dc0d91

Jeroen's hands-on report: rivers continuing under the ocean. Tyre's
ruling implemented: the skeleton is rung-independent, the drawn coast
is rung-indexed (warp cutoff admits more octaves per rung), so
reconciliation is a presentation-frame operation — a draw-time clip
against the SAME per-cell morphology verdict the terrain painter used,
at the rung on screen. New pure module atlas_window_water_clip.gd:
cell resolution across both paths (single-window direct; tile mode
selects the containing tile by each tile's OWN echoed n with nearest-
wrap re-expression against that tile's canonical center — response-is-
source-of-truth + wrap discipline reused, not reinvented). Strict drop
(no snap); offshore mouths suppressed (return with real termini in
T-1170 — retirement markers at the clip sites); basins untouched;
fail-open wherever no composite data has arrived (the clip refines
presentation, never gates data). The _pos split feeds the SAME wrap-
resolved district to both draw position and clip test so they can
never disagree about the wrap image. 49 new tests incl. antimeridian
and mid-progressive-arrival fail-open; revert-verified with precise
attribution (breaking water detection fails exactly the 3 water tests,
fail-open/land tests stay green); smoke-suite stub crash under a real
driver caught and fixed (headless skip-gating masked it). 7 suites
regression-free; gdlint clean.

Tickets: T-1172

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

fix(ui): T-1172 round 2 — tile wrap resolution mirrored to the painter's own direction 0b14cdb21d

Live round: the first clip removed only 133 pixels. Root cause (dossier-
traced): resolve_morphology_zone wrapped the QUERY toward a tile's raw
canonical center — the inverse of the painter's draw_col =
nearest_wrap_image(tile_center, held_center) — so seam tiles tested
containment against the wrong wrap-image and read real-but-wrong-
location land cells. Fix mirrors the painter exactly: wrap the tile's
own center toward held_center, test the (already held-wrapped) query
against that. Index math itself was confirmed correct end-to-end and
is now factored into shared AtlasWindowGeometry.cell_index_for_local_
offset() (full painter unification not applicable — the painter only
iterates forward, never reverse-looks-up; documented). Post-fix: 1082
traced positions cross-checked against actual painted pixels, 0 real
mismatches; regenerated captures show every dot/mouth on land. The one
pre-existing test encoding the buggy direction as correct was replaced
by positive+negative wrap-semantics tests (the negative one is the
reliable revert discriminator) plus a wire-accurate seam-tile fixture
with an honestly-documented proof limit (a single-tile fixture cannot
distinguish the wrap directions; the multi-tile scan tests can).
Also: two harness traps found and fixed in the lead's drive scratch —
canvas_items stretch factor (root.size now matches the 1920x1080 base
viewport) and mid-arrival snapshots (explicit is_fully_arrived wait;
the round-1 faint result was partly a 4-of-6-tiles capture). 46/46 +
50/50 + five sibling suites regression-free; gdlint clean.

Tickets: T-1172

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

jpmschweitzer commented

2026-07-23 11:51:14 +02:00

Review: waterline-clip → main (type: code + visual sign-off)

Branch tip reviewed: 0b14cdb21. Design ruled pre-implementation by Tyre (recorded on T-1172 + the D-226 two-waterline note riding this PR); reviewers of record: Hoshe (QA), Araminta (presentation).

The design (Tyre, pre-implementation ruling)

The map had two waterlines: the skeleton extracted against the raw heightmap sea level; the drawn ocean the derived morphology verdict. His decisive findings: the coast warp is hard-capped sub-pixel (~57 km), so the ocean-crossing trails were Region morphology aggregation, not warp displacement — and the drawn coastline is rung-indexed by construction, so no single server-side waterline is well-defined. Server-side reconciliation rejected on well-definedness; the clip lives at the draw site against the same per-cell verdict the painter used. Strict drop; offshore mouths suppressed (the one taste call, flagged to Jeroen); basins untouched; fail-open without composite data; retirement markers for T-1170.

Hoshe (QA): APPROVE — zero findings

Execution-grade verification throughout:

The round-2 wrap fix verified side-by-side against the painter (byte-identical shape to _draw_tile_mosaic's draw_col); he performed the revert to the round-1 direction himself and got exactly the one named discriminator failure (test_resolve_tile_mode_does_not_match_the_tiles_stale_canonical_span).
The fixture-limit honesty note — Stig's claim that a single-tile fixture mathematically cannot distinguish the two wrap directions — proven algebraically and empirically with 500,000 randomized cases: zero mismatches. "The doc's honesty is accurate, not just plausible-sounding."
Clip predicate coverage matches the ruling exactly (dots/confluences/mouths clipped; basins/attractors untouched); the fail-open test genuinely models mid-progressive-arrival (an unarrived tile in a populated set).
Water constants re-confirmed against the server enum; shared index function's forward/reverse agreement hand-verified including boundary fractions; painter confirmed to never need the reverse lookup (the unification-not-applicable claim holds).
Captures compared against baseline: ocean-crossing trails cleanly absent, zoomed crops of three ocean regions show zero residual dots, markers land exactly at the coastline.
Fresh suite runs: water_clip 46/46, geometry-nature 50/50, nature-overlay 42/42, draw-smoke 6/6; gdlint clean on all eight touched files; D-226 note validated; zero server files in the diff.

Araminta (presentation): APPROVED, all three points

Pixel-scanned the deep ocean basin directly: zero river-teal hits in open water, while the on-land river system is pixel-for-pixel identical to the version she previously approved — "the clip removed exactly what it was supposed to and nothing else." Offshore-mouth suppression accepted on visual merits ("a floating ring with no course reads worse than no ring"; the coast does not read under-anchored — T-1162's shoreline crinkle carries the river-meets-sea read). District confirmed unchanged.

The live rounds (for the record)

Round 1 passed 49 green tests and removed 133 pixels: the tile-mode wrap resolution was inverted relative to the painter, and stub tests shared the code's assumption — caught only by the live pixel-diff. Round 2's dossier tracing (painter's cell math side-by-side) pinned it; post-fix, 1082 traced positions cross-checked against actual painted pixels with 0 real mismatches. Two harness traps found and fixed en route (canvas_items stretch factor; mid-arrival snapshots — round 1's faint result was partly a 4-of-6-tiles capture). A third trap — orphan-leaking binary-gated skips bouncing client-only branches off the push gate — ticketed as T-1173.

Verdict: APPROVED

Tickets: T-1172. Governance: D-226 two-waterline note. Clip retires into T-1170's coast-terminating course invention.

## Review: waterline-clip → main (type: code + visual sign-off) Branch tip reviewed: `0b14cdb21`. Design ruled pre-implementation by Tyre (recorded on T-1172 + the D-226 two-waterline note riding this PR); reviewers of record: Hoshe (QA), Araminta (presentation). ### The design (Tyre, pre-implementation ruling) The map had two waterlines: the skeleton extracted against the raw heightmap sea level; the drawn ocean the derived morphology verdict. His decisive findings: the coast warp is hard-capped sub-pixel (~57 km), so the ocean-crossing trails were Region morphology *aggregation*, not warp displacement — and the drawn coastline is **rung-indexed by construction**, so no single server-side waterline is well-defined. Server-side reconciliation rejected on well-definedness; the clip lives at the draw site against the same per-cell verdict the painter used. Strict drop; offshore mouths suppressed (the one taste call, flagged to Jeroen); basins untouched; fail-open without composite data; retirement markers for T-1170. ### Hoshe (QA): APPROVE — zero findings Execution-grade verification throughout: - **The round-2 wrap fix** verified side-by-side against the painter (byte-identical shape to `_draw_tile_mosaic`'s `draw_col`); he performed the revert to the round-1 direction himself and got exactly the one named discriminator failure (`test_resolve_tile_mode_does_not_match_the_tiles_stale_canonical_span`). - **The fixture-limit honesty note** — Stig's claim that a single-tile fixture mathematically cannot distinguish the two wrap directions — proven **algebraically and empirically with 500,000 randomized cases**: zero mismatches. "The doc's honesty is accurate, not just plausible-sounding." - Clip predicate coverage matches the ruling exactly (dots/confluences/mouths clipped; basins/attractors untouched); the fail-open test genuinely models mid-progressive-arrival (an unarrived tile in a populated set). - Water constants re-confirmed against the server enum; shared index function's forward/reverse agreement hand-verified including boundary fractions; painter confirmed to never need the reverse lookup (the unification-not-applicable claim holds). - Captures compared against baseline: ocean-crossing trails cleanly absent, zoomed crops of three ocean regions show zero residual dots, markers land exactly at the coastline. - Fresh suite runs: water_clip 46/46, geometry-nature 50/50, nature-overlay 42/42, draw-smoke 6/6; gdlint clean on all eight touched files; D-226 note validated; zero server files in the diff. ### Araminta (presentation): APPROVED, all three points Pixel-scanned the deep ocean basin directly: zero river-teal hits in open water, while the on-land river system is **pixel-for-pixel identical** to the version she previously approved — "the clip removed exactly what it was supposed to and nothing else." Offshore-mouth suppression accepted on visual merits ("a floating ring with no course reads worse than no ring"; the coast does not read under-anchored — T-1162's shoreline crinkle carries the river-meets-sea read). District confirmed unchanged. ### The live rounds (for the record) Round 1 passed 49 green tests and removed 133 pixels: the tile-mode wrap resolution was inverted relative to the painter, and stub tests shared the code's assumption — caught only by the live pixel-diff. Round 2's dossier tracing (painter's cell math side-by-side) pinned it; post-fix, 1082 traced positions cross-checked against actual painted pixels with 0 real mismatches. Two harness traps found and fixed en route (canvas_items stretch factor; mid-arrival snapshots — round 1's faint result was partly a 4-of-6-tiles capture). A third trap — orphan-leaking binary-gated skips bouncing client-only branches off the push gate — ticketed as T-1173. ### Verdict: APPROVED Tickets: T-1172. Governance: D-226 two-waterline note. Clip retires into T-1170's coast-terminating course invention.

jpmschweitzer closed this pull request

2026-07-23 11:52:25 +02:00

jpmschweitzer referenced this issue from a commit

2026-07-23 11:55:27 +02:00

chore(meta): T-1172 to review — PR #196 up (waterline-clip)

jpmschweitzer referenced this issue from a commit

2026-07-23 11:55:27 +02:00

chore(meta): close T-1172 — PR #196 merged (waterline clip; rivers no longer draw over drawn ocean)

jpmschweitzer referenced this issue from a commit

2026-07-23 16:07:46 +02:00

test(ui): spy tests for the B3 arrival-redraw fix (PR #197 Hoshe #3)