fix(golemancy): reconcile spec vs code discrepancies (issue #326)

- D-SLOT-01: Verified slot cap of 7 matches spec §2.2 (no change needed)
- D-COMB-03: Implement AoE damage distribution for Sand/Shadowglass frames
- D-COMB-01: Reconcile armor pierce formula to spire-combat spec §9.4 (dmg × (1 + armorPierce))
- D-CIRC-01: Fix Simple Logic Circuit summon cost from raw to earth mana
- D-ENCHANT-03: Add dual_attunement unlockRequirement to all golem enchantments
- D-CORE-01/02: Add Guardian Core runtime override mechanism for guardian-specific mana

Also increased test timeouts for module import tests that timeout in full suite runs.

src/lib/game/stores/golem-combat-actions.test.ts

@@ -94,6 +94,7 @@ function runGolemAttacks(
     () => ({ floorHP: 50, floorMaxHP: 100, roomCleared: false }),
     enemyElement,
     () => enemy,
+    () => [enemy],
     () => {},
   );
   return { result, capturedDamage };
@@ -133,6 +134,7 @@ describe('processGolemAttacks - spell damage and mana cost (fixes #1, #2)', () =
       () => ({ floorHP: 50, floorMaxHP: 100, roomCleared: false }),
       'fire',
       () => enemy,
+      () => [enemy],
       () => {},
     );
 
@@ -156,6 +158,7 @@ describe('processGolemAttacks - spell damage and mana cost (fixes #1, #2)', () =
       () => ({ floorHP: 50, floorMaxHP: 100, roomCleared: false }),
       'fire',
       () => enemy,
+      () => [enemy],
       () => {},
     );
 
@@ -214,10 +217,12 @@ describe('processGolemAttacks - elemental matchup (fix #3)', () => {
     const enemy = makeEnemy({ element: 'fire', armor: 0 }); // No armor for clean test
 
     const frame = FRAMES['crystal'];
-    const expectedDmg = frame.baseDamage; // 1.0x neutral, no armor
+    // Crystal frame: baseDamage=14, armorPierce=0.15, neutral element (1.0x)
+    // New formula: 14 * 1.0 * (1 + 0.15) = 16.1
+    const expectedDmg = frame.baseDamage * (1 + frame.armorPierce);
 
     const { capturedDamage } = runGolemAttacks(golem, serialized, design, enemy, 'fire');
-    expect(capturedDamage).toBe(expectedDmg);
+    expect(capturedDamage).toBeCloseTo(expectedDmg, 5);
   });
 });
 
