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