settled-reach/docs/workshops/body-map-viewer/body-map-viewer-workshop-brief.md

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

title	description	type	status	workshop	created	decision_refs
Workshop Brief: Body Map Viewer — the stepped map handler	Design the new Atlas map handler: server-side content determination per zoom step, client map-art rendering (RTT + screen-space vectors), stepped gridunit ladder to ground level, cache/TTL architecture, wire contract	workshop	active	body-map-viewer	2026-07-25	D-166 D-226 D-227 D-243 D-239 D-225 D-010

Workshop Brief: Body Map Viewer — the stepped map handler

The Question

Jeroen's design outline (jeroen-outline.md) replaces the Atlas render mechanism: content determination moves to the server (per-gridunit data canvases generated per zoom step, doubling as seed input for the next tier down), the client becomes a map-art function (colorize, style, annotate — never invent geometry), and zoom becomes a stepped ladder from the body-global view down to ~10 px per 1 m tile. This dissolves the T-1176 error class at the root (there is no zoom-scaled canvas anymore) and turns the D-166 seamless-ladder mandate into a concrete serving + caching + rendering architecture.

The premises are settled (below). The workshop designs the remaining load-bearing pieces: the wire contract, the cache tiers, the step ladder itself, and four honest risk confrontations — against measured numbers, not extrapolation (the T-1143 planetary rung is the named cautionary tale).

Context — settled premises (not for relitigation)

From the outline + two clarification rounds (clarifications.md)

• prep rulings (Jeroen, 2026-07-25):

1. Lazy/late compute. Nothing computed in the game loop that game state doesn't need; smart precache allowed, never blocking user output. TTL = f(detail level, time, distance); player focus = character location AND atlas viewport.
2. Server determines content; client draws art. The server answers "what is at this world coordinate at this zoom step"; the client styles it. Derivation is CPU/Rust server-side only — GPU is presentation only (locked; the two-language-mirror liability, T-1170 precedent).
3. Stepped zoom. Scroll clicks through discrete levels; cursor-anchored centering, edge-scroll pan, and full-zoom-out-reset survive. A client-side morph/tween between steps is an investigation item (cosmetic only, never re-derivation). Supersedes the continuous-multiplier zoom (T-1143 ruling 3) — recorded as a deliberate revision at filing.
4. Vocabulary: tile = the 1×1 m ground unit (D-243), only. Gridunit (at zoom level) = the per-step data cell. The ladder bottoms out at ~10 px per tile on the viewport's smaller axis.
5. Data resolution is a tunable: 1 gridunit per screen px ideal; ~1 per 5×5 px display unit acceptable ("crisper is better, but the computer must not catch fire"). Decided by measurement.
6. Hydrology = deterministic equilibrium. Lake fill, overflow re-routing, gorge carving: a settled end-state, pure function of seed + moisture/climate, extending D8 drainage. No stateful simulation.
7. Render baseline (locked): per-step data canvas → render-to-texture terrain layer (texel-exact, drawn 1:1 or at the tunable ratio) + unscaled screen-space sibling layer for vector annotations (literal px sizes). Open within the baseline: shader-vs-CPU styling (c1) and the step morph.
8. Step boundaries = compute-chunk boundaries for the deterministic generators.
9. Jeroen's cache direction (to cost and confirm, not overturn): the primary atlas cache lives client-side — received step canvases are retained (compressed to what's needed) and simply not re-requested; determinism makes this safe (a canvas for a fixed seed never changes). Only sim-state components (frozen/flooded — "maybe shorter ttl on the climate sim state components") need invalidation at all. Open within this premise (Jeroen, sign-off round): whether the client needs a dedicated cache store — disk-backed, redis-like TTL semantics, self-cleaning records — rather than in-memory retention only; his lean: "on disk probably, but with self cleaning of cache records." D-227's discipline applies client-side too: whatever the store, it is an evictable cache, never a source of truth.

