settled-reach/docs/workshops/body-map-viewer/prep-grounding.md

title, description, type, status, workshop, created, decision_refs

title	description	type	status	workshop	created	decision_refs
Body Map Viewer — Prep Grounding	Pre-read for the T-1176 prep session (Jeroen + lead + Tyre) and later the workshop: current mechanism, error-class evidence, delivered ladder design, binding constraints, candidate directions	workshop	active	body-map-viewer	2026-07-25	D-166 D-226 D-227 D-243

Body Map Viewer — Prep Grounding

Prepared by the lead for the three-way prep session (Jeroen, lead, Tyre) that writes the workshop brief. Working name body-map-viewer (Jeroen's phrase) — rename with the brief if a better one emerges. Everything here is input, not position: Jeroen's outline of his own design opens the session and nothing below pre-empts it.

1. Why this exists

Jeroen, 2026-07-23 (T-1176): "I want to discuss and maybe revise the pixel scan/output mechanism for drawing the map. I feel we can be smarter about this and bypass an entire class of errors we are seeing as well as probably improve performance." Follow-up 2026-07-25: he, the lead, and Tyre write a plan to start a wider-team workshop on the new map handler; Jeroen will outline how he would build the body map viewer with zoom to ground level and how the deterministic generation cascade connects into it.

2. The error-class evidence (PRs #195–#197, recorded in D-226 implementation notes)

All rendering-layer bugs of the river arc descend from one architectural choice: immediate-mode draw_* calls issued by children of a zoom-scaled canvas (_canvas.scale = _view_zoom), which makes every on-screen size a canvas-local value divided by zoom:

• Per-call-site compensation fragility — every radius/stroke needs _zs/_zs_stroke/ _zs_ring_radius wrapping (atlas_window_geometry_nature.gd); a missed site degrades silently. Happened twice (PR #195 attractor strokes, PR #197 course widths).
• Godot line-rasterizer stroke floor — widths below ~1.0 canvas units collapse to a 1 px hairline (bracketed live: 0.6 → hairline, 1.1 → visible). Consequence on record: per-class course width grading is inert at every shipping fit zoom; classes distinguish by opacity alone until T-1175.
• draw_arc blob regime — ring radius below stroke width renders a filled blob (bracketed: 1×stroke = blob, 1.5× = recovers, 2× = clean; floored at 2×).
• Wrap-image resolution family — seam tiles must mirror the painter's nearest_wrap_image(tile_center, held_center, cols) exactly (T-1172 round 2 inverted it); shared index math now lives in cell_index_for_local_offset.
• Auditability — the mechanism defeated visual verification three times in one batch (lead capture misreads corrected only by wire data). A mechanism whose correctness can't be eyeballed is itself a finding.

3. The current mechanism (the thing being revised)

Client (client/ui/implant/apps/atlas/): AtlasWindowViewer (~1017 ln) owns a _canvas Node2D; pan/zoom = _canvas.position/_canvas.scale (_apply_transform). Terrain: atlas_window_overlay.gd builds one Image texel per derived cell → ImageTexture → draw_texture_rect (COMPOSITE_SMOOTH pipeline axis; rebuilt only on window change — pan/zoom is free), per-rung sampling filter _filter_for_granularity_v2 (Region/orbital-mosaic → NEAREST, District/Quarter → LINEAR; T-1161 two-axes outcome). Nature features (atlas_window_nature_overlay.gd): draw_polyline/draw_circle/ draw_arc inside the scaled canvas with the §2 compensation family. Orbital rest state: whole-body mosaic of capped Region tiles (per-tile ImageTextures, AtlasWindowTileSet). Rung selection: coverage-ceiling walk (select_rung(), MAX_COVERAGE_M — Quarter ≈ 32.8 km, District ≈ 131 km, Region ≈ 13,107 km, beyond → tile mode). CELL_PIXEL_SIZE = 16 px at zoom 1.0. Redraws on pan/zoom/rung-cross/ arrival, not per-frame.

Server (server/src/atlas/): windowed derives on the Rayon background queue, never inline (D-226 T-1124 §1 [HARD]); one windowed payload (DistrictWindowLayer: per-cell u8 arrays + courses: Vec<RiverCourse>), echo/cache keyed on (body, center, n, granularity); wire clamp window_n² × granularity² ≤ WIRE_CAP_CELLS (4096); whole-body Layer1 family (512×256: heightmap analysis, D8 drainage/rivers) rung-independent. Measured (zoom_ladder_bench, release, 16 cores): District derive 3.0 µs/cell uncut, 1.785 µs @2048 m cutoff; Quarter 1.823 µs @512 m; orbital 1.454 µs; served Region window (4096 cells) 0.617 ms/call.

4. The delivered ladder design and what it already settles

docs/architecture/atlas-zoom-ladder-t1143.md (9-agent pass, 2026-07-21) + Jeroen's three rulings (recorded as D-226 amendment):

1. Floor OPENED — "we set a new BHAG so old restrictions are up for debate." The D-226(d) ceiling is opened for the Atlas ladder; "down to tile scale" reads literally. Below-quarter rungs (block/tile) are implementation-gated on T-1154 (below-quarter measurement pass — backlog, now unblocked: the octave-cutoff plumbing it was blocked on has existed since T-1162). Chunk/tile output still never appears as a whole-body planetary layer — windowed viewport only.
2. Planetary carrier — progressive capped-density tiling on the generalized district_window carrier (shipped as the orbital mosaic).
3. Entry seam — continuous cursor-anchored zoom, full-zoom-out resets to the canonical planetary frame (shipped, T-1153).

Standing risks from that doc that touch this workshop: R1 planetary/canvas-fill cost story (full-canvas sample still extrapolated, ~524 ms @2 px/cell parallel- estimated); R2 temperature steps at district boundaries by construction at every rung (never continuous); R3 average-back unverified for categorical morphology gates; R6 border-fade referent must repoint when the heightmap-texture path retires.

5. Binding governance (verified verbatim)

• D-166 amendment + corollary (2026-07-21): continuous zoom ladder planetary→tile, every level "deterministically calculated information at that level's native granularity … never magnified interpolation of a coarser composite"; display "samples the derivation at canvas resolution (the ladder is a continuous field, not a stack of fixed display rasters)"; heightmap PNGs are invisible derivation input. Hard Phase-4 exit bar (T-750).
• D-226(d) as amended by ruling 1 above: the old hard ceiling is opened for the windowed viewport; the whole-body-planetary-layer prohibition stands.
• D-227: derive-don't-store — subtile(x,y,z) = derive(seed, atlas, position), transient evictable caches only; coast crinkle + river courses are rung-indexed invention.
• D-243: the containment ladder (voxel 1 m … region 204.8 km, one elastic planetary seam); climate edge-fuzzed ("climate does not change on a line"), morphology seams sharp-but-organic.
• Carrier three-way rule (docs/architecture/river-courses-t1170.md, binding): (i) rung-independent discrete features → whole-body family, filtered client-side; (ii) continuous per-metre fields → windowed per-cell arrays; (iii) rung-indexed invented detail → windowed payload regardless of geometric kind.
• Windowed-family ceiling (D-226 T-1124 §2 [HARD]): exactly one windowed-query field on AtlasLayerResponse; a second forces the tagged-envelope migration.

6. T-1176 candidate directions (sparring material, not positions)

• (a) Unscaled screen-space sibling layer — annotation/feature drawing moves to an unscaled sibling of the canvas; positions transformed to screen space, sizes literal px. Kills the whole §2 compensation class for vector features. (Tyre's earlier note, T-1156 wave 2 / T-1158-adjacent.)
• (b) Render-to-texture per window/tile — features rendered at native resolution into textures; zoom becomes pure texture transform; sizes texel-exact. Must be argued against D-166's "canvas resolution / continuous field, not fixed display rasters" sentence. Prior art in-tree (Tyre): the orbital tile-mode mosaic already composites per-tile ImageTextures (_tile_texture_cache, compute_tile_grid() — Lendel 3×2, verified this session) — the terrain path is halfway to this model.
• (c) Shader-side composition — morphology/courses as data textures, coloring + feature rendering in fragment shader; per-vertex width/tapering (T-1175) comes free; likely the performance route for canvas-resolution sampling at planetary scale (R1).
• (d) Hybrid — e.g. terrain via (c), vector annotations via (a).

7. Adjacent work that intersects

Item	Status	Intersection
T-1154 below-quarter measurement pass	backlog, unblocked	the gate for "zoom to groundlevel"; block/tile rung costs + wire
T-1158 viewer decomposition	backlog	any new mechanism restructures the same file
T-1175 polish collector	backlog	tapering/width grammar wants Polygon2D strips or shaders — mechanism-dependent
T-1157 capture harness redesign	backlog	§2's auditability finding — verification story for whatever ships
T-1174 batch/window sampling divergence	backlog	pre-existing sampling debt
D-239 tile-derivation contract	verified in-session: confirmed/active, "coarse→fine refinement chain (resolves Q-101)", 2026-06-07	the derivation side of "connect the cascade" is settled governance
Phase-5 boundary (D-166 generation-before-player)	standing	ground-level rendering is Phase 5; the Atlas ladder maps derived layers — where Jeroen's viewer sits relative to this line is his to outline

Prior workshop art: atlas-derivation-model.md (brief-only, data side), generation-cascade/ (atlas UI coords vs sim coords), world-generation/ (atlas as annotated information layer), map-authoring-pipeline/ (brief-only, predates the no-hand-made-test-map rule — historical only).

8. What the prep session must produce

1. Jeroen's design outline, captured faithfully (the session's round 1).
2. Every point sorted: settled by the three of us vs genuinely open → workshop question vs already ruled (cite the record).
3. The workshop brief (body-map-viewer-workshop-brief.md): question, locked/open context, roster, per-agent questions, format, input docs, expected outputs (D-record(s), ticket plan).