jpmschweitzerandClaude Fable 5
77531a0eab
Three-way prep session (Jeroen + lead + Tyre) for the map-handler revision: Jeroen's design outline captured verbatim, two clarification rounds, Tyre's governance-delta/implications pass, brief co-written and ratified (zero misrepresentations, zero blocking gaps), signed off by Jeroen with three edit rounds (vocabulary repair tile->gridunit, client cache-store question with SQLite fact base, explicit DQR/ticket deprecation sweep as gated deliverable). Workshop: 5 seats (Dudley/Araminta/Stig/Tyre + Troblum r2), 2 rounds + lead interview extendable at Jeroen's call, round 1 gated on measurements T-1177/T-1178/T-1154/T-1179 (T-1180 non-gating). T-1176 in_progress with gate blocker edges; T-1154 repurposed as measurement (3) and set ready. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
164 lines
10 KiB
Markdown
164 lines
10 KiB
Markdown
---
|
||
title: "Body Map Viewer — Prep Grounding"
|
||
description: "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"
|
||
type: workshop
|
||
status: active
|
||
workshop: body-map-viewer
|
||
created: 2026-07-25
|
||
decision_refs: [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).
|