OpenFUT/openfut-utas-host/ROUTE_AUTHORITY.md

# FIFA17 UTAS Route Authority (economy cutover gate)

Machine-auditable ownership of every FIFA17 UTAS route that touches the economy
cluster. This is the **deployment gate** for the Rust economy cutover (R1/E1):
before Rust economy authority is enabled, every row's `Target` must be reached
and no `Python (proxied)` row may still write Core-owned state.

Cluster state = `coins`, owned inventory (`items`/`purchased`), unopened pack
entitlements (`unopenedPackIds`). `points` has **no** writer (read-only). EASFC
`powFunds` is a separate balance, out of cluster.

Legend: **R** = Rust/Core authoritative, **P** = Python proxied (oracle).
Evidence lines refer to `fifa17-recon/tools/{utas_server.py,fut_store.py}`.


## Accepted URL prefixes (v1 + v2) — S2 fix

The retail FIFA 17 client issues the **Store family** under a `/ut/v2/game/<sku>/`
prefix (live-observed `PUT /ut/v2/game/fifa17/store/transaction/0`), while other
routes use `/ut/game/<sku>/`. `classify_economy` normalizes BOTH prefixes to the
same tail (`ut_tail`), so economy ownership is prefix-agnostic. This closes the
S2 live-staging defect where the v2 Store BUY escaped to Python.

| Route | Accepted method + path shapes (both prefixes) | Economy route |
|---|---|---|
| Credits | `GET (/ut/game\|/ut/v2/game)/<sku>/user/credits` | `Credits` |
| Store catalogue | `GET …/store/purchasegroup[/…]` | `PurchaseGroup` |
| **Store BUY** | `PUT …/store/transaction` **and** `PUT …/store/transaction/<txn-id>` (numeric, e.g. `…/store/transaction/0`) | `StoreBuy` |
| **Pack open** | `POST …/purchased` **and** `POST …/purchased/items` | `PackOpen` |
| **Pack reveal** | `GET …/purchased` **and** `GET …/purchased/items` | `PackReveal` |
| Quick-sell (path) | `DELETE …/item/<digits>` | `QuickSellPath` |
| Quick-sell (body) | `POST (/ut/delete/game\|/ut/v2/delete/game)/<sku>/item` | `QuickSellBody` |
| Move | `PUT …/item` | `MoveItems` |
| Match end | `POST (/ut/delete/game\|/ut/v2/delete/game)/<sku>/match` | `MatchEnd` |
| Market list | `POST …/auctionhouse` \| `…/transfermarket` | `MarketList` |
| Market query | `GET …/tradePile` **and** `…/tradePile/counts` (CASE-INSENSITIVE: `tradepile` too) | `MarketQuery` |
| Market buy | `…/trade/<id>` | `MarketBuy` |
| Market cancel | `DELETE (/ut/delete/game\|/ut/v2/delete/game)/<sku>/trade/<id>` | `MarketCancel` |

`store/transaction` matching is BOUNDED to a single all-digit id segment — it
never absorbs `store/transactions`, `store/transactionfoo`, or
`store/transaction/<id>/extra` (those proxy to Python as non-economy). Audit
basis: Python route table `utas_server.py:1420` matches the store family
"regardless of /ut/game vs /ut/v2/game prefix"; all other economy routes are
`G = /ut/game/[^/]+`-prefixed (v1-only) and the retail client uses v1 for them.

### Round-2 fix (retail `/purchased/items` + `tradePile` case) — candidate supersedes `47ced22`

