Fable (integrator): v4 REAL MAP charter + round-18 instructions — v4.0-alpha REAL ROADS (katoomba_real)

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

docs/LANES/ROUND18_INSTRUCTIONS.md

@@ -0,0 +1,84 @@
+# PROCITY — Round 18 lane instructions (from Fable, integrator)
+
+Date: 2026-07-16 · **v3.2 SHIPPED** (tag on origin, town matrix 10×5 green). R17 review, short
+version: the tail is DRAINED — wind sway shipped after ten rounds parked (and the park reason
+turned out to be a phantom: the tree material was B's own all along — measurement over folklore),
+D's drummer leans into the kit and street peds sit on verandah steps (with a genuine finding en
+route: the seated re-plant was scale-naive and had to become scale-aware for per-citizen-scaled
+rigs), C closed the backline handshake AND proactively proved 18 real OSM shop types build valid
+interiors, E's 5-town pipeline is deterministic and ODbL-clean, A hardened `plan_osm` against
+2,828 real Canberra shops and handed the charter its risk list, F closed the last integration gap
+(the shell never loaded the caches — the classic A-publishes/F-wires seam) and gated the whole
+matrix. Every lane at full quality. The scout did its job: **John chartered v4 = THE REAL MAP.**
+
+**Read the charter first: [docs/V4_REAL_MAP.md](../V4_REAL_MAP.md).** Round 18 is
+**v4.0-alpha: REAL ROADS** — one town (`katoomba_real`) gets its actual street geometry. The whole
+alpha exists to surface what irregular real geometry breaks downstream. Tag **`v4.0-alpha`** at
+close.
+
+## The ledger
+
+1. **Cache schema v2 — `roads[]` (A publishes FIRST, E builds to it).** The town cache grows an
+   optional `roads[]` (OSM way geometry, simplified): A defines the shape (suggested: polylines of
+   `{lat,lon}` points + a `kind` from the OSM `highway=*` class), bumps `schema` to
+   `procity-town-cache/2`, extends `validateTownCache` (v1 caches stay valid — roads absent ⇒ the
+   marched fallback, so nothing shipped regresses).
+2. **Real road graph in the plan (A — the epoch's headline lift).** `plan_osm` consumes `roads[]`:
+   project to the local metre frame, simplify (Douglas-Peucker or your pick — you own the fidelity
+   knob, charter risk #4), build the CityPlan street graph from real topology (nodes at real
+   intersections, straight-segment edges), classify main/side from the OSM `highway` kind + shop
+   density, seat each shop's lot on its nearest real edge at its real position/side. SAME CityPlan
+   schema out — B/C/D/F consume it unchanged by contract. Golden per the amendment law
+   (`katoomba_real`'s re-pins; synthetic + fixtures untouched). District placement (`pickVenues`)
+   must still land 2–4 venues on the real graph.
+3. **Roads fetch (E).** Extend `build_towns.py`: per-town bounded `highway=*` Overpass query
+   (same authorization + raw-cache discipline as R17 — commit the raw response, fetch once),
+   emit `roads[]` per A's v2 contract. **`katoomba_real` first** (the alpha town), then the other
+   four as data-only commits (A hardens against them as they land; only katoomba gates the round).
+4. **Irregular-geometry audit (B — charter risk #3, the alpha's real risk).** Boot
+   `katoomba_real` with real roads and hunt what breaks: chunk streaming over a non-grid graph,
+   building/lot seating at acute intersections, footpath/verge furniture cadence on short or
+   curved-ish edge chains, tram (its loop assumes a spine — if the real graph breaks it, fence it:
+   tram disabled on roads-towns is an acceptable alpha fence, written down). Fix what's yours,
+   file what's A's (lot geometry) or D's (sim graph) with measurements.
+5. **Citizens on real bones (D).** The sim walks the street graph + chunk-streamed rosters on the
+   real topology: verify walkers navigate real intersections, loiter/bench-sit/patronage behave,
+   identity + determinism hold on `katoomba_real`. Cheap if the graph contract really is the
+   contract — prove it, and file what leaks with measurements.
+6. **Interior spot-soak on the alpha town (C — small).** Your R17 type-fallback proof covered
+   types; now enter every `katoomba_real` shop in-shell (20 doors), assert valid interiors, no
+   carve fails, budgets. One table. Otherwise on-call.
+7. **The alpha gate (F, last).** Extend the town matrix with a roads dimension (`katoomba_real`
+   boots real-roads: boot/determinism/budget/district/noassets-fallback green); the classic +
+   default-boot gates prove the alpha changed nothing outside the flagged path; a first
+   real-street money shot (Katoomba main street, default flags, settled) into
+   `docs/shots/v4_alpha/`; docs (README gets a "real towns" paragraph, LANE_F_NOTES §18); tag
+   **`v4.0-alpha`**, push (standing authorization).
+
+## Laws for the round
+
+Everything in the charter's law section. Alpha-specific: real roads ride the **cache schema**, not
+a URL flag (a v2 cache with roads = real roads; v1 = marched fallback — no new flag surface);
+default + classic boots are untouched by construction (they never load a town cache); budgets
+measured on `katoomba_real`'s busiest real block; every irregular-geometry failure gets WRITTEN
+DOWN (fixed or fenced) — the alpha's deliverable is as much the failure list as the town.
+
+## Order
+
+**A first** (schema v2 contract — half-day rule), **E immediately after** (katoomba roads cache;
+the other towns trail). Then **A again** (the graph lift, against real data), with **B + D + C**
+auditing in parallel as soon as A's roads-plan boots (A→B/D/C handshake: "katoomba_real boots with
+real roads, golden pinned"). **F last.** This round has a real serial spine (A→E→A→others→F) —
+expect A to be the long pole; B/D/C, if you're blocked on A, your audit prep (test scaffolding,
+assertion lists) is not.
+
+## Standing
+
+- **John — nothing blocks this round.** FYI: E's roads fetch rides your R17 Overpass
+  authorization (same API, same once-per-town + raw-cache discipline). The alpha hero town is
+  `katoomba_real` — if you'd rather see a different town first (Newtown/Fremantle/Bendigo/
+  Castlemaine), say so before E starts.
+- **v4.0-beta preview (next round, do not start):** all five towns on real roads · the town
+  selector UI (B) · districts/gigs proven per-town · tram ruling on real graphs.
+- **Backlog (unchanged):** instrument LOD · tram tri diet · audioEmitter · flag retirement ·
+  awning-canopy ripple (B's R17 note) · editor · multiplayer presence.

docs/V4_REAL_MAP.md

@@ -0,0 +1,52 @@
+# PROCITY v4 — THE REAL MAP (epoch charter)
+
+*Fable, 2026-07-16. John's pick (R17 kickoff). Grounded in the R17 scout: 5 real AU town caches
+boot through the full gate matrix — deterministic, in-budget, districts place, `?noassets` silent.
+The existing CityPlan contract eats real shop data. What it does NOT yet eat is real geography:
+`plan_osm` marches real shops onto synthesized parallel avenues. v4 closes that gap.*
+
+## The vision
+
+**Walk the actual main street of a real Australian town.** Katoomba's real high street with its
+real secondhand shops in their real order, PROCITY's stylized look (this is not photorealism —
+the *town* is real, the *rendering* is PROCITY), the gig district, the citizens, the dig, the
+weather — everything shipped, on real bones. The default boot stays the synthetic town; real
+towns are a destination you pick.
+
+## The stages
+
+- **v4.0-alpha (R18): REAL ROADS, one town.** Real OSM street geometry (simplified to the
+  CityPlan edge schema — straight segments, real topology) for `katoomba_real`, shops seated
+  along their real streets, everything downstream unchanged by contract. Opt-in via the town
+  cache (schema v2 carries `roads[]`; caches without roads keep the marched fallback).
+- **v4.0-beta: the district on real bones, five towns.** All scouted towns get roads; venues,
+  posters, queue, tram(?), citizens proven on irregular graphs; the town selector (B) so a player
+  can pick a town without URL surgery.
+- **v4.0: the town pack + the tour.** A curated pack (~15–25 towns, E's bbox discipline), the
+  release tour shot on real streets, docs, tag. Default boot still synthetic; flag-flip for real
+  towns is a v4.x decision AFTER soak (the v3 pattern, proven twice).
+
+## The laws (inherited, plus two new)
+
+Classic covenant untouched (`?classic=1` byte-identical forever) · default boot untouched through
+alpha/beta (real towns opt-in) · determinism from (town, citySeed) · budgets unchanged (≤300/200k
+street, ≤350 interior) · asset law (cache fetch fail-soft; `?noassets` falls back to fixtures) ·
+amendment law for goldens · atomic pathspec commits · measurement over brief.
+
+**New — the bbox law (A's R17 risk #1):** a town cache is ONE compact town (span ≤ 5 km,
+validator-enforced); town *selection* discipline lives in E's pipeline, because the generator
+cannot rescue an over-broad query. **New — the ODbL law:** every cache ships
+`license`/`attribution` + `SOURCES.md`; raw Overpass responses are committed so re-runs never
+re-fetch; only public POI/way data, never private-individual data.
+
+## The risk list (from the R17 scout, kept current)
+
+1. Mega-strip / over-broad bbox — mitigated by the bbox law; watch per-town.
+2. Sparse towns (< 6 shops) — curation floor; `MIN_TOWN_SHOPS` enforced.
+3. **NEW, the alpha's real risk: irregular geometry downstream.** B's chunks/buildings/furniture
+   and D's sim have only ever seen A's synthetic graphs and the marched-avenue osm towns.
+   Non-grid intersections, acute angles, short edges, dead ends — the alpha exists to surface
+   exactly these. Every failure gets written down, fixed or fenced.
+4. Road simplification fidelity — too coarse reads wrong, too fine costs edges; A owns the knob.
+5. Settled non-risks: facade clearance on osm towns (R17), interior types (C proved 18 real
+   `shop=` values degrade cleanly), plan-side determinism (E's pipeline is byte-identical re-run).