Governance delta (full analysis: tyre-implications.md §1): amends the D-166 corollary (anti-over/undersampling becomes a per-step property — repointed, not deleted), T-1143 ruling 3 (stepped supersedes continuous), the select_rung coverage walk (replaced by step index), D-243 (adds gridunit), and likely triggers the tagged-envelope migration (D-225's deferral — expected scope, not a risk to avoid). Survives untouched: D-227 derive-don't-store (the TTL cache is its concrete eviction policy), D-010, D-226(d)'s whole-body prohibition, D-169/D-170, and the T-1170 carrier three-way rule (repointed "window" → "step canvas").

Red flags the workshop must confront (stated honestly, not to relitigate)

1. Between-step magnification. Just before a step-cross the held texture is a magnified coarser composite — the exact thing D-166 forbids — for one step interval. Step count + px-per-gridunit are the knobs that keep it imperceptible; the D-166 amendment must own this.
2. "Always keep global" memory. ~1.6 MB/body at 5×5 ≈ ~440 MB across ~273 bodies if never-evict; ~13 GB at 1×1. The cache deliverable produces a number, not a vibe: always-derivable-fast vs permanent residency (vs disk tier — which must stay consistent with D-227).
3. Canonical-vs-viewport canvas is a governance boundary at the deep end. A canonical fixed canvas at 1 m spacing is a near-whole-body metre-resolution derivation — violating the D-226(d) prohibition that survives. Viewport-sized keeps the deep ladder legal by construction. Not just a cache tradeoff.
4. Cliff/multi-height gap. Settled hydrology produces gorges; a gorge is two heights in one gridunit; the sketched payload carries one height. Either a vertical-structure field at Phase-4 Atlas scope, or cliffs are Phase-5 geometry with a "steep" classification on the map. The hydrology measurement must output the cliff representation, not just cost.
5. Tagged-envelope migration is expected scope — tier: challenging but doable (executing D-225's planned deferral, not inventing a migration).

Participants

Dudley, Araminta, Stig, Tyre, Troblum (round 2 only) (+ Qatux documenting, SI reviewing ticket outputs)

Questions for participants

Dudley:

1. The equilibrium hydrology solver: algorithm choice (priority-flood family with overflow re-routing + gorge carving), measured cost at 512×256 and 4K-class, and the cliff/two-heights output representation (red flag 4).
2. Step-canvas generation and the canonical-vs-viewport data canvas (red flag 3): cost, cache shape, and the D-226(d) boundary at the deep steps.
3. Compute-chunk partitioning: how a step's derivation decomposes across the Rayon queue (chunked par_iter at 330K–8.3M cells — measured, not extrapolated) with step boundaries as the chunk boundaries (premise 8).
4. Cache tiers server-side: what "always keep the global level" costs across ~273 bodies (red flag 2), and the TTL(detail, time, distance) eviction policy as D-227's concrete instantiation.

Araminta:

1. Named-feature encoding (THE wire decision): dense classification rasters + sparse feature list vs inline identity vs ids-with-lookup — for rivers, settlements, roads, POIs and their names. Jeroen's constraint: "best fidelity vs wire contract possible; the information the client needs needs to be there." Feeds the tagged-envelope call.
2. The per-gridunit payload schema: exactly which typed fields the map-art function receives (biome, ground type, height, flooded/frozen/sea, river/settlement presence + identity), and what the client is allowed to do with them.
3. Encoding continuity across steps: one colorizer family (T-1143 §6), average-back across step boundaries, and what "different classes of content at lower zoom" (forest → clearings/ponds) means for the classification vocabulary.

Stig:

1. The client map-drawing component: structure of the RTT terrain layer + unscaled screen-space annotation layer, replacing the _canvas.scale model; what of the existing atlas/ cluster survives vs retires (T-1158 decomposition folds in here).
2. Step-cross experience: hold-fetch-swap, the morph investigation (cosmetic tween only), ImageTexture upload cost per step, and the client-side cache (premise 9: retain received canvases compressed, stop re-requesting; sim-state components TTL'd).
3. Overlay compositing under RTT (temperature/moisture/vegetation toggles, glaciation modifier): shader vs CPU styling — the (c1) decision, including T-1175's tapering/width grammar coming along for free if shaders win.
4. The client cache store (premise 9's open half): does the map cache need a persistent, disk-backed store with self-cleaning TTL records (redis-like semantics in an embedded shape), or does in-memory retention suffice per session? Fact base (verified, sign-off round): SQLite ships with the game but not inside the Godot client — the Rust server (a local subprocess) owns the SQLite path (systems.db, D-138 persisted state); the client's only addons are gdUnit4 and messagepack. Three candidate shapes to cost (with Dudley on the first): (i) server-side SQLite cache DB — zero new dependencies, "client-primary" reads as local-machine-primary (a warm local subprocess answering from disk is nearly as snappy as client memory); (ii) godot-sqlite addon in the client — a real client-side store, one new dependency; (iii) plain Godot FileAccess cache dir + index — no dependency, hand-rolled TTL sweep. Hard boundary in every shape: the cache is its own file — systems.db is the read-only canonical snapshot (asset-pipeline golden rule) and never doubles as cache. Size the store from the wire table (④); D-227's cache-never-truth constraint applies at every tier.

Tyre:

1. Ratify the governance delta (§1 of your implications pass) as concrete amendment texts: D-166 corollary repoint, T-1143 ruling revision, D-243 gridunit entry, the tagged-envelope decision.
2. The gridunit ↔ D-243 reconciliation: does gridunit spacing snap to the absolute-metre rungs or float freely per viewport/step? (Your "most load-bearing vocabulary reconciliation.")
3. The determinism boundary in the new split: server-resolved geometry vs client art — where exactly may the client interpolate ("tween rivers/roads") without creating a second truth?
4. The cliff/multi-height ruling proposal (with Dudley's measurement output).

Troblum (round 2):

1. Stress the cost story against the measured appendix — find the extrapolation.
2. The memory budget (red flag 2) and the wire-size table under realistic play patterns (step-thrashing, body-hopping).
3. The deepest-step extent vs D-226(d) (red flag 3) — verify the chosen canvas policy actually holds the boundary.

Questions for Jeroen (lead interview, each round):

1. Map time axis: climatology vs current sim state for frozen/flooded — your "shorter ttl on climate sim state components" hint as the working model?
2. Step count and the step factor (largest → visible tile), once the measured costs frame what a step can afford.
3. Canonical vs viewport-sized data canvas — you saw value in both; the deep-step governance boundary (red flag 3) may force the split answer (canonical shallow, viewport deep).
4. Phase-5 reuse: is the map-drawing component the future in-world viewport's code path, or Atlas-only? (Scopes the component's ambitions.)

Workshop Format

2 rounds + lead interview per round; extendable at Jeroen's call — after each round Jeroen is asked whether another round is needed, for as long as he feels necessary (workshops are not closed early on partial convergence).

• Gate: round 1 does not start until measurements ①–④ below are done and their numbers are in this brief's appendix (⑤ may land during round 1).
• Round 1 — positions. Each core participant answers their question slice against the measured numbers, in writing ({agent}-round1.md).
• Lead interview 1. Jeroen rules on what round 1 surfaced (step count, canvas policy, map time axis).
• Round 2 — synthesis. Cross-cutting decisions: the wire contract + tagged-envelope call, gridunit↔D-243, cache-tier architecture, the cliff ruling. Troblum's adversarial pass runs here against the whole picture.
• Lead interview 2 → sign-off or another round.
• Filing: D-records claimed and written before dismissal (amendment set per the governance delta + the new render-architecture record), including the explicit deprecation sweep (Expected Output 2) — a Clerk consistency audit verifies no conflicting record or ticket is left standing before the team is dismissed; tickets drafted by the lead, reviewed by SI; Qatux produces workshop-outcomes.md and diagram updates.

Pre-workshop measurement appendix (owners; numbers land here before round 1)

#	Measurement	Owner	Effort
①	Equilibrium hydrology solver prototype + bench (512×256 and 4K-class) incl. cliff representation output	Dudley	1–2 d
②	Per-gridunit derive at real canvas sizes (330K and 8.3M cells, production par_iter path — no extrapolation)	Dudley	0.5 d
③	T-1154 block/tile rung costs (now unblocked) — prices the ladder's bottom	Dudley	0.5 d
④	Wire-size table for candidate encodings (raw/bit-packed/RLE/PNG; MessagePack round-trip on one real canvas)	Araminta + Dudley	0.5 d
⑤	Godot ImageTexture upload cost per step-cross (330K–8.3M px)	Stig	0.25 d

Input Documents

Doc	Why
jeroen-outline.md	The design, verbatim
clarifications.md	Settled premises + deferred deliverables, verbatim answers
tyre-implications.md	Governance delta, candidate re-ranking, red flags
prep-grounding.md	Current mechanism, error-class evidence, measured baselines
docs/architecture/atlas-zoom-ladder-t1143.md	The predecessor ladder design + Jeroen's three rulings
docs/architecture/river-courses-t1170.md	The carrier three-way rule (survives, repointed)
governance/decisions/architecture.md	D-166 amendment+corollary, D-226 chain, D-227, D-243, D-239, D-225

Expected Outputs

1. D-record set: the body-map-viewer render architecture (new record) + the amendment set from the governance delta (D-166 corollary repoint, T-1143 ruling revision, D-243 gridunit vocabulary, tagged-envelope decision, cache/TTL policy as D-227's instantiation).
2. Explicit deprecation sweep — no conflicting record left standing (Jeroen, sign-off round). Every DQR record and ticket that conflicts with the decided setup is explicitly amended, superseded, or deprecated in the same filing pass — never left silently contradicting. Starting set = the governance delta's known conflicts (the D-166 corollary sentence, T-1143 ruling 3 and its select_rung coverage-walk model, the windowed-family ceiling if the tagged envelope is chosen); completed by a systematic consistency sweep (Clerk audit) to catch conflicts the delta did not name. Conflicting tickets are cancelled or re-scoped with the supersession noted on the ticket (T-1158 subsumed, T-1154 repurposed as measurement ③, T-1175/T-1157/T-1174 reconciled in the ticket plan).
3. The step ladder: step count, step factor, per-step gridunit spacing and its D-243 relationship, the deepest step's canvas policy.
4. The wire contract: per-gridunit payload schema + named-feature encoding + envelope framing, with the measured wire-size table.
5. The cache architecture: client-primary retention (premise 9) + the client store decision (in-memory vs disk-backed with self-cleaning TTL) + server tiers + TTL formula + the global-tier memory answer.
6. Ticket plan: implementation chain (measurement-informed), explicitly reconciling T-1158 (viewer decomposition — subsumed), T-1175 (polish — styling engine dependent), T-1157 (capture harness — the new mechanism's verification story), T-1174, and the retirement path for the _canvas.scale model.
7. workshop-outcomes.md + updated diagrams (Qatux).