Live re-stage of `47ced22` showed the CONFIRMED retail Store BUY uses
`POST /ut/game/fifa17/purchased/items` (reveal `GET …/purchased/items`), which the
exact-tail `purchased` match missed → Python (Core coins unchanged = no debit). Fix:
`is_purchased_tail` accepts `purchased` AND `purchased/items` (bounded: rejects
`purchasedfoo`, `purchased/items/extra`); `is_tradepile_tail` matches the `tradepile`
family case-insensitively (`tradePile`, `tradepile`, `…/counts`) since the FUT hub tile
polls lowercase while the screen uses camelCase (oracle routes both via `re.I`). Audit
basis: oracle `utas_server.py:1428` bare `/purchased` regex matches `/purchased/items`;
`:1539-1540` `tradePile`/`tradePile/counts` are `re.I`. The full contract is the
machine-auditable `retail_route_matrix` unit test + the `pure_economy_routes` dispatch
matrix (NEVER-BOTH / no-fallback) + `retail_purchased_items_buy_debits_core_through_dispatch`.

## E1 — CUTOVER READY (barrier `93a46d4`, superproject source-ready; NOT deployed)

The economy authority barrier is committed: `Server::handle_with_ip` dispatches
every economy route to Rust/Core (`try_handle_economy`) BEFORE `classify()`, and
`from_config` (`43917a0`) attaches the economy services in production. Final
per-route authority (all economy routes owner = Rust, Python proxy = NO):

| Route (method) | Owner | coins R/W | inv R/W | ent R/W | pile R/W | listing R/W | reveal | Py proxy | Rust handler / Core primitive |
|---|---|---|---|---|---|---|---|---|---|
| `/user/credits` (GET) | R | R/- | - | R/- | - | - | - | NO | `handle_credits` (`balance`+ent count) |
| `/userMassInfo` (GET) | R (hybrid) | R/- | R/- | R/- | - | - | - | envelope only | `overlay_massinfo_economy`+squad (Py non-economy envelope only) |
| `/store/purchasegroup` (GET) | R | R/- | - | R/- | - | - | - | NO | `handle_purchasegroup` full-gen + `StoreMode` |
| `/store/transaction` (PUT) | R | -/R | -/R | - | -/R | - | R | NO | `handle_store_buy` → `purchase_items` |
| `/purchased` (POST) | R | -/R | -/R | -/R | -/R | - | R | NO | `handle_pack_open` → `redeem_entitlement`/mint |
| `/purchased` (GET) | R | - | R/- | - | R/- | - | R | NO | `shape_purchased_reveal` (pile+inventory) |
| `/item/<id>` (DELETE) | R | -/R | -/R | - | - | - | - | NO | `handle_quick_sell_path` → `sell_item` |
| `/ut/delete/…/item` (POST) | R | -/R | -/R | - | - | - | - | NO | `handle_quick_sell_body` → `sell_item` |
| `/item` (PUT) | R | - | R/- | - | -/R | - | - | NO | `handle_move_items` (PileStore) |
| `/ut/delete/…/match` (POST) | R | -/R | - | - | - | - | - | NO | `handle_match_end` → `grant_reward` |
| `/auctionhouse`,`/transfermarket` | R | R/- | - | - | - | -/R | - | NO | `handle_market_list` (MarketStore) |
| `/tradePile` (GET) | R | R/- | - | - | - | R/- | - | NO | `handle_market_query` |
| `/trade/<id>` (POST/PUT/GET) | R | R/R | -/R | - | - | R/R | - | NO | `handle_market_buy` → `purchase_item` |
| `/ut/delete/…/trade/<id>` (DELETE) | R | - | - | - | - | -/R | - | NO | `handle_market_cancel` |

`/ut/auth`, `/openfut/fifa17/capability`, `/club`, `/squad/*` are NOT economy
routes (classify_economy → None) and are unchanged. `userMassInfo` is the one
intentional hybrid: Python supplies the non-economy envelope, Rust overlays the
squad AND the economy fields — no Python economy value is authoritative/visible.

