# 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).

### Retired-or-carried at the v4.0 close (ROUND22 ledger #6 — Lane A, line by line)

Verdicts against the **full 23-town pack** (1,210 shops), not against the 5-town sample the list was
written for. "Retired" means a law now enforces it and the pack proved the law holds with headroom.

1. **RETIRED — enforced, with headroom.** `MAX_TOWN_SPAN_M` (5 km) is validator-enforced, so a breach
   fails loudly at load, not silently in the plan. Widest in the pack: **geelong at 3,829 m — 77% of the
   ceiling**; no town came close to the law. Mega-strips are now a *pipeline curation* question (E's), and
   the generator's fence is the backstop it was designed to be.
2. **RETIRED — the floor never bound.** `MIN_TOWN_SHOPS` is 6; the thinnest town in the pack is
   **darwin at 12 — 2× the floor**. No cache was rejected for sparsity. (Whether a 12-shop town *reads*
   alive is a different question and a live one — it's D's thin-tail spot-check this round, not a
   generator risk.)
3. **RETIRED on the plan side; CARRIED for the runtime lanes.** This was the alpha's real risk and it
   paid off exactly as intended — the irregular graphs surfaced fragmentation (R19), capacity (R20) and
   venue stranding (R21), each fixed-or-fenced and written down. At 23-town scale A's side needed **no
   new hardening**: 1 connected component and 3 venues on every town, all invariants green, fitzroy's 160
   shops included. **Carried** only where it hasn't been measured yet: C's door-soak, D's fitzroy audit
   and F's matrix are this round's verifies — the plan being green is not the same as the town rendering
   and simulating green.
4. **RETIRED — the knob is at a measured setting.** Junction-protected Douglas–Peucker settled it
   (katoomba 105 → 11 components; cull/bridge → 1 component at 100% main-net, and now **1 component on
   all 23**). The fidelity/edge-count trade has a floor that holds across the pack; it is no longer an
   open question, and any future move re-pins goldens under the amendment law.
5. **Unchanged** — still settled, now on 23 towns rather than 5.
6. **NEW, CARRIED — thin-graph seating capacity.** The pack's honest tail: **6.4% of shops don't seat**
   (77 of 1,210), all counted by cause, dominated by overflow where a town has more shops than its road
   graph has frontage. Outliers: **daylesford 19%** (32 shops on 171 roads — the thinnest graph in the
   pack by 2×) and **fitzroy 13%**. `RGAP` is already 0.5 m and `NODE_CLEAR` 3 m; the only lever left is
   spilling overflow onto a *different* street, which buys a few percent by putting a shop on a road it
   isn't on. Ruling stands from R20: **drop and count beats teleport.** Carried into v4.x as a known,
   measured, per-cause-attributed tail — not a defect, and not hidden.