PROCITY/docs/G3_ECONOMY_DESIGN.md

G3 — THE ECONOMY BACKEND (design doc)

Lane G, R23 draft. Drafted per the v5 charter (V5_REAL_SHOP.md) ledger #2.

§7 (THE WRITE-BACK QUESTION) IS RATIFIED — John, 2026-07-17, R24 kickoff: A THEN B. v5.0 ships sandboxed (a game purchase never touches real inventory); reservation is chartered as a v5.x upgrade behind a hold budget John sets; full write-back is not chartered. Charter law #4 is satisfied. The rest of this doc remains DESIGN and still needs both Fables' sign-off; no server code ships before that.

Status of each section: [MEASURED] = verified against the real databases. [DESIGN] = proposed, not built. [RULED] = decided by John under charter law.

---

1. What the data actually is [MEASURED]

The charter assumed one join: thriftgod's census of real shops → dealgod's real items. That join does not exist. The three datasets are three different populations:

dataset	what it really holds	inventory?
thriftgod.shop	2,928 real AU secondhand shops, OSM-anchored (the census)	no
dealgod.stores	9,285 online sellers — 8,754 are Discogs accounts, not physical shops	1.77M listings
recordgod	one real trading record shop's POS — crates, slots, prices, grading	28,624 live

Measured consequences:

• No Newtown record shop has any stock, in any database. Egg Records, Papa Disquo, Haze Guitars, The Vintage Record, Downtown Music: 0 items each. dealgod has zero Newtown stores and zero census name matches.
• thriftgod.item (the minted table) holds 2,221 items across 29 shops — all Brisbane/ Newcastle/Alice charity shops. Zero record shops. It is a demo seed, not a stock system.
• This is not charter risk #3 ("fuzzy matching"). It is a population mismatch. Fuzzy matching cannot fix it, because there is nothing on the other side of the join to match to.

1a. The one shop where all three meet [MEASURED]

monsterrobot — 147 Musgrave Road, Red Hill, Brisbane QLD (John, R23) — is the same real shop in three forms, and that is the whole reason tier 1 can be honest:

recordgod (its POS)  ──┐
monsterrobot.party     ├── one real shop: real crates · real slots · real prices · its OWN photos
dealgod store 3962749 ─┘

• 28,624 live vinyl; 24,914 physically placed in 357 real crates with real labels ("DEEP HOUSE", "$12–$15 TECHNO") and real slot numbers — with gaps where records actually sold.
• Covers are the shop's own product shots on the shop's own domain, cached by dealgod (23,392 releases). 99.3% of its crate stock joins to a cached cover by Discogs release_id.
• It is not in thriftgod's OSM census, so its godverse id is its dealgod store id 3962749 (real, stable, clear of the census space — thriftgod max shop id = 2992).

Shipped this round (G2a): crate 550 "DEEP HOUSE" → 120 real records → web/assets/ stock_godverse/3962749/. Byte-identical re-bake verified.

---

2. Why mint() cannot be the source of any tier [MEASURED]

thriftgod's mint() is the obvious candidate for stocking shops. It disqualifies itself three ways:

1. It is not deterministic. FEED_RECORDS uses TABLESAMPLE SYSTEM (0.5); mint() uses random.random(), random.uniform(), random.shuffle(). random.seed appears nowhere in server.py. Re-running mint gives different stock at different prices. That is fatal to tier 1 (charter law #2), and it is why tier 1 reads the POS instead: a crate is a table of facts.
2. The shop assignment is fictional. mint samples arbitrary Discogs sellers' listings and assigns them to a census shop that never owned them.
3. Therefore it breaks two laws downstream. The licence law's green rests on "the stores' own product shots" — a Discogs seller's photo shown as Egg Records' stock isn't that. And the write-back question (§7) is meaningless for minted stock: you cannot mark real inventory sold for an item the shop never had.

mint stays what it is: a fun demo seeder for parody tier 0. It is not an inventory system. (If a future round wants seeded mint for tier 0 variety, seeding it is a small, safe change — random.Random(shop_id) + an ordered ORDER BY id sample instead of TABLESAMPLE.)

---

3. The tier ladder, as built [MEASURED for 0–1, DESIGN for 2]

tier	source	deterministic	offline
0 · parody	seeded canvas / E's parody packs	yes	yes
1 · static real	per-shop atlas baked from the POS snapshot (G2a, shipped)	yes — verified	yes — files
2 · live	thriftgod server over the POS (this doc)	no, by design	enriches only

The offline law is structural, not a promise. stockpack.js already returns null when an index or atlas is missing, and every caller falls back to parody canvas. Tier 2 rides the same seam: the server is an enrichment that upgrades an already-playable tier-1 room. There is no boot path, gate, or tag that may touch the network.

---

4. API surface [DESIGN]

Read-only in v5.0; the write verbs are drafted here but gated on §7.

GET  /godverse/v1/shop/<godverse_id>/stock?crate=<id>&since=<iso>
       -> { shop_id, crate, tier, items:[{sku, slot, release_id, artist, title,
                                          price, condition, sleeve_cond, cover, state}],
            gone:[sku], etag, served_at }
GET  /godverse/v1/shop/<godverse_id>/crates      -> crate list + counts (the rotation menu)
POST /godverse/v1/reserve  { sku, session }      -> { ok, holds_until }   [GATED — §7]
POST /godverse/v1/buy      { sku, session, hold } -> { ok, receipt }      [GATED — §7]

Design rules:

• The atlas is never served by the API. Covers stay static files (tier 1). The server sends facts (what's still there, what it costs), never pixels. A tier-2 shop with a dead server is visually identical to tier 1 — that's the fail-soft.
• gone[] is the whole point of tier 2. The client already holds the tier-1 crate; the server says only what changed. A sold record is a sku in gone[] → collapseBuyItem() (already built, R9) zero-areas the sleeve. Sold-means-gone is a diff, not a re-fetch.
• etag/since so a re-enter is a 304, not a payload.
• Shop id is the godverse id (§1a), never a POS internal id. R24 naming, as landed: the town cache carries shop.godverseShopId (A's schema field, camelCase, read by the JS runtime); the atlas index carries shop.godverse_id (snake_case, what E's validate_atlas.py requires). Same id, two artifacts, two house conventions — the API uses godverse_id on the wire to match the Python/JSON side it is served from. Recorded rather than silently reconciled: if the integrators want one spelling, it is a one-line change in each emitter, not a design question.

---

5. Async enrichment + caching (risk #1) [DESIGN]

Law: the dig never blocks on the network. Not "usually" — never. The mechanism:

1. Room builds at tier 1 from static files. Playable. Riffling works. No await.
2. The stock fetch is fired in parallel, never awaited by any build path, with a hard ~400 ms budget and AbortController.
3. If it lands in time: apply gone[] + price deltas before the player reaches the crate.
4. If it lands late: apply on arrival (a record vanishing mid-riffle is correct — that's a real shop). If it never lands: the room stays tier 1, silently. Zero console noise — a dead server is an expected state, not an error.
5. Cache the response per (shop, crate) in memory + sessionStorage, keyed by etag. One fetch per shop per session, not per crate entry.
6. One flight at a time per shop; re-entering a shop reuses the cache. No polling loop.

The v1 machinery makes this cheap: the pack is a shared material + per-item UVs, so applying gone[] is a vertex collapse on an existing merged mesh — no rebuild, no re-upload, no stutter.

---

6. Identity: census ↔ lot ↔ POS (risk #3) [DESIGN, informed by §1]

The R22 contract said "atlas per shop keyed by godverse shop id". §1 shows the id must come from whichever dataset actually has the shop, and mismatches must fail soft, never mis-stock:

• A shop is stocked only by explicit, recorded identity — a godverse_id that resolves to a real POS. There is no fuzzy name matching, ever. A shop we cannot identify with certainty gets tier 0. Mis-stocking is worse than no stock: it puts one shop's records in another's crate, which is a lie the whole epoch exists to avoid.
• Every unmatched census shop is counted, not guessed (the drops law). R23's count: 2,928 census shops, 1 identified real POS.
• The census is not a stock oracle. Being in the census means the shop exists, not that we know what's in it. v5.0-beta's "every hero shop stocked" is therefore bounded by real POS access, not by census coverage — see §9.

---

7. THE WRITE-BACK QUESTION — RULED: A THEN B (John, 2026-07-17, R24 kickoff)

THE RULING

v5.0 ships on Option A (sandbox). An in-game purchase never touches real monsterrobot/Square inventory. Sold-means-gone is per-session, tier-1 semantics. Option B (reservation) is CHARTERED as a v5.x upgrade, behind a hold budget John sets. Option C is not chartered — it happens only as a deliberate business launch, if ever.

Charter law #4 is hereby satisfied: the write-back question has an explicit, John-ratified answer, and until B ships the standing state is read-live, sell-sandboxed.

What this makes law for v5.0 (binding on the server work, when it starts):

• The API's POST /reserve and POST /buy (§4) stay unbuilt and unrouted. Not stubbed behind a flag — absent. A sandbox that can be flipped on by a config typo is not a sandbox.
• The game's buy path terminates in the client's wallet. No code path from a game purchase to inventory.in_stock, sold_date, hold_expires_at, qty, or Square exists. The tier-2 reader connects to the POS read-only — enforce it at the credential, not in a code review: a role with SELECT on inventory/crate/disc_cache and nothing else (this also carries the §9 PII fence in the same grant).
• A gate worth its name here (the vacuous-gate law): assert the write verbs 404, and that the tier-2 role's grants are read-only. A test that "we didn't call buy()" proves nothing.

Option B's charter (v5.x — the preconditions, so it can't slide in quietly):

1. The hold budget — John's number, not yet set. Max concurrent game-held SKUs, and max hold duration. Until both are set, B is not startable. (Open item, not a blocker for v5.0.)
2. The shop always wins. If a held record sells in-store via Square, the game loses the hold, silently and immediately, and the player is told the truth ("someone bought it in the shop") — the one race policy that is never up for negotiation.
3. Staff-visible reason code on every hold (held: GODVERSE), so a human at the counter can see why a record is out of the crate and clear it by hand.
4. Soak first. B rides plumbing that has soaked, not plumbing that tags a round — Fable's framing, and the reason A ships first.

The options as framed for the ruling are preserved below, since the trade-offs are the record of why A-then-B was chosen.

---

The question as put: does an in-game purchase ever touch real thriftgod/recordgod inventory? Live, not hypothetical: monsterrobot is a real trading shop whose POS syncs to Square, with real customers buying these exact records off the real shelf.

Relevant measured facts: the POS already has in_stock, sold_date, hold_expires_at, qty and square_item_id. A reservation primitive therefore already exists — the question is whether the game is allowed to pull it.

Option A — Sandbox (read-live, sell-local)

Game reads real stock; a purchase never leaves the game. Sold-means-gone is per-session.

• For: zero real-world risk; no payment, tax, or fulfilment surface; a bug can't cost real stock; ships fastest.
• Against: the one-of-a-kind thrill is fiction — the real crate never changes, and two players (or the same player, next boot) buy the same record. Tier 2 becomes "live prices" more than "live stock".

Option B — Reservation (a real, expiring hold)

A game purchase places a real hold on the real SKU via the existing hold_expires_at. The record genuinely leaves the real crate for N hours; unclaimed, it returns.

• For: genuinely one-of-a-kind, and reversible — the strongest truth-per-unit-risk; uses a primitive the POS already has.
• Against: a game action removes real sellable stock from real in-store customers. Needs a hold cap/budget, a staff-visible reason code ("held: GODVERSE"), and a race policy against Square in-store sales. Someone must decide what happens when a held record sells in the shop anyway (the game must lose, gracefully).

Option C — Full write-back (game sale = real sale)

A purchase marks the real SKU sold and syncs to Square.

• For: total truth — buy it in the game and it is gone from the real shop, forever.
• Against: irreversible real-world inventory and revenue consequences; the game becomes a sales channel (real payment, tax, postage, fulfilment, refunds, chargebacks); a bug destroys real stock; a game wallet is not money. This is a business decision, not an engineering one.

(Lane G asked nothing and recommended nothing here — the options above are the record as put to John. Ruled A-then-B; the binding terms are at the top of this section.)

---

8. Failure modes [DESIGN]

failure	behaviour	gate class
server unreachable / DNS dead	tier 1, silent, zero console noise	tier-2 smoke
server dies mid-session	room keeps last-good state; no re-fetch storm; no stutter	tier-2 smoke
server slow (> budget)	request aborted; tier 1 stands; late arrival applies or is dropped	tier-2 smoke
5xx / malformed JSON	treated as unreachable — never a partial apply	tier-2 smoke
atlas missing but server up	tier 0 — no stock without covers; never text-only sleeves	tier-1 gate
gone[] names an unknown sku	ignored + counted, never an error	tier-2 smoke
clock skew on holds	server time is authoritative; client never computes expiry	tier-2 smoke

No tier-2 failure may fail a gate or block a tag (charter law #1). Tier 2 gets its own smoke class: reachability, fail-soft, latency. Kill the server mid-session and the game must not stutter — that is v5.0's release gate, and it is a client test, not a server test.

---

9. Fences (non-negotiable, both already load-bearing)

• PII. recordgod holds real customer, customer_session, mailing_list, staff, sales — real private-individual data. The pipeline and the server read only inventory / crate / disc_cache. No exceptions, no joins, no "just for debugging". Charter law #3: no private-individual data, ever.
• Licence. Covers are the shop's own product shots → in-house 🟢, flagged before any public/commercial release. Real titles/artists ship at tier 1 per John's R23 amendment to the no-real-trademarks law, under the same flag. Every atlas carries its provenance.
• Scope reality check for v5.0-beta. "Every hero shop stocked" needs a real POS per shop. We have exactly one (John's own). Stocking a second real shop means a second real shopkeeper's data and consent — a licence and relationship question, not a pipeline question. Beta should be scoped to monsterrobot's 357 crates (24,646 real records — the whole shop, crate rotation per risk #2) rather than to more shops, unless John says otherwise.

---

10. Open items for the reviewers

1. [Fable-m3 / C] Per-shop pack resolution is not wired: stockpack.js caches by type alone (_packs/_resolved), and interior_mode.js:192 resolves getStockPack(shop.type) with base fixed at assets/models/. R23's single shop works via a base override; two stocked shops will collide in that cache. The seam C/F need: key the cache by type + base (or godverse_id), and preload per-shop on shop entry. G re-emits to whatever wording C lands (LANE_C_PUB).
2. [Fable-m3 / E] redhill_real doesn't exist — the only Brisbane cache (westend_real) stops ~2.3 km south of Red Hill. The crate has no street until E's build_towns.py gets a Red Hill entry (~center: (-27.4553, 153.0064), span_km: 2.4) and one Overpass fetch. That's E's file and an outward call — G has not touched either.
3. [John, R24] §7, the write-back question. RULED 2026-07-17: A then B (§7). Carried forward: the hold budget is John's number and is not yet set — Option B is not startable until it is, which is a v5.x item, not a v5.0 blocker.
4. [Both Fables] §9's beta scoping — depth (one real shop, 357 crates) vs breadth (more shops, which needs other people's data).