Guard source gear namespaces and retain recoverable legacy records (#9)

2026-10-10 11:36:10 -04:00
1 parent ab37006932
commit e567910c04
@@ -0,0 +1,100 @@
+# Gear namespaces and recoverable legacy records
+
+The source runtime distinguishes an item's game namespace from the dungeon that
+produced its source row. `InventoryItem.contentCategory` is `wow`, `rom`, or
+`coa`; it stays optional in the TypeScript contract for legacy callers, while
+new WoW and Runewaker factories explicitly write their own source category.
+Saved character/class identity chooses the expected owner category. A dungeon
+selection cannot change it or relabel another game's gear.
+
+## Item and equipment boundaries
+
+`lootTypes.ts` exposes an explicit category match and a usability check.
+RoM usability additionally requires a nonempty payload accepted by the existing
+`normalizeRomNativeGearStats` normalizer. This is structural validation, not
+proof of an authenticated item association or authoritative stat ranges.
+Unidentified and foreign records cannot be equipped or contribute active gear.
+Contradictory owner-category hints cannot override the source class category.
+
+Owner-aware loot generation and combat grants filter foreign/unusable records.
+An unavailable same-game item pool yields no borrowed gear. Boss-card identity
+continues to use the boss/dungeon source. Native Godot still remaps both loot
+catalogs to its cards-only adapter; this change does not enable ordinary loot.
+The generic Runewaker item catalog has source-tagged records without native
+gear payloads and is not promoted into a playable equipment progression pool.
+
+Synthetic equipment scoring and internal training gear remain simulation
+scaffolding. They are not imported live loot. A private training-item identity
+can preserve existing simulator fallback calculations without authorizing a
+persisted or copied record as native RoM gear.
+
+## Profile migration and recovery
+
+`accountRepository.ts` reads local database versions 1–8 at the existing
+`healer-man.profile-database.v1` key and writes schema 8. A missing item category
+may migrate to `wow` only for an explicit WoW owner; the existing normalized
+numeric item fields and equipment references retain their prior values.
+Missing categories on RoM/CoA records are not guessed from names, IDs or dungeons.
+
+Normalized active inventories and assignments contain usable same-game items.
+Rejected legacy records remain in character-local `gearRecovery.items` with
+original item data and a reason (`missing-category`, `foreign-category`, or
+`invalid-native-payload`). `gearRecovery.equipment` retains former owner/slot/
+instance references. Repeated load/cloud normalization merges recovery without
+multiplying it, and ordinary gear updates preserve the existing recovery.
+This schema retains data for a later explicit recovery operation; it does not
+provide a recovery UI or invent a replacement item.
+
+Inventory/equipment mutations reject foreign or unusable incoming gear before
+writing. Rejected mutations leave stored bytes unchanged. Other profiles and
+owners retain separate inventories and recovery. Cloud serialization carries
+full profile rows, and hydration queues a save when namespace/recovery migration
+changes the roster; existing boss-card checkpoint and session-generation behavior
+remain separate.
+
+## Native integration and remaining scope
+
+Shared source issue [#9](https://git.whoagland.com/phenom/healer-man/issues/9)
+owns the source guards and profile schema. Native checkpoint
+[#292](https://git.whoagland.com/Codex/healer-man-godot/issues/292) owns reviewed
+source pins, bridge regressions and installation. Parent native
+[#124](https://git.whoagland.com/Codex/healer-man-godot/issues/124) remains open:
+native offline profiles currently store identity/appearance and do not persist
+runtime item inventory/loadout or expose recovery. RoM entry retains empty gear.
+Source-backed RoM progression and equipment presentation are not established by
+the source association catalog. CoA is Ascension Conquest of Azeroth, distinct
+from supplementary Chronicles of Arcadia references; no native CoA mode is added.
+
+RoM stat formulas, weights and allocations remain under the separate native
+[#123](https://git.whoagland.com/Codex/healer-man-godot/issues/123) claim. The
+existing possibility of non-finite native gear aggregates is tracked separately
+in shared [#10](https://git.whoagland.com/phenom/healer-man/issues/10); namespace
+metadata does not establish numeric bounds or source authenticity.
+
+## Verification
+
+Validation results and exact inputs are recorded with the owning issues. The
+focused item/equipment suites pass 39 tests; account/migration/cloud suites pass
+35; combat/stat regressions pass 120; selected training/slot checks pass three;
+and the avatar suite passes 56 with verified copied inputs and explicit
+AppleDouble exclusions. The native source-boundary suite passes seven tests,
+and the candidate native bundle builds from the composed, pinned source.
+
+The required browser production build currently stops at the missing
+`public/assets/game/manastorm` asset-audit input in the isolated review checkout.
+This is retained as an unmet browser build/visual verification limit; a passing
+native bundle does not certify the browser release. Source TypeScript and
+combined native/card/simulator checks are recorded separately. The repository
+release hygiene check passes. No new GPU capture, live browser roster/dungeon
+check, manual playthrough or listening is claimed.
+
+The full source app TypeScript check passes with the original `src` scope and
+task-local exclusions for AppleDouble companion files. All 21 selected native
+cases pass across the unchanged 20-case run and the exact missing-catalog case
+rerun. A serial public-runtime comparison matches all five Ready WoW profiles
+at level 80 with identical clock and random inputs. Those profiles have empty
+gear; equipped-item and migration behavior is covered by the focused source
+suites. Earlier varying mana results came from run-ID-seeded party identities,
+not a gear formula change; the superseded controls remain in the archive.
+
+See `gear-namespace-validation.json` for exact source and evidence identities.
@@ -0,0 +1,85 @@
+{
+  "schemaVersion": 1,
+  "date": "2026-10-10",
+  "coordinator": "/root",
+  "session": "01a11cd3-fa7c-7510-ba8f-bc7a3d0310a6",
+  "issues": {
+    "native": 292,
+    "nativeParent": 124,
+    "shared": 9
+  },
+  "status": "tested-native-checkpoint-browser-verification-incomplete",
+  "sourceFiles": {
+    "src/game/lootTypes.ts": "36b11682b214bc479267075c720cb4afcdbb5c8ba7ac18c199d706c3f1313baa",
+    "src/game/equipment.ts": "76a9757a9727cb7fa543695d8f77426ab1328688a65f4f2212b6c144afb16f92",
+    "src/game/lootCatalog.ts": "7027dadc2f7f90f6e7b65603b38873b3ad32e09fb4807ceea541caa39278a5f5",
+    "src/game/runewakerLootCatalog.ts": "113008a954c27611e4cc28576290fc721f254dee41427285a355f8e30ba70b9a",
+    "src/game/lootPolicy.ts": "bded57df5de902ba01c365ac021709f572aeb692a7cc8a6c0edfd6494d8cad9d",
+    "src/game/combatStore.ts": "f49b7af337af0fb6e69f6df68ec5ec9ab558cc88fe819ae30c4cf9ad823cd4e5",
+    "src/game/heirloomEquipment.ts": "057da9166c2a29086fc8ef59afc81fb985ee52926b6cf2f91212809c987d0ff8",
+    "src/app/accountRepository.ts": "32f6f63537db2312e553dee4c00cbb24ec04b1b0dc5d3079227a8e30d932f8e3",
+    "src/app/types.ts": "41bb6aac2fd03b7c8c4c4c8e6b475bec4df5d3422627a61489077feada34b628",
+    "src/app/onlineAccountClient.ts": "04eac8950a503ffccebf29f73f981c1d01a9e558e4712200aaf4ff534279acfe"
+  },
+  "composedNativeSourceFiles": {
+    "src/game/lootTypes.ts": "36b11682b214bc479267075c720cb4afcdbb5c8ba7ac18c199d706c3f1313baa",
+    "src/game/equipment.ts": "76a9757a9727cb7fa543695d8f77426ab1328688a65f4f2212b6c144afb16f92",
+    "src/game/lootCatalog.ts": "7027dadc2f7f90f6e7b65603b38873b3ad32e09fb4807ceea541caa39278a5f5",
+    "src/game/runewakerLootCatalog.ts": "113008a954c27611e4cc28576290fc721f254dee41427285a355f8e30ba70b9a",
+    "src/game/lootPolicy.ts": "bded57df5de902ba01c365ac021709f572aeb692a7cc8a6c0edfd6494d8cad9d",
+    "src/game/combatStore.ts": "5afefb58b9a02b564cf07140c19388163a8423d22695f3619d196a9d603eeb7d",
+    "src/game/heirloomEquipment.ts": "057da9166c2a29086fc8ef59afc81fb985ee52926b6cf2f91212809c987d0ff8",
+    "src/app/accountRepository.ts": "32f6f63537db2312e553dee4c00cbb24ec04b1b0dc5d3079227a8e30d932f8e3",
+    "src/app/types.ts": "41bb6aac2fd03b7c8c4c4c8e6b475bec4df5d3422627a61489077feada34b628",
+    "src/app/onlineAccountClient.ts": "04eac8950a503ffccebf29f73f981c1d01a9e558e4712200aaf4ff534279acfe"
+  },
+  "nativeEngineSha256": "6f9a06c8fb46dbc25b5ff7aa1fee77fcc950a8481e2beb8eb9ed69e33d51e15d",
+  "checks": {
+    "sourceFocusedUniqueTests": 253,
+    "sourceGroups": {
+      "itemEquipment": 39,
+      "profileCloud": 35,
+      "combatStats": 120,
+      "targetedTraining": 3,
+      "avatar": 56
+    },
+    "sourceAppTypecheck": "pass: full original src scope; task-local AppleDouble exclusions only",
+    "sourceReleaseHygiene": "pass",
+    "sourceBrowserBuild": "blocked: missing public/assets/game/manastorm in isolated review checkout",
+    "nativeBundleBuild": "pass",
+    "nativeFocusedCases": 21,
+    "nativeCoverageMethod": "20 unchanged cases pass in attempt-03; the one missing-catalog case passes in the exact-case rerun after copying and pinning the installed boss-card catalog",
+    "readyWowParity": "5/5 level-80 public Ready profiles match with fixed clock/RNG and one fresh process per profile; empty gear only",
+    "liveBrowserRosterAndDungeon": "not performed",
+    "newGodotGpuCapture": "not performed"
+  },
+  "artifacts": {
+    "diagnostics/source-worker/attempt-08/source-worker-receipt.json": "8bcae5d6e47e7e3547ac72d5f3d650fa2f7280993f96a77a3a597fd32e696a48",
+    "diagnostics/persistence-worker/final-receipt-attempt-04.json": "241b8423795b3596b3f77fcc93c0d50bf093f0dcfa6043ec9974c1c8050d1b2a",
+    "diagnostics/required-source-checks/combat-regressions-attempt-01/result.json": "8def574f70b9b19ff57f4413eb4382ecd1e29df126d1036173dd092974021e2d",
+    "diagnostics/required-source-checks/avatar-attempt-03/result.json": "74b511dc10bc233f4aaf49c3bf5a5eb6a626e5639b85332b1444a8d50ec08157",
+    "diagnostics/required-source-checks/typecheck-attempt-04/result.json": "cb2f6f49e3f8f2f3c3f44ce02e0a0f644bcb9d69dfe656ba04b78cfb2af517ca",
+    "diagnostics/required-source-checks/release-attempt-01/result.json": "1c0cd604233dfc3ed01ddca47b34770392e917cd5a589efee15a46d1ceb4c230",
+    "diagnostics/required-source-checks/build-attempt-02/result.json": "d068f38485c7a38af27586d1bbd1ad96db9630bf976092da0572fe0c3a7d5255",
+    "diagnostics/native-build/baseline-attempt-02/result.json": "92bf94d5b26fa99c502575d2fb9bd624518f9e5e21b362b697324efd6a6e6d63",
+    "diagnostics/native-build/candidate-attempt-01/result.json": "05bf46066a9429edb2405d4a60ca7937446f1cb978e71e504a1bf0a051b3dbfb",
+    "diagnostics/native-regressions/attempt-03/result.json": "7e31c04b48f9b01e1419c718023ad929a65cc0efdc3c4759e00a3b72e5d6775e",
+    "diagnostics/native-regressions/cards-catalog-rerun-attempt-01/result.json": "23b8d1b0216de53c462ca25ada0443aa9bdd62336dd554b10bc5f0b9dfa19fcf",
+    "diagnostics/persistence-worker/wow-preservation/attempt-10/acceptance-receipt.json": "8533744d44af288149572f7147c69961b50315101e3c7f86e90ee4d0bafc99ea",
+    "diagnostics/native-candidate-integration/attempt-02/result.json": "44d4672f6f1c174563e2524fffe38ab18f1d96b74486b7a0c198bad764990fbe",
+    "diagnostics/native-candidate-integration/attempt-02/hunk-preservation.json": "b2f6c6e236dc6484fd14ee9bada39fd60933b33320b927e721370feff8445e44",
+    "diagnostics/required-source-checks/release-attempt-02/result.json": "daf8d3a2bc4dd0d103127687d6fd44ba5ee30f7e2ff51f518fb88fe80004caa6"
+  },
+  "preservedScopes": [
+    "WoW rigs/animations/models/stats and installed short-GCD work",
+    "#123 RoM formulas/weights/allocation",
+    "native cards-only loot and simulator reward policy",
+    "character category independent from dungeon category"
+  ],
+  "remaining": [
+    "Full browser build and live roster/in-dungeon screenshots",
+    "#124 native offline item/loadout persistence and recovery UI",
+    "#124 authenticated RoM item progression and equipment presentation",
+    "Shared #10 non-finite aggregate follow-up"
+  ]
+}