feat(utas-host): real Fifa17IdentityResolver (catalog + store + policy), drop placeholders

openfut-utas-host/README.md

@@ -34,28 +34,37 @@ the host holds the [`CoreAccess`] boundary (`GET {core_url}/collection?…` toda
 |---|---|---|---|
 | `OPENFUT_UTAS_HOST_ADDR` | yes | — | where this host listens (client-visible UTAS addr) |
 | `OPENFUT_UTAS_PYTHON_URL` | yes | — | Python UTAS oracle base URL for fallback (must differ from this host) |
+| `OPENFUT_FIFA17_CATALOG` | yes | — | FIFA 17 card-definition identity catalog (`Fifa17CardCatalog` JSON: card id → asset id) |
+| `OPENFUT_IDENTITY_STORE` | yes | — | persistent external-identity store file (owned instance → stable wire id) |
 | `OPENFUT_CORE_URL` | no | `http://127.0.0.1:8080` | OpenFUT Core base |
 | `OPENFUT_FIFA17_TABLES_DIR` | no | `fifa17-recon/data/tables` | `leagues/nations/teams.json` for id⇄name |
-| `OPENFUT_FIFA17_ASSET_MAP` | no | — | JSON `{ "<core_card_id>": <fifa_asset_id> }` (see the blocker) |
 
-## KNOWN BLOCKER — retail rendering of Core inventory
+Startup **fails clearly** if the catalog or identity store cannot be loaded —
+there is no placeholder fallback (exactly one production identity path).
+
+## Identity model (resolved)
 
 FIFA renders an owned card by resolving `resourceId & 0xffffff` against the
 client's **own local players table**; an invented id renders a **blank generic
-card** (proven live — `fut_cards.py:11-21`). OpenFUT Core's catalogue is synthetic
-string-id cards (`card_pl_001`) with **no FIFA asset id**, and no committed
-card→asset mapping exists. So:
+card** (proven live — `fut_cards.py:11-21`). Two distinct identities, never
+conflated, are resolved by [`Fifa17IdentityResolver`] (the single production path):
 
-- Without `OPENFUT_FIFA17_ASSET_MAP`, `/club` returns `{"itemData":[]}` — honest,
-  never faked. The shaper drops any item lacking a **real** asset id.
-- Making Core inventory actually render in retail requires a Core-card→FIFA-asset
-  identity decision (seed Core from FIFA assets, or a real mapping table). This is
-  the "who owns FUT state" question and is the **prerequisite** for a rendering
-  retail `/club`. Filtering, pagination, entity mapping, transport and fallback are
-  all done and tested independently of it.
+- **Definition identity** (`resourceId`/`assetId`) — the card's real FIFA asset
+  id, from the versioned `OPENFUT_FIFA17_CATALOG`. An unmapped definition is
+  **dropped and counted**, never faked.
+- **Instance identity** (`id`) — a stable, persistent, reversible wire integer
+  from the generic `openfut-identity` store under the FIFA 17 wire-id policy
+  (monotonic from `100_000_001`). The same owned instance keeps its id across
+  restart and reverses exactly; two copies of one definition share a
+  `resourceId` but get distinct `id`s. The namespace is globally monotonic
+  within `(fifa17, owned-item)` — no per-account column is needed because Core
+  owned-instance ids are globally-unique UUIDs.
 
-`rare=SP` ("Special") stays UNSUPPORTED (semantics unproven; parsed, reported, never
-guessed).
+**Remaining prerequisite for a *rendering* retail `/club`:** Core inventory must
+reference cards that exist in the catalog. The catalog + store + resolver are
+built and tested; wiring a controlled real FIFA 17 dev-content inventory (the
+curated per-game dev pack) is the next slice. `rare=SP` ("Special") stays
+UNSUPPORTED (semantics unproven; parsed, reported, never guessed).
 
 ## Retail A/B runbook (first `/club` gate)
 
@@ -70,7 +79,7 @@ Preconditions (mirror the proven blaze/roster switch discipline):
 Bring-up:
 1. Move Python UTAS to an alternate port (`FUT_PORT=8199` in the container/`openfut-fut.sh`); it keeps serving there.
 2. Start this host on the client-visible UTAS addr:
-   `OPENFUT_UTAS_HOST_ADDR=<lan>:8099 OPENFUT_UTAS_PYTHON_URL=http://127.0.0.1:8199 OPENFUT_CORE_URL=http://127.0.0.1:8080 OPENFUT_FIFA17_ASSET_MAP=<map.json> openfut-utas-host`
+   `OPENFUT_UTAS_HOST_ADDR=<lan>:8099 OPENFUT_UTAS_PYTHON_URL=http://127.0.0.1:8199 OPENFUT_CORE_URL=http://127.0.0.1:8080 OPENFUT_FIFA17_CATALOG=<catalog.json> OPENFUT_IDENTITY_STORE=<store.json> openfut-utas-host`
 3. Launch FIFA → FUT → **My Squad** player picker and exercise: no-filter, position, nation, league, league+team, Gold+position, then scroll beyond page one.
 
 Evidence to capture (all six):