**Proofs (all green, source-ready):** differential 15 PARITY + 1
DIFFERENT-BY-DESIGN (market second-buy: Rust single-debit ledger vs oracle
stateless re-debit; compat NONE); host concurrency 8 races × 50 iters; failure
injection 10 cases incl. complete-sale-after-commit = SAFE (listing left
`reserved`, not buyable; one debit + one mint; no E3); importer
dry-run/apply/restart/idempotency/conflict; `from_config` E2E + restart;
NEVER-BOTH (economy routes → Rust, Python proxy count 0); no-fallback (dead Core
→ 503, proxy count 0); stale-reader (Core values only, Python 111 never visible).
Python source byte-unchanged; oracle suite 32/32 green.

## Writer routes (mutate cluster state)

| Route | Method | Python handler | Writes | Current | Target | Core primitive |
|---|---|---|---|---|---|---|
| `/ut/game/<sku>/match` | POST | `match_route`→`record_match` (fut_store 554) | coins | P | **R** | `grant_reward` |
| `/store/transaction` | PUT | `store_buy`→`open_pack`→`spend` (utas 3702) | coins, purchased, packsOpened, nextItemId | P | **R** | `purchase_entitlement` (+ `redeem_entitlement`) |
| `/purchased` | POST | `purchased_items`→`open_pack`+`consume_unopened_pack`+`move_items` (utas 3716) | coins, purchased, unopenedPackIds, items, nextItemId | P | **R** | `redeem_entitlement` |
| `/ut/game/<sku>/item/<id>` | DELETE | `quick_sell_url_route`→`quick_sell` (utas 1234) | coins, items, purchased | P | **R** | `sell_item` |
| `/ut/delete/game/<sku>/item` | POST | `quick_sell_route`→`quick_sell` (utas 1273) | coins, items, purchased | P | **R** | `sell_item` |
| `/ut/game/<sku>/item` | PUT | `item_route`→`move_items` (utas 1342) | items, purchased | P | **R** | `redeem_entitlement`/move (inventory-only) |
| `/ut/game/<sku>/trade/<id>` | POST/PUT | `trade_route` buy-now `spend`+`add_items` (utas 3895/3899) | coins, items, nextItemId | P | **R** | `purchase_item` (synthetic-seller mint) |
| `/auctionhouse`,`/transfermarket` | POST | `auctionhouse_route`→`list_for_sale` (utas 3865) | listings, nextListingSeq | P | **R** | listing-state (see note) |
| `/ut/delete/game/<sku>/trade/<id>` | DELETE | `delete_trade_route`→`remove_listing` (utas 3935) | listings | P | **R** | listing-state (see note) |
| `/ut/game/<sku>/squad` | PUT | `squad_route`→`save_squad` (utas 3430) | squads (item refs) | **R** (SquadReplace→Core) | R | Core squad tx (already migrated) |

Note (market listings): `listings`/`nextListingSeq` are the user's own sale pile;
the buyable auction inventory is **synthetic** (PACK_POOL-derived, not persisted).
There is **no** sale-credit, expiry-return, or fee (audit §5). Listing/cancel move
no coins and no ownership, so they are low-risk; a minimal durable listing store
(or keeping the synthetic-only model) is the market slice's only decision.

## Reader routes (emit cluster state; go STALE if Rust writes while these read Python)

| Route | Method | Python handler | Reads | Current | Target |
|---|---|---|---|---|---|
| `/user/credits` | GET | `credits_route` (utas 3765) | coins, unopenedPackIds count | P | **R** (`balance` + entitlement count) |
| `/userMassInfo` | GET | `massinfo` currencies (utas 578) | coins, points, record, items, unopenedPackIds, squad | P (`.squad` overlaid R) | **R** economy fields (coins/packs), squad already R |
| `/store/purchasegroup` | GET | `store_catalog`→`unopened_packs` (utas 3614) | unopenedPackIds | P + R topology overlay | **R** full-gen (catalog + SessionStore mode + Core entitlements) |
| `/tradePile` | GET | `tradepile_route` (utas 3911) | items, listings, coins | P | **R** (reads Core inventory/balance/listings) |
| `/hub`,`/tradePile/counts`,`/watchList` | GET | `hub_data`/`auction_counts`/`watchlist` | items, listings, coins | P | **R** |
| `/club`,`/club/stats`,`/user/list`,`/clubUser` | GET | club readers→`items` | items | **R** (`/club` Core-backed) / P others | **R** |

