PROCITY/docs/V5_REAL_SHOP.md

PROCITY v5 — THE REAL SHOP (epoch charter)

Fable (m3, integrator), 2026-07-16. John's pick at the v4 retro. Grounded in: the Lane G marriage (merged, ruled, G2a atlas contract reviewed by C/E in R22), dealgod's 1.77M real items with photos, thriftgod's census already driving newtown_godverse, and the v2-era dig/wallet/ stock machinery that has been waiting for this data since it shipped.

The vision

v4 made the towns real; v5 makes the shops real. Walk Fitzroy's actual street into an actual op shop, riffle a crate, and the records in it are that shop's real stock — real covers, real titles, real prices. Buy one and it's gone, because it was one-of-a-kind in the real world. Thriftgod is the brain and the bank; PROCITY is the body.

The tier ladder (the epoch's load-bearing idea)

Stock is a DATA TIER, like assets — each tier fully playable, each degrading softly to the one below. This is the offline law made structural:

tier	source	flag state	deterministic?
0 · parody	seeded canvas sleeves (v1)	any boot, always works	yes — the QA baseline
1 · static real	per-shop atlases baked from dealgod (G2a)	?stock=real, no server	yes — atlases are files
2 · live GODVERSE	thriftgod server: live stock, sold-means-gone (G3)	server reachable	no — by design

The seeded-everything law is NOT weakened: the world (geometry, layout, venues, citizens) stays seeded and byte-identical; stock contents are inventory data riding the asset law. QA gates run on tiers 0–1; tier 2 gets its own smoke class (reachability, fail-soft, latency) that never gates a tag on server state.

The stages

• v5.0-alpha: THE FIRST REAL CRATE. One real shop end-to-end — a Newtown record shop in newtown_godverse, static atlas (G2a), riffle real covers, buy, wallet debits, every tier degrades clean. Plus the G3 design doc ratified (both integrators + John) before any server code exists.
• v5.0-beta: THE REAL SHOPPING TOWN. Every hero shop in 1–2 godverse towns carries real static stock; godverse coverage grows where thriftgod's census is dense (fitzroy is the prize); pricing from thriftgod's mint() profiles baked into the atlases; the dig UX polished for real items (title/price cards are real data).
• v5.0: THE LIVE TIER. Thriftgod's server behind tier 2 per the ratified G3 design: live per-shop stock, sold-means-gone, reservation semantics — with the offline law proven by the gate (kill the server mid-session; the game degrades to tier 1 without a stutter). Tour, docs freeze, tag.

The laws

Everything inherited (classic covenant 0x3fa36874 forever · determinism for the world · budgets · amendment law · measurement-over-brief · drops counted · fresh-context verification), plus this epoch's own:

1. The offline law (non-negotiable, from the standing G3 ruling): the server enriches, never gates. Full offline play at tier 0 and tier 1, always. No boot path, gate, or tag may depend on a reachable server.
2. The determinism boundary: world = seeded, frozen, gated. Stock = data tiers. Tier 2 is openly non-deterministic and therefore never inside a golden or a byte-identical assert.
3. The licence law (extends E's provenance spine): item photos are the stores' own product shots — 🟢 for in-house play; flagged before any public/commercial release (G's own note, now law). No private-individual data, ever. Every atlas carries provenance.
4. The write-back law: game purchases NEVER mutate real thriftgod inventory without an explicit, John-ratified reservation design in the G3 doc. Until then tier 2 is read-live, sell-sandboxed. (Whether "sold in game" can mark real stock is John's call to make in the design review, not a default.)
5. The two-studio law: G owns pipeline/godverse_*, web/assets/stock_godverse/**, godverse caches, and the server side; A–F own their lanes; cross-repo contracts publish FIRST; both integrators sign the G3 design. Merge amendment: when a round's brief names a G deliverable as gating, G's branch merges mid-round after Fable-m3 review (G's file namespace is disjoint, so pathspec safety holds); otherwise boundaries as before.

The risk list (kept current, v4-style)

1. Latency/stutter at tier 2 — server calls must be async enrichment; the dig must never block on the network. The G3 doc owns the caching design.
2. Atlas budgets at real density — a mecca hero shop can hold hundreds of real items; C's interior ceilings are the law and the atlas contract must respect them (pagination/crate rotation rather than bigger atlases).
3. Census↔OSM identity — matching thriftgod shops to godverse lots is fuzzy (names drift, shops move). Mismatches must be counted and fail-soft to tier 0, never mis-stocked.
4. Sold-means-gone semantics — race conditions, reservations, and the write-back question. All design-doc territory; nothing ships before ratification.
5. Settled non-risks: the dig/wallet/stockAdapter machinery (shipped v2, soaked 16 rounds); static-atlas determinism (E's byte-identical pipeline discipline); the fail-soft ladder (proven pattern from ?noassets day one).