PROCITY/docs/G3_ECONOMY_DESIGN.md

# G3 — THE ECONOMY BACKEND (design doc, DRAFT for ratification)

*Lane G (ultra), R23. Drafted per the v5 charter ([V5_REAL_SHOP.md](V5_REAL_SHOP.md)) ledger #2.
Ratification: both Fables + John, at R24 kickoff. **Nothing server-side ships before that.** This
round is paper — plus the tier-1 artifact that made the paper honest (G2a, merged this round).*

Status of each section: **[MEASURED]** = verified against the real databases this round.
**[DESIGN]** = proposed, not built. **[JOHN]** = a decision reserved to John by 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.

---

## 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 [JOHN — charter law #4]

**Does an in-game purchase ever touch real thriftgod/recordgod inventory?**

This is now a live question, not a hypothetical: `monsterrobot` is a **real trading shop** whose
POS syncs to **Square**, with real customers buying these exact records off the real shelf. Stated
per charter law #4 with trade-offs and **no default**.

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 asks nothing and recommends nothing here.** Until ratified: **tier 2 is read-live,
sell-sandboxed** (the charter's standing state, Option A by default *only* because law #4 says so).

---

## 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.
4. **[Both Fables]** §9's beta scoping — depth (one real shop, 357 crates) vs breadth (more
   shops, which needs other people's data).