Update class mechanics, stat rulesets, and CoA reference catalogs

docs/COA_REFERENCE_PIPELINE.md

@@ -0,0 +1,164 @@
+# CoA offline reference pipeline
+
+The reference pipeline prepares source evidence for implementing all 21 Conquest
+of Azeroth classes. It reads existing client files first, generates a searchable
+dataset, and compares source versions. An explicit offline promotion updates the
+active CoA catalogs. CoA remains Needs Testing; source coverage does not certify
+class mechanics or balance.
+
+## Sources and version boundaries
+
+The default source pair is `H:/resources/client` and `H:/LadiksMPQEditor` when both
+exist. Otherwise the pipeline uses the project's sibling `resources/client` and
+`LadiksMPQEditor` directories together. In this workspace those are under
+`F:/Projects`. To choose another installation, supply both roots explicitly:
+
+```powershell
+npm run coa:reference:inventory -- --client-root H:/resources/client --extracted-root H:/LadiksMPQEditor
+npm run coa:reference:build -- --client-root H:/resources/client --extracted-root H:/LadiksMPQEditor
+```
+
+The frozen July trees come from
+`data/coa-reference/baselines/coa-july-2026-07-25.json.gz`. Before the first
+promotion, the original active catalog is preserved losslessly in that file.
+Historical reference builds keep using it after active catalog updates. Spell evidence
+comes from the extracted base-client tables under `client-current`: global
+`patch-T` Spell, `patch-M` class and skill metadata, and `patch-S` supporting
+tables. Client `Data/Content` contributes advancement and rank evidence. Relevant
+sources receive hashes and version/source labels. Original files stay intact.
+
+July class-spell references also seed identities, including starter spells that
+are absent from talent trees and progression chains. Their old DBC values are
+not imported. Ownership follows global trigger/effect-168 links so the selective
+spell fetch and promotion cover linked payloads in the same CoA scope.
+
+The previous importer preferred the Area 52 `patch-D` overlay. The extraction's README
+calls those effective CoA sources, while the external datamine identifies them as
+Free-Pick's overlay and uses the base-client chain for CoA. The new reference
+retains this disagreement as audit evidence. The combined live importer now
+selects global Spell/SkillLineAbility tables for CoA and preserves the existing
+Area 52 preference for classic classes. Shared spell IDs have separate CoA
+wrappers; classic spell resolution and its triggered fallback remain isolated.
+
+The optional external source is `srhinos/coa-datamine` at commit
+`5078f9ac22541c45c17a866c23aac6c12073de23`. Its published talent capture is dated
+August 12, 2026. It is a distinct source version applied only by the explicit
+promotion command. A surviving API or capture labeled `live` describes source
+availability/content at capture time, not the current availability of a realm.
+
+The explicit supplement fetch downloads the pinned talent capture, all 21 derived
+talent-tree records, and their identity/provenance metadata. It does not download
+the full client extraction or game assets. Git blob hashes and the
+capture's published SHA-256 verify the files. Valid cached files are reused, and
+interrupted downloads resume at file boundaries. No Exiles crawling is performed.
+
+## Offline active-catalog promotion
+
+```powershell
+npm run coa:reference:fetch
+npm run coa:reference:fetch:spells
+npm run coa:reference:promote
+npm run coa:catalogs:refresh
+```
+
+The spell fetch is an explicit, selective download of pinned global BASE raw
+shards needed for spell IDs absent from the local global table. It includes
+linked payloads and verifies the stored shard hashes. It never selects the
+archive's Area 52 table. Unresolved old progression ranks retain their identities
+and are reported as gaps.
+
+Promotion reads only verified caches and local files. It resolves React Flight
+text references in the captured builder before normalizing nodes, filters empty
+metadata tabs from playable trees, and checks preservation before atomically
+replacing `src/game/coaLiveData.generated.json`. The machine-readable result is
+`data/coa-reference/promotion-report.json`. A failed check retains the active
+catalog. Repeating promotion with the same inputs produces identical bytes.
+
+Existing `coa-entry-*`, `coa-tree-*`, tree IDs, and progression-chain IDs survive.
+Saved talent ranks still follow the normal clamping rules when the captured
+maximum rank decreases. An existing node ID can carry a revised effect: August
+exchanges the spell payloads of Pyromancer's Agonizing Burns/Timed Attacks and
+Cultist's Dark Infusion/Darkward. Saves have no capture-version field, so numeric
+ID preservation does not preserve the old effect. Review affected builds after
+updating. Existing classic spell records, chains, and generated abilities are
+preserved and checked separately.
+
+The refresh command regenerates CoA runtime data and its class shards, resolves
+triggered spells from global data, and exports missing icons. It preserves the
+existing non-CoA talent records and UI shards.
+
+## Build, search, and audit
+
+```powershell
+npm run coa:reference:inventory
+npm run coa:reference:fetch
+npm run coa:reference:build
+npm run coa:reference:audit
+npm run coa:reference:lookup -- --class barbarian --tree Brutality --limit 5
+npm run coa:reference:lookup -- --class barbarian --ability "Ancestral Strike" --limit 5
+npm run coa:reference:lookup -- --spell 800380 --limit 5
+```
+
+Fetching is optional and explicit. Build, audit, and lookup work offline. A build
+without the archive produces a local-only reference and identifies the missing
+comparison. Run fetch and then build to add it. `--refresh` is supported only by
+fetch, which revalidates the same pinned revision rather than choosing a new one.
+
+`--output-root PATH` chooses a separate reference output directory; `--cache-root
+PATH` chooses the supplemental cache. Defaults are `data/coa-reference` and its
+`cache` subdirectory. Lookup accepts numeric class IDs or HealerMan class names,
+tree names/IDs, spell IDs, and case-insensitive ability-name fragments. Each result
+collection is limited to 20 by default; use `--limit` between 1 and 1000.
+Class and tree searches include linked spell ranks and triggered spell dependencies;
+those dependencies are not presented as learned abilities.
+
+Build prints the path to the readable audit. The corresponding `audit.json`
+contains detailed machine-readable findings. `reference.json` preserves nodes,
+spell data, rank relationships, class catalogs, source evidence, and unresolved
+relationships. Class aliases are tied to numeric class IDs, so legacy names such
+as DemonHunter, Monk, and SonOfArugal do not create extra playable classes.
+
+The report inventories each class, compares July and August nodes/trees, compares
+local base spell evidence with the previous imported values, and identifies
+runtime-catalog mappings. A mapping is not proof that a talent mechanic works.
+The backlog prioritizes source conflicts and identity gaps before bespoke combat
+behavior, player/companion integration, UI verification, and targeted balance work.
+
+## Integrity and limitations
+
+Snapshots are content-addressed and immutable. Build writes and verifies all
+files before replacing `current.json`. Failed builds leave the last valid
+snapshot selected. Rebuilding unchanged sources produces the same snapshot ID.
+Audit and lookup verify the selected snapshot's manifest before reading it.
+
+If a source file is malformed or a downloaded cache file fails its checksum, the
+command stops with the affected source identified. Restore the original source
+or rerun the explicit fetch before rebuilding. Missing spell/dependency evidence
+is reported as a coverage gap rather than filled with speculative values.
+
+An existing immutable snapshot with damaged files is rejected. To regenerate it
+without changing the damaged evidence, build with a fresh `--output-root` and
+point `--cache-root` at the existing verified cache.
+
+Client descriptions, effect fields, and identity joins have different certainty.
+The dataset preserves that evidence; it does not invent server-side base stats,
+proc timing/rates, missing coefficients, or acquisition rules. Name matches alone
+do not establish an exact rank identity. CAD catalog presence alone does not prove
+that an ability was trainable in the captured game version.
+
+The promoted trees and spell evidence provide the foundation for class mechanic
+implementation. Bespoke procs, resource behavior, acquisition rules, and balance
+still require targeted class work before promotion from Needs Testing.
+
+## Validation
+
+```powershell
+npm run coa:reference:test
+npx vitest run src/game/coaLiveCatalog.test.ts src/game/coaAbilityCatalog.test.ts src/game/coaAbilityCatalogLoader.test.ts src/game/coaSourceScope.test.ts src/game/coaPromotionPreservation.test.ts src/game/talentCatalog.test.ts
+npm run release:check
+```
+
+Focused pipeline tests cover malformed inputs, source pairing/selection, missing
+relationships, independent version comparison, cache integrity/resume, immutable
+snapshot publication, and offline lookup. No full test suite or all-class balance
+sweep is required for this development-reference change.