@alpaca-software/40kdc-data 0.1.2 → 0.1.3

package/dist/cruncher/from-dsl.js

@@ -17,8 +17,9 @@ const DEFENDER_TARGETS = new Set(["defender", "enemy-within-aura", "all-enemy"])
  * naming any branches the buff layer can't express today.
  */
 export function effectToBuffs(effect, source, context, perspective = "attacker") {
-    const out = { applied: [], unsupported: [] };
-    walk(effect, source, { context, perspective }, out);
+    const out = { applied: [], unsupported: [], activatable: [] };
+    const abilityId = source.kind === "ability" ? source.abilityId : "effect";
+    walk(effect, source, { context, perspective, abilityId }, out);
     return out;
 }
 function walk(node, source, opts, out) {
@@ -52,11 +53,8 @@ function walk(node, source, opts, out) {
                 walk(step, source, opts, out);
             return;
         case "choice":
-            // Player decision — auto-applying every branch would double-count.
-            out.unsupported.push({
-                reason: "choice: player picks one option; the buff layer can't choose",
-                effectFragment: node,
-            });
+            // Player decision — each branch becomes an opt-in lever (pick one).
+            enumerateChoice(node, source, opts, out);
             return;
         case "dice-gated":
             // Probabilistic; the buff layer is deterministic.
@@ -66,10 +64,9 @@ function walk(node, source, opts, out) {
             });
             return;
         case "dice-pool-allocation":
-            out.unsupported.push({
-                reason: "dice-pool-allocation: player allocates dice at runtime",
-                effectFragment: node,
-            });
+            // Player spends dice on options at runtime — each buff-bearing option
+            // becomes an opt-in lever, grouped under the pool's activation cap.
+            enumerateDicePool(node, source, opts, out);
             return;
         default:
             // Unknown effect — record it. Covers ability-grant, deep-strike,
@@ -132,8 +129,17 @@ function translateReroll(node, source, opts, out) {
         out.unsupported.push({ reason: "re-roll: missing modifier object", effectFragment: node });
         return;
     }
+    const narrowed = unhonorableNarrowing(modifier);
+    if (narrowed) {
+        out.unsupported.push({ reason: `re-roll: narrows by "${narrowed}" which the cruncher can't resolve here`, effectFragment: node });
+        return;
+    }
     const roll = modifier.roll;
-    const subset = modifier.subset;
+    // A `value: 1` on a re-roll modifier unambiguously means "re-roll rolls of 1".
+    // A historical migration (2026-weapon-keywords) mis-defaulted such nodes to
+    // `subset: "all-failures"`; honor the value as the source of truth so any
+    // stray data of that shape can't silently over-apply the reroll.
+    const subset = modifier.value === 1 ? "ones" : modifier.subset;
     // Under target perspective, only "save" rerolls fire on the buffed unit.
     if (opts.perspective === "target" && roll !== "save")
         return;
@@ -156,6 +162,11 @@ function translateRollModifier(node, source, opts, out) {
         });
         return;
     }
