PROCITY/docs/V4_REAL_MAP.md

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