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