Preserve source rank recovery categories for WoW actor cooldowns (#3)

Native integration: Codex/healer-man-godot#114.
Coordinator: /root, session 01a11cd3-fa7c-7510-ba8f-bc7a3d0310a6.
Workers: single_pass_source, single_pass_validation, single_pass_renderer; GPT-6 Luna xhigh.

docs/WOW_GCD_CATEGORIES_2026-10-09.md

@@ -0,0 +1,74 @@
+# WoW rank-specific global cooldown categories
+
+Shared source [issue #3](https://git.whoagland.com/phenom/healer-man/issues/3)
+owns this combat correction. Native integration belongs to
+[Codex/healer-man-godot#114](https://git.whoagland.com/Codex/healer-man-godot/issues/114).
+
+## Imported rank identity
+
+`scripts/generate-wow335-abilities.mjs` imports Spell.dbc
+StartRecoveryCategory alongside StartRecoveryTime. The expanded 239-field
+local enUS layout shifts semantic fields 205/206 to raw columns 211/212.
+The extracted DBC SHA-256 is
+`9f0088da35c5ed0b5106cd20e422611489e435b74043e520e02221e0ce1b1af1`.
+The additive import joins all 2,229 selected learned rank IDs with no missing
+rows and preserves every original generated value and byte after removing
+only the inserted `gcdCategoryId` fields. This is an additive metadata import,
+not a regeneration of spell effects, costs, stats or equipment.
+
+`wow335AbilityCatalog.ts` maps the category into every rank and initial ability;
+`abilityCatalog.ts` selects `gcdCategoryId` with the learned rank's spell ID,
+time and effects. Devotion Aura 48941 is category 38/time 1500 at levels
+74–78; 48942 is category 133/time 1500 from level 79 through 80. Categories
+are not derived from name, character level or the first rank of the chain.
+
+## Combat ownership
+
+`wowGlobalCooldown.ts` owns matching-category admission and timer creation.
+Player state, PartyMember and CombatActorState carry optional
+`globalCooldownEndsByCategory` keyed by decimal category string. For WoW,
+`globalCooldownEndsAt` is the category-133 projection. Starting category 38
+or 0 preserves the independent category-133 scalar and timer.
+
+An exact category is checked even when the attempted spell's own duration is
+zero. A zero-duration action creates no timer. Explicit category 0 is a real
+key: a positive-duration fixture starts key `"0"` and other categories remain
+available. None of the current 2,229 learned rows has positive duration in
+category 0, so ordinary learned category-0 actions continue working during
+category 133. Legacy entries lacking a category use 133 when duration is
+positive; a missing-category zero-duration entry retains its bypass.
+
+Player `castAbility` and party readiness/commit call the same helper.
+Cast completion and Sudden Doom's internal free Death Coil keep their existing
+execution exemptions. Actor authority adapters carry category maps in both
+directions; initialization, reset and native player switches preserve actor
+ownership. NPC next-action scheduling remains its existing rotation cadence.
+
+Raw WoW durations below 1000 ms remain unchanged, including five 500 ms
+Shadowfury rows and Backdraft/party haste paths. Positive non-133 WoW timers
+retain their raw duration. Ordinary category-133 timers retain their existing
+haste policy and one-second floor. Runewaker/RoM timing remains scalar-only;
+this change does not merge stat formulas, allocation, gear pools or rigs.
+
+The matching-category behavior follows the pinned primary
+[AzerothCore category manager](https://github.com/azerothcore/azerothcore-wotlk/blob/35aaa5e722093b4f57b59bc234c0311467081b49/src/server/game/Entities/Unit/CharmInfo.cpp#L367-L390)
+and [Spell admission/creation](https://github.com/azerothcore/azerothcore-wotlk/blob/35aaa5e722093b4f57b59bc234c0311467081b49/src/server/game/Spells/Spell.cpp#L8471-L8527).
+This is category policy evidence; complete original-client hit tables,
+spell-attribute haste parity and companion rotation parity remain separate.
+
+## Validation and publication
+
+Focused regressions live in `src/game/wowGlobalCooldown.test.ts`. They include
+exact rank selection and public source character initialization/casting.
+Native evidence covers the public Ready Discipline cast path and separately
+labeled category-38/133/0 UI fixtures. The offline native diagnostic profile
+catalog currently fixes its characters at level 80, so its GPU fixture is not
+a live level-74 profile claim or additional Paladin certification. Balance
+certification remains the existing five Ready WoW specializations.
+
+The published source checkout and installed mirror's combatStore/partyRuntime
+are equal after CRLF normalization. The native byte-guard manifest instead
+patches the exact pre-114 installed mirror and preserves its mixed line endings.
+Native source pins identify installed bytes, not a claim that source Git HEAD
+alone recreates every asset/export in the native installation. See the owning
+issues for final commands, validation counts, evidence and review status.