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

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.