diff --git a/docs/LANES/ROUND23_INSTRUCTIONS.md b/docs/LANES/ROUND23_INSTRUCTIONS.md new file mode 100644 index 0000000..37e77f8 --- /dev/null +++ b/docs/LANES/ROUND23_INSTRUCTIONS.md @@ -0,0 +1,89 @@ +# PROCITY — Round 23 lane instructions (from Fable, integrator) + +Date: 2026-07-16 · **v4.0 SHIPPED, the epoch retro is written ([RETRO_V4.md](../RETRO_V4.md)), +and John has chartered v5: [THE REAL SHOP](../V5_REAL_SHOP.md).** Read the charter first — the +tier ladder (parody → static real → live GODVERSE) and the five laws are the epoch's spine. + +Round 23 is **v5.0-alpha: THE FIRST REAL CRATE** — one real shop's real stock, riffled and +bought, end-to-end, plus the G3 design doc drafted for ratification. The v4.x tail runs as the +light parallel lane the retro promised. Tag **`v5.0-alpha`** at close. + +## The ledger + +1. **G2a: the first real atlas (Lane G, on ultra — the round's headline).** Build the per-shop + atlas pipeline per the R22-reviewed contract (C's ceilings · atlas-per-shop keyed by godverse + shop id · fail-soft to parody): dealgod inventory → a static atlas + index for ONE real + Newtown record shop in `newtown_godverse`. Files stay in the G namespace + (`pipeline/godverse_*`, `web/assets/stock_godverse/**`). Deterministic (byte-identical + re-run against the same inventory snapshot — snapshot the query result like you snapshot + Overpass raw). Provenance per the licence law (charter law #3). **This deliverable is + gating, so per the merge amendment (charter law #5) your branch merges mid-round once + Fable-m3 reviews.** Ping via G-progress when it's up. +2. **G3: the design doc draft (Lane G + both Fables).** `docs/G3_ECONOMY_DESIGN.md` covering: + API surface (read stock / price / reserve / buy) · async-enrichment caching (risk #1 — the + dig never blocks on network) · the determinism boundary (charter law #2) · failure modes + (server dies mid-session → tier 1 without a stutter) · census↔lot identity matching (risk + #3, mismatches counted) · **the write-back question stated as a decision for John** (charter + law #4 — options with trade-offs, no default). Draft this round; ratification is R24's + kickoff. Nothing server-side ships before it. +3. **The interior side of the real crate (C).** When G's atlas merges: verify the contract in + the room — the godverse record shop's crates resolve the per-shop atlas through the existing + `stockAdapter` path, interior draw/tex ceilings hold with real covers, `?noassets` and + missing-atlas boots fail soft to parody with zero errors. If the contract needs an + amendment, you own the wording (LANE_C_PUB), G re-emits. +4. **The atlas validator (E).** The format side: a `validate_atlas` check in the pipeline + (dimensions ≤ C's ceilings, provenance fields present, index↔atlas consistency, determinism + note) so G's output is gate-checkable on m3 without the dealgod DB. Plus the retro's + curation item: **the thin-tail clustering floor** — re-bbox toowoomba onto its actual retail + strip (or retire it, your call, counted either way) using D's median nearest-neighbour + spacing as the curation metric. +5. **The spacing warn (A).** D's metric becomes law: `validateTownCache` warns when median + nearest-neighbour spacing exceeds a threshold you pick from the pack's measured spread + (darwin 27 m alive, toowoomba 388 m dead — plenty of daylight for a line). Warn, not error — + E curates, the validator flags. Re-pin only what E's toowoomba fix moves. +6. **GIG_RANGE chunk-neighbour fix (D — the carried v4.x item).** The 8.7% blind spot: extend + `_nearestOpenShop` to the ped's chunk + 8 neighbours. Hot path, so bring the R18-style + before/after (perf cost, blind-spot elimination, determinism unchanged, byte-identical + flags-off). Post-release is exactly when this change is safe. +7. **The alpha gate (F, last).** + a. THE CRATE, end-to-end in a fresh browser: boot `newtown_godverse` with `?stock=real`, + walk into the real record shop, riffle — **real covers render** — buy, wallet debits, + the item leaves the crate (tier-1 static semantics: gone this session, back next boot — + that's correct until G3). + b. The tier ladder proven: same shop under `?noassets` (tier 0, zero fetch), missing-atlas + (soft fall to parody), `?stock=real` (tier 1) — all silent-and-fine; classic + default + gates frozen as ever. + c. `qa.sh --strict --matrix` green (the matrix now includes E's toowoomba fix), notes §23, + README one-paragraph v5 teaser, tag **`v5.0-alpha`**, push. + +## Laws + +The charter's five (offline · determinism boundary · licence · write-back · two-studio) plus +everything inherited. Golden discipline: only E's toowoomba re-bbox may move a town golden +(amendment law, one commit). No server code anywhere this round — the G3 doc is paper. + +## THE EXACT RUN ORDER + +1. **Start together: G (atlas + doc draft, on ultra) + E (#4 validator + toowoomba) + A (#5 + spacing warn) + D (#6 GIG_RANGE).** All disjoint. +2. **When G's atlas is up and Fable merges it: start C (#3).** E's validator should be ready to + run against the merged atlas — coordinate in G-progress. +3. **When C passes and E/A/D are in: F closes (#7)** — the crate, the ladder, the tag. +4. **G3 doc review runs asynchronously all round** — both Fables comment in the doc; it lands + ratified-or-revised at R24 kickoff with John's write-back ruling. + +Waves: **[G, E, A, D] → [merge, C] → [F]**, with the doc threading through. + +## Standing + +- **John — one decision incoming, not blocking this round:** the write-back question (does an + in-game purchase ever touch real thriftgod inventory — sandbox, reservation, or full + write-back?). It arrives framed with trade-offs in the G3 doc at R24 kickoff. FYI: G's branch + merges mid-round this epoch when its deliverable is gating (charter law #5); item-photo + licensing stays in-house-green, flagged before anything public. +- **B — deliberately light this round** (you've carried heavy since R16): on-call for C if the + crate render surfaces anything street-side, plus first pick of the v4.x polish list next + round (awning ripple and the tram-stop tri diet are yours when you want them). +- **v5.0-beta preview (do not start):** every hero shop in 1–2 godverse towns stocked · mint() + pricing baked into atlases · fitzroy_godverse if the census is dense there · the dig UX for + real items. diff --git a/docs/V5_REAL_SHOP.md b/docs/V5_REAL_SHOP.md new file mode 100644 index 0000000..4de51f9 --- /dev/null +++ b/docs/V5_REAL_SHOP.md @@ -0,0 +1,83 @@ +# 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).