+    const narrowed = unhonorableNarrowing(modifier);
+    if (narrowed) {
+        out.unsupported.push({ reason: `roll-modifier: narrows by "${narrowed}" which the cruncher can't resolve here`, effectFragment: node });
+        return;
+    }
     const value = signedValue(modifier);
     if (value === null) {
         out.unsupported.push({
@@ -210,6 +221,27 @@ function translateStatModifier(node, source, opts, out) {
         });
         return;
     }
+    const narrowed = unhonorableNarrowing(modifier);
+    if (narrowed) {
+        out.unsupported.push({ reason: `stat-modifier: narrows by "${narrowed}" which the cruncher can't resolve here`, effectFragment: node });
+        return;
+    }
+    const stat = modifier.stat;
+    const isOnBuffedUnit = appliesToBuffedUnit(node, opts.perspective);
+    // `attack_type: melee|ranged` scopes the mod to that attack — express it as a
+    // phase gate so e.g. a melee +1 Attack doesn't fire in the shooting phase.
+    const applicability = attackTypeApplicability(modifier);
+    const emit = (contribution) => {
+        const buff = { source, contribution };
+        out.applied.push(applicability ? { ...buff, applicableWhen: applicability } : buff);
+    };
+    // AP has an inverted sign convention (stored negative; more negative = more
+    // piercing) and offensive/defensive variants, so it computes its own delta
+    // and routes by attacker/defender rather than going through `signedValue`.
+    if (stat === "AP") {
+        translateApModifier(node, modifier, opts, out, emit);
+        return;
+    }
     const value = signedValue(modifier);
     if (value === null) {
         out.unsupported.push({
@@ -218,18 +250,16 @@ function translateStatModifier(node, source, opts, out) {
         });
         return;
     }
-    const stat = modifier.stat;
-    const isOnBuffedUnit = appliesToBuffedUnit(node, opts.perspective);
     switch (stat) {
         case "A":
             if (opts.perspective !== "attacker" || !isOnBuffedUnit)
                 return;
-            out.applied.push({ source, contribution: { type: "attacks-mod", value } });
+            emit({ type: "attacks-mod", value });
             return;
         case "S":
             if (opts.perspective !== "attacker" || !isOnBuffedUnit)
                 return;
-            out.applied.push({ source, contribution: { type: "strength-mod", value } });
+            emit({ type: "strength-mod", value });
             return;
         case "T":
             // Defender stat. Only relevant under target perspective.
@@ -242,7 +272,7 @@ function translateStatModifier(node, source, opts, out) {
             }
             if (!isOnBuffedUnit)
                 return;
-            out.applied.push({ source, contribution: { type: "toughness-mod", value } });
+            emit({ type: "toughness-mod", value });
             return;
         case "Sv":
             // Saves improve when the *defender* gets +Sv. A +1 to Sv in printed
@@ -259,16 +289,7 @@ function translateStatModifier(node, source, opts, out) {
             }
             if (!isOnBuffedUnit)
                 return;
-            out.applied.push({ source, contribution: { type: "save-mod", value: -value } });
-            return;
-        case "AP":
-            // AP rides on the attacker's weapon profile and is stored as a negative
-            // number in the data (e.g. AP -1). The data's `{operation:"add", value:-1}`
-            // form means "AP becomes one more negative" → more piercing. `signedValue`
-            // already returns that negative number directly, so pass it through.
-            if (opts.perspective !== "attacker" || !isOnBuffedUnit)
-                return;
-            out.applied.push({ source, contribution: { type: "ap-mod", value } });
+            emit({ type: "save-mod", value: -value });
             return;
         default:
             out.unsupported.push({
@@ -277,6 +298,40 @@ function translateStatModifier(node, source, opts, out) {
             });
     }
 }
+/**
+ * Translate an `AP` stat-modifier. AP rides on the attacker's weapon profile and
+ * is stored as a negative number (e.g. AP -1); more negative = more piercing.
+ *
+ * Two variants exist in the data:
+ *  - **offensive** (`target` self/unit): the buffed unit's own weapons gain AP —
+ *    an attacker-side `ap-mod`. `improve N` → `-N` (more piercing), `worsen N` →
+ *    `+N`, and the legacy `add`/`subtract` forms (which already pass a signed,
+ *    usually negative, value) flow through `apDelta` unchanged.
+ *  - **defensive** (`target: "attacker"`): "enemy weapons targeting this unit
+ *    have AP worsened". This applies when the buffed unit is the *target*; we do
+ *    not model it as an attacker-side buff (that would wrongly weaken the buffed
+ *    unit's own attacks), so it is surfaced as `unsupported`.
+ */
+function translateApModifier(node, modifier, opts, out, emit) {
+    if (classifyTarget(node) === "attacker") {
+        out.unsupported.push({
+            reason: "stat-modifier AP on the attacker: defender-side AP reduction is not modelled by the buff layer",
+            effectFragment: node,
+        });
+        return;
+    }
+    if (opts.perspective !== "attacker" || !appliesToBuffedUnit(node, "attacker"))
+        return;
+    const delta = apDelta(modifier);
+    if (delta === null) {
+        out.unsupported.push({
+            reason: `stat-modifier AP: operation "${String(modifier.operation)}" not supported`,
+            effectFragment: node,
+        });
+        return;
+    }
+    emit({ type: "ap-mod", value: delta });
+}
 function translateFeelNoPain(node, source, opts, out) {
     // FNP applies when the buffed unit is the *target* — it ablates incoming
     // damage. Under attacker perspective the FNP is irrelevant (the unit is
@@ -315,12 +370,15 @@ function translateKeywordGrant(node, source, opts, out) {
     const modifier = node.modifier;
     if (!isObject(modifier))
         return;
-    const keywords = modifier.keywords;
-    if (!Array.isArray(keywords))
+    // The DSL grants keywords in two shapes: a singular `keyword` string (often
+    // with a `weapon_type`) or a `keywords` array. Accept both.
+    const raws = keywordGrantList(modifier);
+    if (raws.length === 0)
         return;
-    for (const raw of keywords) {
-        if (typeof raw !== "string")
-            continue;
+    // `weapon_type: melee|ranged` scopes the grant to that attack — a melee-only
+    // keyword shouldn't fire in the shooting phase. Express it as a phase gate.
+    const applicability = weaponTypeApplicability(modifier);
+    for (const raw of raws) {
         const ref = parseKeywordGrant(raw);
         if (!ref) {
             out.unsupported.push({
@@ -329,8 +387,55 @@ function translateKeywordGrant(node, source, opts, out) {
             });
             continue;
         }
-        out.applied.push({ source, contribution: { type: "extra-keyword", keywordRef: ref } });
+        const buff = { source, contribution: { type: "extra-keyword", keywordRef: ref } };
+        out.applied.push(applicability ? { ...buff, applicableWhen: applicability } : buff);
+    }
+}
+/** Normalise a keyword-grant modifier's singular `keyword` and/or `keywords` array. */
+function keywordGrantList(modifier) {
+    const out = [];
+    if (typeof modifier.keyword === "string")
+        out.push(modifier.keyword);
+    if (Array.isArray(modifier.keywords)) {
+        for (const k of modifier.keywords)
+            if (typeof k === "string")
+                out.push(k);
     }
+    return out;
+}
+/** Map a keyword-grant's `weapon_type` to the phase its weapons fire in. */
+function weaponTypeApplicability(modifier) {
+    if (modifier.weapon_type === "melee")
+        return { phases: ["fight"] };
+    if (modifier.weapon_type === "ranged")
+        return { phases: ["shooting"] };
+    return undefined;
+}
+/**
+ * Map a stat-modifier's `attack_type` (or the equivalent `weapon_type`) to the
+ * phase that attack happens in. Both spellings carry the same melee/ranged
+ * intent; honoring `weapon_type` lets a "+1 A to melee weapons" mod phase-gate
+ * correctly instead of leaking into the shooting phase.
+ */
+function attackTypeApplicability(modifier) {
+    const kind = modifier.attack_type ?? modifier.weapon_type;
+    if (kind === "melee")
+        return { phases: ["fight"] };
+    if (kind === "ranged")
+        return { phases: ["shooting"] };
+    return undefined;
+}
+/**
+ * Narrowing keys that scope a buff to a named weapon or a model subset the
+ * cruncher can't resolve at translation time (it has no weapon/model context
+ * here). When present on a damage-path leaf, applying the buff unfiltered would
+ * silently OVER-APPLY it, so we surface it as `unsupported` instead — the data
+ * stays faithful for other consumers; the optimizer just doesn't assume it.
+ * `weapon_type`/`attack_type` are NOT here — those map cleanly to a phase gate.
+ */
+const UNHONORABLE_NARROWING = ["weapon_name", "weapon_profile", "weapon_keyword", "weapon_filter", "model_filter", "model_scope"];
+function unhonorableNarrowing(modifier) {
+    return UNHONORABLE_NARROWING.find((k) => modifier[k] != null);
 }
 function translateBsModifier(node, source, opts, out) {
     // A bs-modifier on `target: "attacker"` is a defender-side rule: it
@@ -358,10 +463,18 @@ function translateConditional(node, source, opts, out) {
     const negated = condition.negated === true;
     const verdict = evaluateCondition(condition, opts.context);
     if (verdict === "unknown") {
-        out.unsupported.push({
-            reason: `conditional: cannot evaluate condition "${String(condition.type)}" against current context`,
-            effectFragment: node,
-        });
+        // A timing the player controls (e.g. "start of phase") isn't a wall — it's
+        // an activation the player can opt into. Surface it as a lever rather than
+        // dropping it. Other unevaluatable conditions stay unsupported.
+        if (conditionMentionsTiming(condition)) {
+            enumerateTimingGate(node, source, opts, out);
+        }
+        else {
+            out.unsupported.push({
+                reason: `conditional: cannot evaluate condition "${String(condition.type)}" against current context`,
+                effectFragment: node,
+            });
+        }
         return;
     }
     const active = negated ? !verdict : verdict;
@@ -370,6 +483,294 @@ function translateConditional(node, source, opts, out) {
     walk(effect, source, opts, out);
 }
 // ---------------------------------------------------------------------------
+// Activatable-lever enumeration
+//
+// Player-controlled gates — a `timing-is` the context can't pin down, each
+// `dice-pool-allocation` option, each `choice` branch — aren't walls for a
+// damage optimizer; they're the search space. Instead of dropping them to
+// `unsupported`, we descend through them and surface every buff-bearing branch
+// as an opt-in {@link ActivatableBuff}. The descent reuses the normal leaf
+// translators (so a lever applies exactly what it advertises) and turns the
+// conditions a branch still carries (target keyword, phase) into declarative
+// `applicableWhen` so the resolver gates them per-target.
+// ---------------------------------------------------------------------------
+/** Emit one lever per `choice` branch that yields a buff (pick exactly one). */
+function enumerateChoice(node, source, opts, out) {
+    const options = Array.isArray(node.options) ? node.options : [];
+    options.forEach((opt, i) => {
+        const buffs = [];
+        collectGatedBuffs(opt, source, opts, {}, buffs);
+        if (buffs.length === 0)
+            return;
+        out.activatable.push({
+            id: `${opts.abilityId}?${i}`,
+            label: labelForBuffs(buffs),
+            buffs,
+            group: { id: `${opts.abilityId}?choice`, maxActivations: 1 },
+        });
+    });
+}
+/** Emit one lever per buff-bearing dice-pool option, capped by `max_activations`. */
+function enumerateDicePool(node, source, opts, out) {
+    const options = Array.isArray(node.options) ? node.options : [];
+    const maxActivations = typeof node.max_activations === "number" ? node.max_activations : options.length;
+    for (const opt of options) {
+        if (!isObject(opt))
+            continue;
+        const buffs = [];
+        collectGatedBuffs(opt.effect, source, opts, {}, buffs);
+        if (buffs.length === 0)
+            continue;
+        const name = typeof opt.name === "string" && opt.name ? opt.name : labelForBuffs(buffs);
+        out.activatable.push({
+            id: `${opts.abilityId}#${name}`,
+            label: name,
+            buffs,
+            group: { id: opts.abilityId, maxActivations },
+        });
+    }
+}
+/**
+ * Surface a timing-gated activation. The timing itself is just "when" — opting
+ * in satisfies it — so we descend into the body: an inner `dice-pool-allocation`
+ * or `choice` surfaces its *own* option levers (e.g. Blessings of Khorne's
+ * three keyword grants), while inner always-on buffs bundle into a single
+ * timing lever. A body with no modelable combat buff (a `resurrection` or
+ * `dice-gated`, like Berzerker Frenzy) yields nothing.
+ */
+function enumerateTimingGate(node, source, opts, out) {
+    const condition = node.condition;
+    if (!isObject(condition))
+        return;
+    const sub = { applied: [], unsupported: [], activatable: [] };
+    walk(node.effect, source, opts, sub);
+    // Inner independent decisions (dice-pool options, choice branches) pass
+    // straight through as their own levers.
+    out.activatable.push(...sub.activatable);
+    // Inner unconditional buffs become one lever gated only on the timing.
+    if (sub.applied.length > 0) {
+        const timing = extractTiming(condition) ?? "timing";
+        out.activatable.push({
+            id: `${opts.abilityId}@${timing}`,
+            label: labelForBuffs(sub.applied),
+            buffs: sub.applied,
+        });
+    }
+}
+/**
+ * Walk the body of a player gate, collecting the buffs it would contribute.
+ * Conditions are deferred to `applicableWhen` where expressible; nested
+ * decisions and stochastic rolls inside an activation are not modelled.
+ */
+function collectGatedBuffs(node, source, opts, applicability, outBuffs) {
+    if (!isObject(node))
+        return;
+    switch (node.type) {
+        case "conditional": {
+            const condition = node.condition;
+            if (!isObject(condition))
+                return;
+            const app = conditionToApplicability(condition);
+            if (app === "gate") {
+                // A nested timing gate: opting into the activation satisfies it, so
+                // keep descending without adding a constraint.
+                collectGatedBuffs(node.effect, source, opts, applicability, outBuffs);
+                return;
+            }
+            if (app === "context") {
+                // Can't express as a buff gate — fall back to the current context and
+                // only descend when the condition is definitely active.
+                if (evaluateCondition(condition, opts.context) === true) {
+                    collectGatedBuffs(node.effect, source, opts, applicability, outBuffs);
+                }
+                return;
+            }
+            collectGatedBuffs(node.effect, source, opts, combineApplicability(applicability, app), outBuffs);
+            return;
+        }
+        case "sequence":
+            for (const step of node.steps ?? []) {
+                collectGatedBuffs(step, source, opts, applicability, outBuffs);
+            }
+            return;
+        case "choice":
+        case "dice-pool-allocation":
+        case "dice-gated":
+            // A decision (or stochastic roll) nested inside an activation. The outer
+            // lever already stands for a player choice; we don't model the inner one.
+            return;
+        default: {
+            // Leaf effect — run the normal leaf translators into a throwaway sink,
+            // then attach the accumulated applicability so target/phase gating
+            // defers to the resolver instead of vanishing the lever.
+            const tmp = { applied: [], unsupported: [], activatable: [] };
+            walk(node, source, opts, tmp);
+            for (const b of tmp.applied)
+                outBuffs.push(applyApplicability(b, applicability));
+            return;
+        }
+    }
+}
+/** Does this condition (or any operand) gate on a player-controlled timing? */
+function conditionMentionsTiming(condition) {
+    if (condition.type === "timing-is")
+        return true;
+    if (typeof condition.operator === "string" && Array.isArray(condition.operands)) {
+        return condition.operands.some((o) => isObject(o) && conditionMentionsTiming(o));
+    }
+    return false;
+}
+/** Pull the first `timing-is` timing value out of a (possibly compound) condition. */
+function extractTiming(condition) {
+    if (condition.type === "timing-is") {
+        const t = condition.parameters?.timing;
+        return typeof t === "string" ? t : undefined;
+    }
+    if (Array.isArray(condition.operands)) {
+        for (const o of condition.operands) {
+            if (isObject(o)) {
+                const t = extractTiming(o);
+                if (t)
+                    return t;
+            }
+        }
+    }
+    return undefined;
+}
+/**
+ * Translate a condition into a {@link BuffApplicability} the resolver can gate
+ * on. Returns `"gate"` for a player-controlled timing (satisfied by opting in),
+ * or `"context"` when the condition has no declarative buff representation and
+ * must fall back to context evaluation.
+ */
+function conditionToApplicability(condition) {
+    if (condition.negated === true)
+        return "context";
+    if (typeof condition.operator === "string" && Array.isArray(condition.operands)) {
+        if (condition.operator !== "and")
+            return "context";
+        let merged = {};
+        for (const operand of condition.operands) {
+            if (!isObject(operand))
+                return "context";
+            const a = conditionToApplicability(operand);
+            if (a === "gate")
+                continue; // timing operand: satisfied by opting in.
+            if (a === "context")
+                return "context";
+            merged = combineApplicability(merged, a);
+        }
+        return merged;
+    }
+    const params = condition.parameters;
+    switch (condition.type) {
+        case "timing-is":
+            return "gate";
+        case "phase-is": {
+            const phase = params?.phase;
+            return typeof phase === "string" ? { phases: [phase] } : "context";
+        }
+        case "target-has-keyword": {
+            const kw = params?.keyword;
+            return typeof kw === "string" ? { requiresTargetKeyword: kw } : "context";
+        }
+        case "unit-has-keyword": {
+            const kw = params?.keyword;
+            return typeof kw === "string" ? { requiresAttackerKeyword: kw } : "context";
+        }
+        case "attack-is-type": {
+            const t = params?.attack_type;
+            if (t === "melee")
+                return { phases: ["fight"] };
+            if (t === "ranged")
+                return { phases: ["shooting"] };
+            return "context";
+        }
+        default:
+            return "context";
+    }
+}
+/** Merge two applicabilities; `phases` intersect, the rest narrow. */
+function combineApplicability(a, b) {
+    const out = { ...a };
+    if (b.phases) {
+        out.phases = a.phases ? a.phases.filter((p) => b.phases.includes(p)) : b.phases;
+    }
+    if (b.rollType)
+        out.rollType = b.rollType;
+    if (b.requiresTargetKeyword)
+        out.requiresTargetKeyword = b.requiresTargetKeyword;
+    if (b.requiresAttackerKeyword)
+        out.requiresAttackerKeyword = b.requiresAttackerKeyword;
+    return out;
+}
+/** Attach an accumulated applicability to a buff (no-op when empty). */
+function applyApplicability(buff, applicability) {
+    if (Object.keys(applicability).length === 0)
+        return buff;
+    const merged = buff.applicableWhen
+        ? combineApplicability(buff.applicableWhen, applicability)
+        : applicability;
+    return { ...buff, applicableWhen: merged };
+}
+/** A short, deduped human label summarising a lever's contributions. */
+function labelForBuffs(buffs) {
+    const seen = new Set();
+    const parts = [];
+    for (const b of buffs) {
+        const p = describeContribution(b.contribution);
+        if (!seen.has(p)) {
+            seen.add(p);
+            parts.push(p);
+        }
+    }
+    return parts.join(", ") || "buff";
+}
+function describeContribution(c) {
+    switch (c.type) {
+        case "extra-keyword":
+            return keywordLabel(c.keywordRef);
+        case "hit-mod":
+            return `${signed(c.value)} to hit`;
+        case "wound-mod":
+            return `${signed(c.value)} to wound`;
+        case "save-mod":
+            return `${signed(c.value)} to save`;
+        case "damage-mod":
+            return `${signed(c.value)} damage`;
+        case "attacks-mod":
+            return `${signed(c.value)} attacks`;
+        case "strength-mod":
+            return `${signed(c.value)} strength`;
+        case "toughness-mod":
+            return `${signed(c.value)} toughness`;
+        case "ap-mod":
+            return `AP ${c.value}`;
+        case "reroll":
+            return `re-roll ${c.roll}${c.subset === "ones" ? " 1s" : ""}`;
+        case "feel-no-pain":
+            return `feel no pain ${c.threshold}+`;
+        case "cover":
+            return "cover";
+    }
+}
+function signed(n) {
+    return n >= 0 ? `+${n}` : `${n}`;
+}
+/** Render a weapon-keyword ref back to its printed form (best-effort). */
+function keywordLabel(ref) {
+    const params = ref.parameters ?? {};
+    if (ref.keyword_id === "anti" && typeof params.target_keyword === "string") {
+        const th = params.threshold;
+        return `Anti-${params.target_keyword}${typeof th === "number" ? ` ${th}+` : ""}`;
+    }
+    const base = ref.keyword_id
+        .split("-")
+        .map((w) => (w ? w.charAt(0).toUpperCase() + w.slice(1) : w))
+        .join(" ");
+    return typeof params.value === "number" ? `${base} ${params.value}` : base;
+}
+// ---------------------------------------------------------------------------
 // Condition evaluator
 // ---------------------------------------------------------------------------
 function evaluateCondition(condition, ctx) {
@@ -398,6 +799,13 @@ function evaluateCondition(condition, ctx) {
         }
         case "remained-stationary":
             return ctx.attackerStationary === true;
+        case "charged-this-turn":
+            // A player-controlled context flag (did the buffed unit charge this turn?),
+            // mirroring `remained-stationary`. Undefined → the caller couldn't pin it
+            // down, so stay "unknown" and let the SPA surface the gap.
+            if (ctx.attackerCharged === undefined)
+                return "unknown";
+            return ctx.attackerCharged;
         case "target-has-keyword": {
             const kw = condition.parameters?.keyword;
             if (typeof kw !== "string")
@@ -411,9 +819,14 @@ function evaluateCondition(condition, ctx) {
             return (ctx.attackerKeywords ?? []).includes(kw.toLowerCase());
         }
         case "is-attached":
-            // The resolver knows whether a leader is attached; absent that signal
-            // here, treat as unknown so the SPA can surface the gap.
-            return "unknown";
+        case "model-is-leader":
+            // True whenever the buffed unit is a combined ("attached") unit. We do
+            // not thread per-member leader identity — "attachment present" is the
+            // signal both conditions gate on. Undefined flag (caller couldn't
+            // determine attachment) stays "unknown" so the SPA surfaces the gap.
+            if (ctx.attackerAttached === undefined)
+                return "unknown";
+            return ctx.attackerAttached;
         default:
             return "unknown";
     }
@@ -471,6 +884,38 @@ function signedValue(modifier) {
     if (!Number.isFinite(value))
         return null;
     switch (modifier.operation) {
+        case "add":
+            return value;
+        case "subtract":
+            return -value;
+        // For the symmetric stats (A/S/T) and roll-/bs-modifiers, "improve" moves
+        // the number up (beneficial) and "worsen" down. AP is handled separately by
+        // `apDelta`, which inverts this because AP's beneficial direction is more
+        // negative.
+        case "improve":
+            return value;
+        case "worsen":
+            return -value;
+        default:
+            // set / halve / multiply: not a single signed delta — left unsupported.
+            return null;
+    }
+}
+/**
+ * Read the AP delta out of a stat-modifier `{operation, value}` pair. AP is
+ * stored negative (more negative = more piercing), so "improve" makes it more
+ * negative and "worsen" less. The legacy `add`/`subtract` forms pass a signed
+ * value through directly (the data already encodes the sign).
+ */
+function apDelta(modifier) {
+    const value = Number(modifier.value);
+    if (!Number.isFinite(value))
+        return null;
+    switch (modifier.operation) {
+        case "improve":
+            return -Math.abs(value);
+        case "worsen":
+            return Math.abs(value);
         case "add":
             return value;
         case "subtract":