settled-reach/docs/workshops/atlas-derivation-model.md

Workshop — The Atlas → Tile Derivation Model

Driven by the water model, but the water model is only the forcing instance.

Why this, why now

We are building the generation cascade (Phase 4). The viewer (#960) surfaced a problem that looks like "lakes" but is actually the inter-level derivation contract: how coarse, map-scale planetary data becomes fine, coherent, per-tile geometry without squared/blocky artifacts. This is cascade-first: if we bake the wrong derivation model now, every layer below (economic → settlement → quarters → tiles) inherits it and it becomes very expensive to unwind. Decide it before those layers exist. Stations are out of scope here — bodies first.

The methodology: reverse the derivation

Do not start from "what can the cascade derive?" Start from the target:

Build the complete list of everything a tile on a body must contain. Then work backward: for each item, how do we derive it deterministically from (a) a prebaked atlas dataset and/or (b) a seeded algorithm?

The requirements list is the spec. The cascade is the mechanism that satisfies it. We want the list first so the cascade is designed to a known target, not grown by accretion.

The three legs (generalized from the water instance)

1. Dual artifact — baked render ↔ semantic model. The reliefmap should have lakes/rivers/coastlines baked in (authoritative visual, no toggles — yes, that means regenerating reliefmaps). Separately, there is a semantic model (rivers as flow-carrying paths, lakes as regions, coasts as curves) that is the authoritative generation input. The reliefmap is a render of the model at map scale; the model is what lower levels consume.

2. Multi-scale refinement contract — hint, not squared truth. A reliefmap pixel is a map-scale rendering, not ground truth to copy downward. A 2-px river (sized for map visibility) is kilometers wide at tile scale; a land/water pixel edge is a staircase coastline. So coarse data is a semantic hint + a seed, and each lower level deterministically refines it into smooth, ~1-tile-scale geometry that respects the hint without copying its resolution. "Somewhere in this band a coherent coastline passes"; "a river of roughly this flow threads this corridor."

3. Context-driven algorithm family — selection is part of generation. Refinement is not one algorithm. The choice is driven by local context:

• Rivers: low slope → meandering, wide, lazy, floodplains/oxbows; steep → incised, straighter, gorges, knickpoint waterfalls; (braided/deltaic at the extremes).
• Coasts: low relief + sediment → smooth dune-lined strands; hard rock + high relief → craggy cliffs; drowned glaciated valleys → fjords.

Contract: hint + local context + seed → algorithm selection → geometry. Same hint, different terrain, genuinely different feature.

The expanding atlas (a key consideration for the brief)

Satisfying the per-tile list will almost certainly require more prebaked planetary layers than heightmap + reliefmap — plausibly: lithology distribution, a water-bodies layer, prevailing winds, temperature/precipitation, glaciation history, biomes. The workshop must take a position on:

• Which layers are prebaked vs runtime-derived (storage + determinism + the modding story — D-225's mod-first intent applies).
• Context data we have vs owe: slope/relief derive from the heightmap, but lithology (crag-vs-dune) and glaciation (fjords) may not exist yet. Decide whether morphology is selected from proxies we have, or a thin new context layer is owed (with its determinism + ownership cost).
• Organizational (future, "at some point"): moving all wiki content + heightmaps into a new gamedata/ atlas subtree sitting next to server/ and client/. Not a round-1 deliverable, but flag whether the data model implies it and roughly when.

Questions to resolve (each → a D-record or a tracked open question)

1. The per-tile content requirements list — the target (reverse-derivation).
2. Biome authority — planet-gen reliefmap coloring vs in-cascade subbiome::classify; which is canonical, and what that implies for where water (and other features) is authored.
3. The atlas dataset family — which layers are prebaked; format; determinism.
4. Dual artifact — baked reliefmap ↔ semantic model: representation + how they stay in sync (regen pipeline).
5. The refinement contract — the inter-layer hint+seed→geometry API; anti-squaring; how each layer hands constraints to the next.
6. Context-driven morphology — the algorithm families + the context inputs they require; the have-vs-owe data fork.
7. Cascade placement + gamedata/ restructure — where water/derivation is authored; restructure scope/timing.
8. Determinism — D-010 integer-only must hold across all refinement + selection (seed → identical geometry).

Team angles

• Tyre — architecture: the derivation/refinement contract, dual raster + semantic data structures, deterministic downscaling, atlas-layer storage, the gamedata/ restructure feasibility, performance/memory at tile scale.
• Nigel — procedural variety/emergence: does the algorithm family + reverse-derivation yield rich, sensible, non-repetitive worlds across seeds? Where does sameness creep in? What's the second-playthrough payoff?
• Gestalt — systems meaning: drive the per-tile requirements list from "what creates interesting decisions / gameplay," and the consequences of morphology (a fjord is a deep defensible harbor; a meandering river is fertile + bridgeable; a craggy coast resists landing).
• Burnelli — economic layer needs: what the economy reads from the atlas — water as trade corridor vs barrier, ports/harbors, resource distribution, the regional scale the economy actually operates at.

Round 1 task (each agent)

Read this brief + the pointed code/decisions, then post an opening position on your angle that includes:

1. Your contribution to the reverse requirements list — what must a tile (or the data feeding it) contain, from your lens.
2. The key forks/risks you see in the derivation model.
3. Anything in the current code/decisions that constrains or contradicts the approach.

This is investigation + position, not final design. Flag blockers early (heartbeat rule below).

Reading

• Code: server/src/atlas/heightmap.rs (normalized elevation + sea_level, downsample), server/src/atlas/drainage.rs (existing depression_fill, D8 routing, rivers/basins, the new Moore boundary trace), server/src/atlas/layer1.rs (Layer1Output incl. grid_w/grid_h), server/src/atlas/layer_proxy.rs (D-225 proxy). tooling/planet-gen/ — render_heightmap.py, planet_renderer.py (ocean colors, biome coloring), planet_simulation.py (max_elevation_km, biome assignment).
• Decisions: D-202 (canonical 16-bit heightmap), D-208 (drainage), D-209 / D-210 (attractors / sub-biomes), D-225 (layer-stream proxy, mod-first), D-166 (generation-before-player). The cascade phase table in CLAUDE.md.
• Constraints: D-010 (determinism, integer-only), cascade-first (no detail from a later phase), the no-squaring principle above.

Process

Round-based. The lead synthesizes after each round and pulls Jeroen in — he decides when to dismiss. Close only when D-record(s) + ticket(s) exist (hard deliverables). Teammates edit files; the lead does all git.

Heartbeat rule: if you work a single task >15 min without progress, message the lead with what's blocking you. Do not silently retry.