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

docs/GAME_GEAR_NAMESPACES.md

@@ -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.