@@ -238,6 +243,7 @@ describe('processGolemAttacks - enchantment effects (fix #4)', () => {
       () => ({ floorHP: 50, floorMaxHP: 100, roomCleared: false }),
       'fire',
       () => enemy,
+      () => [enemy],
       (enemyId, effects) => { appliedEffects.push({ enemyId, effects }); },
     );
 
@@ -259,6 +265,7 @@ describe('processGolemAttacks - enchantment effects (fix #4)', () => {
       () => ({ floorHP: 50, floorMaxHP: 100, roomCleared: false }),
       'fire',
       () => enemy,
+      () => [enemy],
       (_, effects) => { appliedEffects.push(effects); },
     );
 
@@ -282,6 +289,7 @@ describe('processGolemAttacks - enchantment effects (fix #4)', () => {
       () => ({ floorHP: 50, floorMaxHP: 100, roomCleared: false }),
       'fire',
       () => enemy,
+      () => [enemy],
       () => { effectsCalled = true; },
     );
 
@@ -289,58 +297,55 @@ describe('processGolemAttacks - enchantment effects (fix #4)', () => {
   });
 });
 
-// ─── Fix #5: Armor pierce ────────────────────────────────────────────────────
+// ─── Fix #5: Armor pierce (spire-combat spec §9.4) ──────────────────────────
+// Formula: dmg = frame.baseDamage × (1 + frame.armorPierce)
+// Enemy armor reduction is handled separately in onDamageDealt.
 
 describe('processGolemAttacks - armor pierce (fix #5)', () => {
-  it('does not multiply damage by (1 + armorPierce)', () => {
+  it('applies armor pierce as damage multiplier per spire-combat spec §9.4', () => {
     // Steel frame: baseDamage=18, armorPierce=0.5
-    // Old buggy formula: 18 * (1 + 0.5) = 27
-    // Correct: 18 with 50% armor bypass against 40% armor
+    // New formula: 18 * (1 + 0.5) = 27
     const design = makeDesign('basic', 'steel', 'simple');
     const serialized = makeSerialized(design);
     const golem = makeActiveGolem(design, undefined, 1.0);
     const enemy = makeEnemy({ armor: 0.4 });
 
     const frame = FRAMES['steel'];
-    // With 50% armor pierce: effectiveArmor = 0.4 * (1 - 0.5) = 0.2
-    // dmg = 18 * (1 - 0.2) = 14.4
-    const expectedDmg = frame.baseDamage * (1 - 0.4 * (1 - frame.armorPierce));
+    const expectedDmg = frame.baseDamage * (1 + frame.armorPierce);
 
     const { capturedDamage } = runGolemAttacks(golem, serialized, design, enemy, 'fire');
 
-    // Should NOT be 18 * 1.5 = 27 (old buggy formula)
-    expect(capturedDamage).not.toBe(frame.baseDamage * (1 + frame.armorPierce));
-    // Should be the correct armor-bypassed value
     expect(capturedDamage).toBe(expectedDmg);
   });
 
-  it('fully bypasses armor when armorPierce is 1.0', () => {
+  it('doubles damage when armorPierce is 1.0', () => {
+    // dmg = 10 * (1 + 1.0) = 20
     const dmg = computeBasicAttackDamage(
       { baseDamage: 10, armorPierce: 1.0, element: undefined },
       0, 0.8, 'fire',
     );
-    expect(dmg).toBe(10); // Full damage, armor fully bypassed
+    expect(dmg).toBe(20);
   });
 
-  it('applies no armor bypass when armorPierce is 0', () => {
+  it('returns base damage when armorPierce is 0', () => {
+    // dmg = 10 * (1 + 0) = 10
     const dmg = computeBasicAttackDamage(
       { baseDamage: 10, armorPierce: 0, element: undefined },
       0, 0.5, 'fire',
     );
-    // 50% armor, no pierce: 10 * (1 - 0.5) = 5
-    expect(dmg).toBe(5);
+    expect(dmg).toBe(10);
   });
 
   it('stacks enchantment armorPierce with frame armorPierce', () => {
     const framePierce = 0.5;
     const enchantPierce = 0.15;
-    const totalPierce = Math.min(1, framePierce + enchantPierce);
+    const totalPierce = framePierce + enchantPierce;
 
     const dmg = computeBasicAttackDamage(
       { baseDamage: 20, armorPierce: framePierce, element: undefined },
       enchantPierce, 0.4, 'fire',
     );
-    const expected = 20 * (1 - 0.4 * (1 - totalPierce));
+    const expected = 20 * (1 + totalPierce);
     expect(dmg).toBe(expected);
   });
 });

src/lib/game/stores/golem-combat-actions.ts

@@ -9,8 +9,11 @@ import { computeGolemStats, getGolemSlots } from '../data/golems/utils';
 import {
   resolveEnchantmentEffects,
   computeBasicAttackDamage,
+  processBasicAttack,
 } from './golem-combat-helpers';
+import type { BasicAttackResult } from './golem-combat-helpers';
 import type { GolemEnchantmentEffect } from './golem-combat-helpers';
+import type { SerializedDesign } from '../data/golems/types';
 import type {
   RuntimeActiveGolem,
   GolemLoadoutEntry,
@@ -27,17 +30,6 @@ export interface GolemCombatResult {
   totalDamageDealt: number;
 }
 
-interface SerializedDesign {
-  id: string;
-  name: string;
-  coreId: string;
-  frameId: string;
-  mindCircuitId: string;
-  enchantmentIds: string[];
-  selectedManaTypes: string[];
-  selectedSpells: string[];
-}
-
 // ─── Summoning (spec §10) ───────────────────────────────────────────────────
 
 /**
@@ -95,6 +87,8 @@ export function summonGolemsOnRoomEntry(
       enchantments: [],
       selectedManaTypes: design.selectedManaTypes,
       selectedSpells: design.selectedSpells,
+      guardianSummonCost: design.guardianSummonCost,
+      guardianPrimaryManaType: design.guardianPrimaryManaType,
     });
 
     let canAfford = true;
@@ -239,7 +233,7 @@ export function processGolemManaRegen(
  * 2. Spell mana cost: uses actual SPELLS_DEF[spellId].cost.amount
  * 3. Elemental matchup: applies getElementalBonus to basic attacks
  * 4. Enchantment effects: applies golem enchantment effects on basic attacks
- * 5. Armor pierce: bypasses enemy armor fraction instead of multiplying damage
+ * 5. Armor pierce: per spire-combat spec §9.4, dmg = baseDamage × (1 + armorPierce)
  */
 export function processGolemAttacks(
   activeGolems: RuntimeActiveGolem[],
@@ -252,6 +246,7 @@ export function processGolemAttacks(
   applyDamageToRoom: (dmg: number) => { floorHP: number; floorMaxHP: number; roomCleared: boolean },
   enemyElement: string,
   getTargetEnemy: () => EnemyState | null,
+  getTargetEnemies: () => EnemyState[],
   onApplyEnchantmentEffects: (enemyId: string, effects: GolemEnchantmentEffect[]) => void,
 ): GolemCombatResult {
   let rawMana = 0;
@@ -273,6 +268,7 @@ export function processGolemAttacks(
 
     const enchantmentEffects = resolveEnchantmentEffects(design.enchantmentIds);
     const bonusArmorPierce = design.enchantmentIds.includes('sword_metal') ? 0.15 : 0;
+    const isAoe = frame.aoeTargets > 1;
 
     let attackProgress = golem.attackProgress + HOURS_PER_TICK * frame.attackSpeed;
     const updatedGolem = { ...golem };
@@ -314,29 +310,23 @@ export function processGolemAttacks(
         }
       }
 
-      // Basic attack
-      // FIX #3, #4, #5: elemental matchup, enchantment effects, proper armor pierce
-      const targetEnemy = getTargetEnemy();
-      const enemyArmor = targetEnemy?.armor ?? 0;
-
-      const dmg = computeBasicAttackDamage(frame, bonusArmorPierce, enemyArmor, enemyElement);
-
-      // Apply enchantment effects to target enemy
-      if (enchantmentEffects.length > 0 && targetEnemy) {
-        onApplyEnchantmentEffects(targetEnemy.id, enchantmentEffects);
-      }
-
-      const dmgResult = onDamageDealt(dmg, true);
-      const finalDamage = dmgResult.modifiedDamage || dmg;
-
-      if (Number.isFinite(finalDamage)) {
-        const roomResult = applyDamageToRoom(finalDamage);
-        floorHP = roomResult.floorHP;
-        floorMaxHP = roomResult.floorMaxHP;
-        totalDamageDealt += Math.max(0, finalDamage);
-        rawMana = dmgResult.rawMana;
-        elements = dmgResult.elements;
-      }
+      // Basic attack: AoE or single-target (delegated to helper)
+      const basicResult: BasicAttackResult = processBasicAttack({
+        frame: { ...frame, aoeTargets: frame.aoeTargets },
+        bonusArmorPierce,
+        enchantmentEffects,
+        enemyElement,
+        getTargetEnemy,
+        getTargetEnemies,
+        onDamageDealt,
+        applyDamageToRoom,
+        onApplyEnchantmentEffects,
+      });
+      rawMana = basicResult.rawMana;
+      elements = basicResult.elements;
+      floorHP = basicResult.floorHP;
+      floorMaxHP = basicResult.floorMaxHP;
+      totalDamageDealt += basicResult.totalDamageDealt;
 
       attackProgress -= 1;
       safetyCounter++;

src/lib/game/stores/golem-combat-helpers.test.ts

@@ -50,39 +50,42 @@ describe('computeBasicAttackDamage', () => {
   });
 
   it('combines elemental bonus and armor pierce', () => {
-    // Water vs Fire = 1.5x, then 50% armor with 25% pierce
-    // effectiveArmor = 0.5 * (1 - 0.25) = 0.375
-    // dmg = 10 * 1.5 * (1 - 0.375) = 9.375
+    // Water vs Fire = 1.5x, then armor pierce adds to damage multiplier
+    // dmg = 10 * 1.5 * (1 + 0.25) = 18.75
     const dmg = computeBasicAttackDamage(
       { baseDamage: 10, armorPierce: 0.25, element: 'water' },
       0, 0.5, 'fire',
     );
-    expect(dmg).toBeCloseTo(9.375, 5);
+    expect(dmg).toBeCloseTo(18.75, 5);
   });
 
-  it('fully bypasses armor when armorPierce is 1.0', () => {
+  it('doubles damage when armorPierce is 1.0', () => {
+    // dmg = 10 * (1 + 1.0) = 20
     const dmg = computeBasicAttackDamage(
       { baseDamage: 10, armorPierce: 1.0, element: undefined },
       0, 0.8, 'fire',
     );
-    expect(dmg).toBe(10);
+    expect(dmg).toBe(20);
   });
 
-  it('applies no armor bypass when armorPierce is 0', () => {
+  it('returns base damage when armorPierce is 0', () => {
+    // dmg = 10 * (1 + 0) = 10
     const dmg = computeBasicAttackDamage(
       { baseDamage: 10, armorPierce: 0, element: undefined },
       0, 0.5, 'fire',
     );
-    expect(dmg).toBe(5);
+    expect(dmg).toBe(10);
   });
 
   it('stacks enchantment armorPierce with frame armorPierce', () => {
-    const totalPierce = Math.min(1, 0.5 + 0.15);
+    // totalPierce = 0.5 + 0.15 = 0.65
+    // dmg = 20 * (1 + 0.65) = 33
+    const totalPierce = 0.5 + 0.15;
     const dmg = computeBasicAttackDamage(
       { baseDamage: 20, armorPierce: 0.5, element: undefined },
       0.15, 0.4, 'fire',
     );
-    expect(dmg).toBe(20 * (1 - 0.4 * (1 - totalPierce)));
+    expect(dmg).toBe(20 * (1 + totalPierce));
   });
 });
 

src/lib/game/stores/golem-combat-helpers.ts

@@ -45,26 +45,105 @@ export function resolveEnchantmentEffects(enchantmentIds: string[]): GolemEnchan
 
 /**
  * Compute basic attack damage for a golem.
- * Applies elemental matchup bonus and proper armor pierce (bypasses armor fraction).
+ * Formula per spire-combat spec §9.4: dmg = frame.baseDamage × (1 + frame.armorPierce)
+ * Also applies elemental matchup bonus and enchantment armor pierce bonus.
+ * Enemy armor reduction is handled separately in onDamageDealt.
  */
 export function computeBasicAttackDamage(
   frame: { baseDamage: number; armorPierce: number; element?: string },
   enchantmentBonusArmorPierce: number,
-  enemyArmor: number,
+  _enemyArmor: number,
   enemyElement: string,
 ): number {
   let dmg = frame.baseDamage;
   if (frame.element) {
     dmg *= getElementalBonus(frame.element, enemyElement);
   }
-  const totalArmorPierce = Math.min(1, frame.armorPierce + enchantmentBonusArmorPierce);
-  const effectiveArmor = enemyArmor * (1 - totalArmorPierce);
-  if (effectiveArmor > 0) {
-    dmg *= (1 - effectiveArmor);
-  }
+  const totalArmorPierce = frame.armorPierce + enchantmentBonusArmorPierce;
+  dmg *= (1 + totalArmorPierce);
   return Math.max(0, dmg);
 }
 
+// ─── Basic Attack Processing ────────────────────────────────────────────────
+
+export interface BasicAttackContext {
+  frame: { baseDamage: number; armorPierce: number; element?: string; aoeTargets: number };
+  bonusArmorPierce: number;
+  enchantmentEffects: GolemEnchantmentEffect[];
+  enemyElement: string;
+  getTargetEnemy: () => EnemyState | null;
+  getTargetEnemies: () => EnemyState[];
+  onDamageDealt: (damage: number, skipSpecials?: boolean) => {
+    rawMana: number;
+    elements: Record<string, { current: number; max: number; unlocked: boolean }>;
+    modifiedDamage?: number;
+  };
+  applyDamageToRoom: (dmg: number) => { floorHP: number; floorMaxHP: number; roomCleared: boolean };
+  onApplyEnchantmentEffects: (enemyId: string, effects: GolemEnchantmentEffect[]) => void;
+}
+
+export interface BasicAttackResult {
+  rawMana: number;
+  elements: Record<string, { current: number; max: number; unlocked: boolean }>;
+  floorHP: number;
+  floorMaxHP: number;
+  totalDamageDealt: number;
+}
+
+/**
+ * Process a single basic attack (AoE or single-target) for a golem.
+ * AoE frames distribute damage across up to frame.aoeTargets enemies (spec §11).
+ * Single-target frames attack the lowest-HP enemy.
+ */
+export function processBasicAttack(ctx: BasicAttackContext): BasicAttackResult {
+  let rawMana = 0;
+  let elements: Record<string, { current: number; max: number; unlocked: boolean }> = {};
+  let floorHP = 0;
+  let floorMaxHP = 0;
+  let totalDamageDealt = 0;
+
+  if (ctx.frame.aoeTargets > 1) {
+    const allEnemies = ctx.getTargetEnemies();
+    if (allEnemies.length > 0) {
+      const targets = allEnemies.slice(0, ctx.frame.aoeTargets);
+      const dmgPerTarget = computeBasicAttackDamage(ctx.frame, ctx.bonusArmorPierce, 0, ctx.enemyElement) / targets.length;
+      for (const target of targets) {
+        if (ctx.enchantmentEffects.length > 0) {
+          ctx.onApplyEnchantmentEffects(target.id, ctx.enchantmentEffects);
+        }
+        const dmgResult = ctx.onDamageDealt(dmgPerTarget, true);
+        const finalDamage = dmgResult.modifiedDamage || dmgPerTarget;
+        if (Number.isFinite(finalDamage)) {
+          const roomResult = ctx.applyDamageToRoom(finalDamage);
+          floorHP = roomResult.floorHP;
+          floorMaxHP = roomResult.floorMaxHP;
+          totalDamageDealt += Math.max(0, finalDamage);
+          rawMana = dmgResult.rawMana;
+          elements = dmgResult.elements;
+        }
+      }
+    }
+  } else {
+    const targetEnemy = ctx.getTargetEnemy();
+    const dmg = computeBasicAttackDamage(ctx.frame, ctx.bonusArmorPierce, 0, ctx.enemyElement);
+    if (ctx.enchantmentEffects.length > 0 && targetEnemy) {
+      ctx.onApplyEnchantmentEffects(targetEnemy.id, ctx.enchantmentEffects);
+    }
+    const dmgResult = ctx.onDamageDealt(dmg, true);
+    const finalDamage = dmgResult.modifiedDamage || dmg;
+    if (Number.isFinite(finalDamage)) {
+      const roomResult = ctx.applyDamageToRoom(finalDamage);
+      floorHP = roomResult.floorHP;
+      floorMaxHP = roomResult.floorMaxHP;
+      totalDamageDealt += Math.max(0, finalDamage);
+      rawMana = dmgResult.rawMana;
+      elements = dmgResult.elements;
+    }
+  }
+
+  return { rawMana, elements, floorHP, floorMaxHP, totalDamageDealt };
+}
+
 // ─── Golem Attacks Store Wrapper ─────────────────────────────────────────────
 
 // Import here is safe: only used inside the function body, not at module init time.
@@ -108,6 +187,10 @@ export function processGolemAttacksFromStore(
       if (living.length === 0) return null;
       return living.reduce((lowest, e) => (e.hp < lowest.hp ? e : lowest));
     },
+    () => {
+      const room = get().currentRoom;
+      return room.enemies.filter((e) => e.hp > 0);
+    },
     (enemyId, effects) => {
       const room = get().currentRoom;
       const updatedEnemies = room.enemies.map((e) => {