## Writer → Core primitive map (Phase 2)

| Python writer | Reachable | Core primitive (services::economy) |
|---|---|---|
| `spend` (pack buy leg) | YES | `purchase_entitlement` debit leg |
| `open_pack` | YES | `purchase_entitlement` + `redeem_entitlement` (buy→entitlement→open split) |
| `consume_unopened_pack` | YES | `redeem_entitlement` (consume-once) |
| `move_items` (purchased→club) | YES | inventory add within `redeem_entitlement` / move op |
| `add_items` (market mint) | YES | `purchase_item` (debit + mint) |
| `quick_sell` | YES | `sell_item` (remove + credit) |
| `record_match` (coins) | YES | `grant_reward` (credit) |
| `new_item_id` | YES | adapter numeric-id via `openfut-identity` (Core ids opaque) |
| `list_for_sale` / `remove_listing` | YES | listing-state (market slice) |
| `grant_coins` | **NO** (dead) | — drop |
| `grant_unopened_pack` | **NO** (test-only) | — drop |
| `save_squad` | YES | already Core-authoritative (SquadReplace) |

## Single-writer rule

Coins live **only** in Python `fut_profile.json` today (Core `clubs.coins` is a
separate imported value). Because every coin reader (`credits`, `userMassInfo`,
`tradePile`, market bodies) reads that same JSON, the coins cluster **must flip
readers and writers together** — a partial flip desyncs the client's counter
(audit "STALENESS RISK"). The coherent first cut is therefore the whole coins
bundle: 4 writer routes + `credits`/`userMassInfo`/`purchasegroup` readers, all
on Core, seeded by a one-time profile import into Core.

## Proxied-route safety (R1 requirement: no unsafe YES)

After cutover, every remaining `Python (proxied)` route MUST have
`economy state touched = NONE`. Routes with `economy state touched != NONE` are
part of the migration cluster and MUST be Rust before R1. This table is the
audit source; the host `classify()` is the enforcement point (NEVER BOTH).

## Cutover progress (2026-08-13)

Landed (Core authority + transport + several handlers; classifier NOT yet flipped):

- **Core economy HTTP API** (`d32dc6e`, `bcc4f51`): generic `/economy/{balance,
  entitlements,purchase-entitlement,redeem-entitlement,sell-item,grant-reward,
  purchase-item,purchase-items}`, server-side club resolution, atomic. Import now
  seeds `unopenedPackIds`→entitlements. Core 178 tests green.
- **Host `CoreEconomy` client** (`d240a61`): typed reqwest, **fail-closed, no
  Python fallback** by contract.
- **Reader handlers**: `/user/credits` (`handle_credits`), `/store/purchasegroup`
  full-gen (`handle_purchasegroup`, no Python body dependency), `userMassInfo`
  economy overlay (`overlay_massinfo_economy`). Invariant test: all three read one
  Core state.
- **Writer handler**: `/match` reward (`handle_match_end` → Core `grant_reward`,
  oracle `destroy_match_body` shape).
- **Adapter policy mappers** (`181bd94`): match reward, pack price.
- All Core-backed, fail-closed (503, never Python), `FakeEconomy`-tested.
- **Store/item writers** (`4d2b8b9`, `economy_store.rs`, unrouted): `handle_store_buy`
  (`purchase_items` debit+mint N → `createPackResponse`; 461 insufficient; 200 {}
  cancel/unknown/owned_only), `handle_pack_open` (owned_only `redeem_entitlement`
  consume-once; normal debit+mint), `handle_quick_sell{_path,_body}` (reverse-resolve
  wire→Core id via `SquadWireResolver` → `sell_item`). Item wire shaping via
  `fut::item::shape_item`; numeric ids via `openfut-identity`.
