8.9 KiB
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:
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
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
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
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.