- **Pack-content generator** (`fut/pack_content.rs`): pure seeded
  `generate_pack_contents`, gold-tier + special_chance PLACEHOLDER policy, fail-closed.
- **Market** (`market_store.rs`/`pile_store.rs`/`market.rs`, unrouted): durable sqlx
  SQLite listing store (WAL+`BEGIN IMMEDIATE`, states active/reserved/sold/cancelled,
  CAS reserve/complete/rollback, typed errors), durable pile metadata,
  `handle_market_{list,query,cancel,buy}` (synthetic-seller buy-now = reserve→
  `purchase_item`→complete_sale, race-safe two-buyer) + `handle_move_items`.
- Adapter +7 / host +43 tests incl. `two_reservers_exactly_one_wins`,
  `two_buyers_exactly_one_sale_one_debit`, `state_survives_reopen`,
  `move_persists_across_reopen`. clippy -D warnings + rustfmt clean.

- **Async runtime bridge + dispatch** (`580d80a`, `async_bridge.rs`, unrouted):
  `AsyncBridge` (one process-lifetime multi-thread Tokio runtime, nested-safe
  `block_on`) + `classify_economy` + `EconomyServices` + `Server::try_handle_economy`
  wire ALL the handlers into real dispatch. `classify()` is untouched (handler
  wiring ≠ authority cutover). Load-bearing fix: the async market handlers call the
  BLOCKING reqwest Core client, which panics if run while a runtime is entered
  (`reqwest::blocking::wait::enter`) — the `FakeEconomy` unit tests missed this;
  `market::off_runtime` hops each Core call to a plain OS thread.
- **Real dispatch E2E** (`economy_full_sequence_through_dispatch`): drives the whole
  cluster through `try_handle_economy` + the bridge against a live in-process Core
  (fifa17 dev content, 100k coins) over the real blocking client, no fakes — Store
  BUY (pool+shape+debit+mint 5), credits, quick-sell, match WIN, market
  list→query→buy→query(sold)→second-buy-fails, cancel, move, + durable store reopen.

**Not flipped:** `classify()` still routes every economy route to Python. Per the
single-writer rule the flip is one coherent barrier once ALL writers+readers are
proven — a partial flip would desync coins.

**Remaining before barrier:** (1) **Python-oracle differential** runner (subprocess,
isolated fixture, all ~13 ops, PARITY / DIFFERENT-BY-DESIGN); (2) **host-level
concurrency matrix** through real dispatch (two-BUY / dup-open / dup-sell /
two-buyers / reward+BUY / move+sell / id-collision, 50–100 iterations); (3)
**failure-injection** seams (Core failure at each step → no debit/grant/double);
(4) **importer** disposable-DB apply / idempotency / restart; (5) `from_config`
attachment of `EconomyServices` + `classify()` barrier flip; then no-Python-fallback
/ writer-unreachable / stale-reader / NEVER-BOTH proofs. Retire in-memory
`ProfileEconomy` from any prod path.

- **Market resourceId→Core card_id mapping** (`fe72f0d`): listings carry BOTH
  `card_id` (authoritative Core content, minted on buy) and `wire_resource_id`
  (FIFA wire, echoed in the auction record); `handle_market_list` reverse-maps via
  the catalog `by_resource` index and fails closed on an unmappable resource. The
  E2E now survives a FULL Core+store restart (synthetic mint is real content).
- **GET /purchased reveal** (`747cc23`): the reveal is the durable FIFA "purchased"
  pile (PileStore `list_by_pile`), shaped by the same `shape_club_response` /club
  uses; idempotent, cleared per-item on move-to-club. E2E opens pack 70 and asserts
  the reveal + idempotent repeat.