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

package/dist/cruncher/attribution.js

@@ -0,0 +1,88 @@
+import { crunch } from "./engine.js";
+const DEFAULT_EPSILON = 1e-6;
+/**
+ * Buffs the UI toggles on/off — the only kinds we attribute. Weapon-keyword
+ * buffs (intrinsics) are left in place for every recompute, so they never show
+ * up as a lift and never perturb the baseline.
+ */
+function isGroupable(source) {
+    return source.kind === "ability" || source.kind === "manual";
+}
+/**
+ * Stable grouping key. Every `Buff` a single UI toggle flatMaps to shares one
+ * key, so a LOO pass removes the whole toggle, never a fragment of it.
+ */
+function groupKey(source) {
+    switch (source.kind) {
+        case "ability":
+            return `a:${source.abilityId}:${source.sourceUnitId ?? ""}`;
+        case "manual":
+            return `m:${source.label}`;
+        case "weapon-keyword":
+            return `w:${source.weaponId}:${source.keywordId}`;
+    }
+}
+/**
+ * Decompose each pipeline stage of `crunch(input)` into the marginal lift of
+ * every toggleable buff group, via leave-one-out recompute.
+ *
+ * Cost is `groups + 2` `crunch` calls (full + baseline + one per group); the
+ * engine is closed-form, so this is cheap to call per weapon line.
+ *
+ * @param input   The same {@link EngineInput} you'd pass to {@link crunch}.
+ * @param dataset Optional dataset override (defaults to the embedded one).
+ * @param opts    `epsilon` — lifts/residuals at or below this magnitude are
+ *                treated as zero (default 1e-6).
+ */
+export function attributeStages(input, dataset, opts) {
+    const epsilon = opts?.epsilon ?? DEFAULT_EPSILON;
+    const full = crunch(input, dataset);
+    // First-seen order of groupable buff groups, with a representative source.
+    const order = [];
+    const repSource = new Map();
+    for (const b of input.buffs) {
+        if (!isGroupable(b.source))
+            continue;
+        const key = groupKey(b.source);
+        if (!repSource.has(key)) {
+            repSource.set(key, b.source);
+            order.push(key);
+        }
+    }
+    // Baseline keeps only non-groupable buffs (weapon-keyword passthroughs) plus
+    // the engine's auto-injected intrinsics.
+    const baseline = crunch({ ...input, buffs: input.buffs.filter((b) => !isGroupable(b.source)) }, dataset);
+    // Leave-one-out: drop one whole group, keep the rest.
+    const loo = new Map();
+    for (const key of order) {
+        const without = input.buffs.filter((b) => !isGroupable(b.source) || groupKey(b.source) !== key);
+        loo.set(key, crunch({ ...input, buffs: without }, dataset));
+    }
+    const intrinsics = full.resolved.extraKeywords.map((e) => e.keywordRef.keyword_id);
+    // crunch always emits the same seven stages in the same order, so index
+    // alignment across full / baseline / loo is sound.
+    return full.stages.map((s, i) => {
+        const expected = s.expected;
+        const baseExpected = baseline.stages[i].expected;
+        let totalLift = 0;
+        const lifts = [];
+        for (const key of order) {
+            const delta = expected - loo.get(key).stages[i].expected;
+            totalLift += delta;
+            if (Math.abs(delta) > epsilon) {
+                lifts.push({ source: repSource.get(key), delta });
+            }
+        }
+        const residual = expected - baseExpected - totalLift;
+        return {
+            name: s.name,
+            expected,
+            detail: s.detail,
+            baseline: baseExpected,
+            lifts,
+            residual: Math.abs(residual) > epsilon ? residual : 0,
+            intrinsics,
+        };
+    });
+}
+//# sourceMappingURL=attribution.js.map

package/dist/cruncher/attribution.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"attribution.js","sourceRoot":"","sources":["../../src/cruncher/attribution.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * Per-stage buff attribution by leave-one-out (LOO) recompute.\n *\n * The engine is closed-form, so the honest way to answer \"how much did this\n * buff lift this stage?\" is to re-run {@link crunch} with that buff removed and\n * diff the stage value. LOO is exactly correct through every non-linearity the\n * pipeline has — the ±1 hit/wound caps, the wound-threshold table, save clamps,\n * FNP, the models-killed cap — and it respects the resolver's non-additive\n * rules for free: a buff that grants a keyword the weapon already carries (e.g.\n * a second Sustained Hits 1) is deduped inside `resolveBuffs`, so its LOO delta\n * comes out ≈ 0 rather than double-counting.\n *\n * Only *toggleable* buffs are attributed — abilities (army / detachment /\n * stratagem / unit / attached / support) and manual UI toggles. The weapon's\n * intrinsic keywords are auto-injected inside `crunch`, are not levers, and are\n * never removed; they're reported by id in {@link AttributedStage.intrinsics}\n * so a UI can explain an elevated baseline without splitting them out.\n *\n * @packageDocumentation\n */\nimport type { Dataset } from \"../data/dataset.js\";\nimport type { BuffSource } from \"./buffs.js\";\nimport { crunch, type EngineInput, type EngineOutput, type Stage } from \"./engine.js\";\n\n/** One toggleable buff group's marginal effect on a single stage. */\nexport type StageLift = {\n  /** Representative source of the group (all its `Buff`s share a group key). */\n  source: BuffSource;\n  /** `stageValue(all buffs) − stageValue(all buffs minus this group)`. */\n  delta: number;\n};\n\n/** A pipeline stage with its value decomposed across the toggleable buffs. */\nexport type AttributedStage = {\n  name: Stage[\"name\"];\n  /** Stage value with every buff on — identical to {@link crunch}'s stage. */\n  expected: number;\n  /** The engine's stage detail string, unchanged. */\n  detail: string;\n  /** Stage value with all groupable buffs removed (intrinsics kept). */\n  baseline: number;\n  /** Per-group marginal effect; groups whose |delta| ≤ epsilon are dropped. */\n  lifts: StageLift[];\n  /**\n   * `expected − baseline − Σ lifts`. Non-zero when buffs collide under a cap\n   * (two +1s sharing one ±1 cap each show ≈0 lift; the real +1 lands here),\n   * so a UI can surface it honestly as \"overlap (capped)\".\n   */\n  residual: number;\n  /** Active weapon-keyword ids (intrinsic, auto-injected); display-only. */\n  intrinsics: string[];\n};\n\nconst DEFAULT_EPSILON = 1e-6;\n\n/**\n * Buffs the UI toggles on/off — the only kinds we attribute. Weapon-keyword\n * buffs (intrinsics) are left in place for every recompute, so they never show\n * up as a lift and never perturb the baseline.\n */\nfunction isGroupable(source: BuffSource): boolean {\n  return source.kind === \"ability\" || source.kind === \"manual\";\n}\n\n/**\n * Stable grouping key. Every `Buff` a single UI toggle flatMaps to shares one\n * key, so a LOO pass removes the whole toggle, never a fragment of it.\n */\nfunction groupKey(source: BuffSource): string {\n  switch (source.kind) {\n    case \"ability\":\n      return `a:${source.abilityId}:${source.sourceUnitId ?? \"\"}`;\n    case \"manual\":\n      return `m:${source.label}`;\n    case \"weapon-keyword\":\n      return `w:${source.weaponId}:${source.keywordId}`;\n  }\n}\n\n/**\n * Decompose each pipeline stage of `crunch(input)` into the marginal lift of\n * every toggleable buff group, via leave-one-out recompute.\n *\n * Cost is `groups + 2` `crunch` calls (full + baseline + one per group); the\n * engine is closed-form, so this is cheap to call per weapon line.\n *\n * @param input   The same {@link EngineInput} you'd pass to {@link crunch}.\n * @param dataset Optional dataset override (defaults to the embedded one).\n * @param opts    `epsilon` — lifts/residuals at or below this magnitude are\n *                treated as zero (default 1e-6).\n */\nexport function attributeStages(\n  input: EngineInput,\n  dataset?: Dataset,\n  opts?: { epsilon?: number },\n): AttributedStage[] {\n  const epsilon = opts?.epsilon ?? DEFAULT_EPSILON;\n  const full = crunch(input, dataset);\n\n  // First-seen order of groupable buff groups, with a representative source.\n  const order: string[] = [];\n  const repSource = new Map<string, BuffSource>();\n  for (const b of input.buffs) {\n    if (!isGroupable(b.source)) continue;\n    const key = groupKey(b.source);\n    if (!repSource.has(key)) {\n      repSource.set(key, b.source);\n      order.push(key);\n    }\n  }\n\n  // Baseline keeps only non-groupable buffs (weapon-keyword passthroughs) plus\n  // the engine's auto-injected intrinsics.\n  const baseline = crunch(\n    { ...input, buffs: input.buffs.filter((b) => !isGroupable(b.source)) },\n    dataset,\n  );\n\n  // Leave-one-out: drop one whole group, keep the rest.\n  const loo = new Map<string, EngineOutput>();\n  for (const key of order) {\n    const without = input.buffs.filter(\n      (b) => !isGroupable(b.source) || groupKey(b.source) !== key,\n    );\n    loo.set(key, crunch({ ...input, buffs: without }, dataset));\n  }\n\n  const intrinsics = full.resolved.extraKeywords.map((e) => e.keywordRef.keyword_id);\n\n  // crunch always emits the same seven stages in the same order, so index\n  // alignment across full / baseline / loo is sound.\n  return full.stages.map((s, i) => {\n    const expected = s.expected;\n    const baseExpected = baseline.stages[i].expected;\n    let totalLift = 0;\n    const lifts: StageLift[] = [];\n    for (const key of order) {\n      const delta = expected - loo.get(key)!.stages[i].expected;\n      totalLift += delta;\n      if (Math.abs(delta) > epsilon) {\n        lifts.push({ source: repSource.get(key)!, delta });\n      }\n    }\n    const residual = expected - baseExpected - totalLift;\n    return {\n      name: s.name,\n      expected,\n      detail: s.detail,\n      baseline: baseExpected,\n      lifts,\n      residual: Math.abs(residual) > epsilon ? residual : 0,\n      intrinsics,\n    };\n  });\n}\n"]}

package/dist/cruncher/buffs.d.ts

@@ -0,0 +1,206 @@
+/**
+ * The flat `Buff` type every contribution flows through, and the
+ * {@link resolveBuffs} resolver that collapses a stack into a
+ * {@link ResolvedModifiers} read-out the engine can consume.
+ *
+ * The same shape carries weapon-keyword effects, ability buffs, stratagem
+ * effects, and manual UI toggles — reroll-stacking, hit/wound caps, and
+ * feel-no-pain-best-threshold all fall out of one resolver rather than each
+ * source kind reinventing precedence.
+ *
+ * @packageDocumentation
+ */
+import type { Phase } from "../generated.js";
+/** Where a buff originated. Drives stable tie-breaking inside `resolveBuffs`. */
+export type BuffSource = {
+    kind: "weapon-keyword";
+    weaponId: string;
+    keywordId: string;
+} | {
+    kind: "ability";
+    abilityId: string;
+    abilityKind: "army" | "detachment" | "detachment-stratagem" | "unit" | "attached" | "support";
+    /**
+     * For `abilityKind: "attached"`, the combined-unit member the ability
+     * came from (so the UI can name it and show its leader/bodyguard role).
+     * Absent for other kinds.
+     */
+    sourceUnitId?: string;
+} | {
+    kind: "manual";
+    label: string;
+};
+/** A weapon-keyword reference (id + parameter map), as found on weapon profiles. */
+export type WeaponKeywordRef = {
+    keyword_id: string;
+    parameters?: Record<string, unknown>;
+};
+/** One typed contribution; the engine reads `ResolvedModifiers` for the rest. */
+export type BuffContribution = {
+    type: "hit-mod";
+    value: number;
+} | {
+    type: "wound-mod";
+    value: number;
+} | {
+    type: "save-mod";
+    value: number;
+} | {
+    type: "cover";
+} | {
+    type: "reroll";
+    roll: "hit" | "wound" | "save" | "damage";
+    subset: "ones" | "all-failures";
+} | {
+    type: "extra-keyword";
+    keywordRef: WeaponKeywordRef;
+} | {
+    type: "feel-no-pain";
+    threshold: number;
+} | {
+    type: "damage-mod";
+    value: number;
+}
+/** Additive modifier to the attacker's per-model attack count (A stat). */
+ | {
+    type: "attacks-mod";
+    value: number;
+}
+/** Additive modifier to the attacker's Strength stat. */
+ | {
+    type: "strength-mod";
+    value: number;
+}
+/** Additive modifier to the defender's Toughness stat. */
+ | {
+    type: "toughness-mod";
+    value: number;
+}
+/**
+ * Additive modifier to the attacker's weapon AP. AP is signed against the
+ * defender's save (negative = more piercing), so a value of `-1` here makes
+ * the weapon one AP more piercing.
+ */
+ | {
+    type: "ap-mod";
+    value: number;
+};
+/** Optional gating; the resolver drops buffs whose gate fails. */
+export type BuffApplicability = {
+    phases?: Phase[];
+    rollType?: "hit" | "wound" | "save" | "damage";
+    /** Target must carry this keyword (case-insensitive). */
+    requiresTargetKeyword?: string;
+    /** Attacker must carry this keyword (case-insensitive). */
+    requiresAttackerKeyword?: string;
+};
+/** A single buff: where it came from, when it applies, what it contributes. */
+export type Buff = {
+    source: BuffSource;
+    applicableWhen?: BuffApplicability;
+    contribution: BuffContribution;
+};
+/**
+ * Shared engine context. Carries the phase plus a few attacker/target flags
+ * the keyword translator and the resolver both need. The engine fills it from
+ * its `EngineInput.context` plus the unit-keyword unions; the resolver reads
+ * only the subset relevant to its `applicableWhen` checks.
+ */
+export type EngineContext = {
+    phase: Phase;
+    /** Attacker has not moved this turn — Heavy fires its +1 to hit. */
+    attackerStationary?: boolean;
+    /**
+     * Attacker made a charge move this turn — drives the `charged-this-turn`
+     * condition (e.g. World Eaters' Relentless Rage). Left undefined when the
+     * caller can't determine it — the condition then evaluates as `"unknown"` and
+     * the SPA surfaces a diagnostic (mirrors `attackerStationary` / `timing`).
+     */
+    attackerCharged?: boolean;
+    /** Within half the weapon's range — Melta / Rapid Fire fire. */
+    withinHalfRange?: boolean;
+    /** Attacker benefits from cover (mostly informational; cover applies to defenders). */
+    attackerInCover?: boolean;
+    /** Target is in cover — the resolver flips on `cover`, the engine applies +1 to save. */
+    targetInCover?: boolean;
+    /** Attacker keywords (union of unit.keywords + faction_keywords), lower-cased. */
+    attackerKeywords?: ReadonlyArray<string>;
+    /** Target keywords (union of unit.keywords + faction_keywords), lower-cased. */
+    targetKeywords?: ReadonlyArray<string>;
+    /**
+     * Sub-phase timing flag (e.g. `"start-of-phase"`, `"end-of-phase"`,
+     * `"on-destroyed"`). Consumed by the `timing-is` condition. Left undefined
+     * when the caller can't pin a sub-phase down — the condition then evaluates
+     * as `"unknown"` and the SPA surfaces a diagnostic.
+     */
+    timing?: string;
+    /**
+     * The buffed unit is part of a combined ("attached") unit — a leader is
+     * attached to a bodyguard, or vice-versa. Drives the `is-attached` and
+     * `model-is-leader` conditions. Derived from a non-empty
+     * `EligibilityInput.attachedUnitIds`. Left undefined when the caller can't
+     * determine attachment — the conditions then evaluate as `"unknown"` and the
+     * SPA surfaces a diagnostic (mirrors how `timing` undefined behaves).
+     */
+    attackerAttached?: boolean;
+};
+/** Back-compat alias — `resolveBuffs` accepts the shared engine context. */
+export type ResolveContext = EngineContext;
+/** Read-out of a resolved buff stack, with provenance per field. */
+export type ResolvedModifiers = {
+    hitMod: {
+        value: number;
+        dominantSource: BuffSource | null;
+    };
+    woundMod: {
+        value: number;
+        dominantSource: BuffSource | null;
+    };
+    saveMod: {
+        value: number;
+        sources: BuffSource[];
+    };
+    cover: {
+        active: boolean;
+        source: BuffSource | null;
+    };
+    rerolls: Partial<Record<"hit" | "wound" | "save" | "damage", {
+        subset: "ones" | "all-failures";
+        dominantSource: BuffSource;
+    }>>;
+    extraKeywords: {
+        keywordRef: WeaponKeywordRef;
+        source: BuffSource;
+    }[];
+    feelNoPain: {
+        threshold: number;
+        dominantSource: BuffSource;
+    } | null;
+    damageMod: {
+        value: number;
+        sources: BuffSource[];
+    };
+    attacksMod: {
+        value: number;
+        sources: BuffSource[];
+    };
+    strengthMod: {
+        value: number;
+        sources: BuffSource[];
+    };
+    toughnessMod: {
+        value: number;
+        sources: BuffSource[];
+    };
+    apMod: {
+        value: number;
+        sources: BuffSource[];
+    };
+};
+/**
+ * Collapse a flat buff stack into a {@link ResolvedModifiers} read-out. Pure
+ * function; the engine — and any UI that wants to render the resolved table
+ * before crunching — both go through this.
+ */
+export declare function resolveBuffs(buffs: Buff[], ctx: ResolveContext): ResolvedModifiers;
+//# sourceMappingURL=buffs.d.ts.map

package/dist/cruncher/buffs.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"buffs.d.ts","sourceRoot":"","sources":["../../src/cruncher/buffs.ts"],"names":[],"mappings":"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"}

package/dist/cruncher/buffs.js

@@ -0,0 +1,150 @@
+/** Stable ordering used to break ties when multiple buffs claim the same field. */
+const SOURCE_KIND_RANK = {
+    "ability:army": 0,
+    "ability:detachment": 1,
+    "ability:detachment-stratagem": 2,
+    "ability:unit": 3,
+    "ability:attached": 4,
+    "ability:support": 5,
+    manual: 6,
+    "weapon-keyword": 7,
+};
+function rank(s) {
+    if (s.kind === "ability")
+        return SOURCE_KIND_RANK[`ability:${s.abilityKind}`] ?? 99;
+    return SOURCE_KIND_RANK[s.kind] ?? 99;
+}
+function applies(buff, ctx) {
+    const w = buff.applicableWhen;
+    if (!w)
+        return true;
+    if (w.phases && w.phases.length > 0 && !w.phases.includes(ctx.phase))
+        return false;
+    if (w.rollType && buff.contribution.type === "reroll" && buff.contribution.roll !== w.rollType) {
+        return false;
+    }
+    if (w.requiresTargetKeyword) {
+        const target = ctx.targetKeywords ?? [];
+        if (!target.includes(w.requiresTargetKeyword.toLowerCase()))
+            return false;
+    }
+    if (w.requiresAttackerKeyword) {
+        const attacker = ctx.attackerKeywords ?? [];
+        if (!attacker.includes(w.requiresAttackerKeyword.toLowerCase()))
+            return false;
+    }
+    return true;
+}
+/**
+ * Collapse a flat buff stack into a {@link ResolvedModifiers} read-out. Pure
+ * function; the engine — and any UI that wants to render the resolved table
+ * before crunching — both go through this.
+ */
+export function resolveBuffs(buffs, ctx) {
+    const live = buffs.filter((b) => applies(b, ctx));
+    const out = {
+        hitMod: { value: 0, dominantSource: null },
+        woundMod: { value: 0, dominantSource: null },
+        saveMod: { value: 0, sources: [] },
+        cover: { active: false, source: null },
+        rerolls: {},
+        extraKeywords: [],
+        feelNoPain: null,
+        damageMod: { value: 0, sources: [] },
+        attacksMod: { value: 0, sources: [] },
+        strengthMod: { value: 0, sources: [] },
+        toughnessMod: { value: 0, sources: [] },
+        apMod: { value: 0, sources: [] },
+    };
+    // Hit / wound mods: sum, then cap at ±1, with dominant source picked from
+    // the contributors whose sign matches the surviving value.
+    const hitContribs = [];
+    const woundContribs = [];
+    for (const b of live) {
+        const c = b.contribution;
+        switch (c.type) {
+            case "hit-mod":
+                hitContribs.push({ value: c.value, source: b.source });
+                break;
+            case "wound-mod":
+                woundContribs.push({ value: c.value, source: b.source });
+                break;
+            case "save-mod":
+                out.saveMod.value += c.value;
+                out.saveMod.sources.push(b.source);
+                break;
+            case "cover":
+                if (!out.cover.active || rank(b.source) < rank(out.cover.source)) {
+                    out.cover = { active: true, source: b.source };
+                }
+                break;
+            case "reroll": {
+                const cur = out.rerolls[c.roll];
+                const incoming = c.subset;
+                if (!cur) {
+                    out.rerolls[c.roll] = { subset: incoming, dominantSource: b.source };
+                }
+                else {
+                    const incomingStronger = (incoming === "all-failures" && cur.subset === "ones") ||
+                        (incoming === cur.subset && rank(b.source) < rank(cur.dominantSource));
+                    if (incomingStronger) {
+                        out.rerolls[c.roll] = { subset: incoming, dominantSource: b.source };
+                    }
+                }
+                break;
+            }
+            case "extra-keyword": {
+                const key = `${c.keywordRef.keyword_id}::${JSON.stringify(c.keywordRef.parameters ?? {})}`;
+                if (!out.extraKeywords.some((e) => keyOf(e.keywordRef) === key)) {
+                    out.extraKeywords.push({ keywordRef: c.keywordRef, source: b.source });
+                }
+                break;
+            }
+            case "feel-no-pain":
+                if (out.feelNoPain === null || c.threshold < out.feelNoPain.threshold) {
+                    out.feelNoPain = { threshold: c.threshold, dominantSource: b.source };
+                }
+                break;
+            case "damage-mod":
+                out.damageMod.value += c.value;
+                out.damageMod.sources.push(b.source);
+                break;
+            case "attacks-mod":
+                out.attacksMod.value += c.value;
+                out.attacksMod.sources.push(b.source);
+                break;
+            case "strength-mod":
+                out.strengthMod.value += c.value;
+                out.strengthMod.sources.push(b.source);
+                break;
+            case "toughness-mod":
+                out.toughnessMod.value += c.value;
+                out.toughnessMod.sources.push(b.source);
+                break;
+            case "ap-mod":
+                out.apMod.value += c.value;
+                out.apMod.sources.push(b.source);
+                break;
+        }
+    }
+    out.hitMod = capModifier(hitContribs);
+    out.woundMod = capModifier(woundContribs);
+    return out;
+}
+function keyOf(ref) {
+    return `${ref.keyword_id}::${JSON.stringify(ref.parameters ?? {})}`;
+}
+/** Sum, clamp to ±1, then pick the dominant contributing source by rank. */
+function capModifier(contribs) {
+    if (contribs.length === 0)
+        return { value: 0, dominantSource: null };
+    const sum = contribs.reduce((a, c) => a + c.value, 0);
+    const capped = Math.max(-1, Math.min(1, sum));
+    if (capped === 0)
+        return { value: 0, dominantSource: null };
+    const sign = Math.sign(capped);
+    const matching = contribs.filter((c) => Math.sign(c.value) === sign);
+    matching.sort((a, b) => rank(a.source) - rank(b.source));
+    return { value: capped, dominantSource: matching[0]?.source ?? null };
+}
+//# sourceMappingURL=buffs.js.map

package/dist/cruncher/buffs.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"buffs.js","sourceRoot":"","sources":["../../src/cruncher/buffs.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * The flat `Buff` type every contribution flows through, and the\n * {@link resolveBuffs} resolver that collapses a stack into a\n * {@link ResolvedModifiers} read-out the engine can consume.\n *\n * The same shape carries weapon-keyword effects, ability buffs, stratagem\n * effects, and manual UI toggles — reroll-stacking, hit/wound caps, and\n * feel-no-pain-best-threshold all fall out of one resolver rather than each\n * source kind reinventing precedence.\n *\n * @packageDocumentation\n */\nimport type { Phase } from \"../generated.js\";\n\n/** Where a buff originated. Drives stable tie-breaking inside `resolveBuffs`. */\nexport type BuffSource =\n  | { kind: \"weapon-keyword\"; weaponId: string; keywordId: string }\n  | {\n      kind: \"ability\";\n      abilityId: string;\n      abilityKind:\n        | \"army\"\n        | \"detachment\"\n        | \"detachment-stratagem\"\n        | \"unit\"\n        | \"attached\"\n        | \"support\";\n      /**\n       * For `abilityKind: \"attached\"`, the combined-unit member the ability\n       * came from (so the UI can name it and show its leader/bodyguard role).\n       * Absent for other kinds.\n       */\n      sourceUnitId?: string;\n    }\n  | { kind: \"manual\"; label: string };\n\n/** A weapon-keyword reference (id + parameter map), as found on weapon profiles. */\nexport type WeaponKeywordRef = {\n  keyword_id: string;\n  parameters?: Record<string, unknown>;\n};\n\n/** One typed contribution; the engine reads `ResolvedModifiers` for the rest. */\nexport type BuffContribution =\n  | { type: \"hit-mod\"; value: number }\n  | { type: \"wound-mod\"; value: number }\n  | { type: \"save-mod\"; value: number }\n  | { type: \"cover\" }\n  | {\n      type: \"reroll\";\n      roll: \"hit\" | \"wound\" | \"save\" | \"damage\";\n      subset: \"ones\" | \"all-failures\";\n    }\n  | { type: \"extra-keyword\"; keywordRef: WeaponKeywordRef }\n  | { type: \"feel-no-pain\"; threshold: number }\n  | { type: \"damage-mod\"; value: number }\n  /** Additive modifier to the attacker's per-model attack count (A stat). */\n  | { type: \"attacks-mod\"; value: number }\n  /** Additive modifier to the attacker's Strength stat. */\n  | { type: \"strength-mod\"; value: number }\n  /** Additive modifier to the defender's Toughness stat. */\n  | { type: \"toughness-mod\"; value: number }\n  /**\n   * Additive modifier to the attacker's weapon AP. AP is signed against the\n   * defender's save (negative = more piercing), so a value of `-1` here makes\n   * the weapon one AP more piercing.\n   */\n  | { type: \"ap-mod\"; value: number };\n\n/** Optional gating; the resolver drops buffs whose gate fails. */\nexport type BuffApplicability = {\n  phases?: Phase[];\n  rollType?: \"hit\" | \"wound\" | \"save\" | \"damage\";\n  /** Target must carry this keyword (case-insensitive). */\n  requiresTargetKeyword?: string;\n  /** Attacker must carry this keyword (case-insensitive). */\n  requiresAttackerKeyword?: string;\n};\n\n/** A single buff: where it came from, when it applies, what it contributes. */\nexport type Buff = {\n  source: BuffSource;\n  applicableWhen?: BuffApplicability;\n  contribution: BuffContribution;\n};\n\n/**\n * Shared engine context. Carries the phase plus a few attacker/target flags\n * the keyword translator and the resolver both need. The engine fills it from\n * its `EngineInput.context` plus the unit-keyword unions; the resolver reads\n * only the subset relevant to its `applicableWhen` checks.\n */\nexport type EngineContext = {\n  phase: Phase;\n  /** Attacker has not moved this turn — Heavy fires its +1 to hit. */\n  attackerStationary?: boolean;\n  /**\n   * Attacker made a charge move this turn — drives the `charged-this-turn`\n   * condition (e.g. World Eaters' Relentless Rage). Left undefined when the\n   * caller can't determine it — the condition then evaluates as `\"unknown\"` and\n   * the SPA surfaces a diagnostic (mirrors `attackerStationary` / `timing`).\n   */\n  attackerCharged?: boolean;\n  /** Within half the weapon's range — Melta / Rapid Fire fire. */\n  withinHalfRange?: boolean;\n  /** Attacker benefits from cover (mostly informational; cover applies to defenders). */\n  attackerInCover?: boolean;\n  /** Target is in cover — the resolver flips on `cover`, the engine applies +1 to save. */\n  targetInCover?: boolean;\n  /** Attacker keywords (union of unit.keywords + faction_keywords), lower-cased. */\n  attackerKeywords?: ReadonlyArray<string>;\n  /** Target keywords (union of unit.keywords + faction_keywords), lower-cased. */\n  targetKeywords?: ReadonlyArray<string>;\n  /**\n   * Sub-phase timing flag (e.g. `\"start-of-phase\"`, `\"end-of-phase\"`,\n   * `\"on-destroyed\"`). Consumed by the `timing-is` condition. Left undefined\n   * when the caller can't pin a sub-phase down — the condition then evaluates\n   * as `\"unknown\"` and the SPA surfaces a diagnostic.\n   */\n  timing?: string;\n  /**\n   * The buffed unit is part of a combined (\"attached\") unit — a leader is\n   * attached to a bodyguard, or vice-versa. Drives the `is-attached` and\n   * `model-is-leader` conditions. Derived from a non-empty\n   * `EligibilityInput.attachedUnitIds`. Left undefined when the caller can't\n   * determine attachment — the conditions then evaluate as `\"unknown\"` and the\n   * SPA surfaces a diagnostic (mirrors how `timing` undefined behaves).\n   */\n  attackerAttached?: boolean;\n};\n\n/** Back-compat alias — `resolveBuffs` accepts the shared engine context. */\nexport type ResolveContext = EngineContext;\n\n/** Read-out of a resolved buff stack, with provenance per field. */\nexport type ResolvedModifiers = {\n  hitMod: { value: number; dominantSource: BuffSource | null };\n  woundMod: { value: number; dominantSource: BuffSource | null };\n  saveMod: { value: number; sources: BuffSource[] };\n  cover: { active: boolean; source: BuffSource | null };\n  rerolls: Partial<\n    Record<\n      \"hit\" | \"wound\" | \"save\" | \"damage\",\n      { subset: \"ones\" | \"all-failures\"; dominantSource: BuffSource }\n    >\n  >;\n  extraKeywords: { keywordRef: WeaponKeywordRef; source: BuffSource }[];\n  feelNoPain: { threshold: number; dominantSource: BuffSource } | null;\n  damageMod: { value: number; sources: BuffSource[] };\n  attacksMod: { value: number; sources: BuffSource[] };\n  strengthMod: { value: number; sources: BuffSource[] };\n  toughnessMod: { value: number; sources: BuffSource[] };\n  apMod: { value: number; sources: BuffSource[] };\n};\n\n/** Stable ordering used to break ties when multiple buffs claim the same field. */\nconst SOURCE_KIND_RANK: Record<string, number> = {\n  \"ability:army\": 0,\n  \"ability:detachment\": 1,\n  \"ability:detachment-stratagem\": 2,\n  \"ability:unit\": 3,\n  \"ability:attached\": 4,\n  \"ability:support\": 5,\n  manual: 6,\n  \"weapon-keyword\": 7,\n};\n\nfunction rank(s: BuffSource): number {\n  if (s.kind === \"ability\") return SOURCE_KIND_RANK[`ability:${s.abilityKind}`] ?? 99;\n  return SOURCE_KIND_RANK[s.kind] ?? 99;\n}\n\nfunction applies(buff: Buff, ctx: ResolveContext): boolean {\n  const w = buff.applicableWhen;\n  if (!w) return true;\n  if (w.phases && w.phases.length > 0 && !w.phases.includes(ctx.phase)) return false;\n  if (w.rollType && buff.contribution.type === \"reroll\" && buff.contribution.roll !== w.rollType) {\n    return false;\n  }\n  if (w.requiresTargetKeyword) {\n    const target = ctx.targetKeywords ?? [];\n    if (!target.includes(w.requiresTargetKeyword.toLowerCase())) return false;\n  }\n  if (w.requiresAttackerKeyword) {\n    const attacker = ctx.attackerKeywords ?? [];\n    if (!attacker.includes(w.requiresAttackerKeyword.toLowerCase())) return false;\n  }\n  return true;\n}\n\n/**\n * Collapse a flat buff stack into a {@link ResolvedModifiers} read-out. Pure\n * function; the engine — and any UI that wants to render the resolved table\n * before crunching — both go through this.\n */\nexport function resolveBuffs(buffs: Buff[], ctx: ResolveContext): ResolvedModifiers {\n  const live = buffs.filter((b) => applies(b, ctx));\n\n  const out: ResolvedModifiers = {\n    hitMod: { value: 0, dominantSource: null },\n    woundMod: { value: 0, dominantSource: null },\n    saveMod: { value: 0, sources: [] },\n    cover: { active: false, source: null },\n    rerolls: {},\n    extraKeywords: [],\n    feelNoPain: null,\n    damageMod: { value: 0, sources: [] },\n    attacksMod: { value: 0, sources: [] },\n    strengthMod: { value: 0, sources: [] },\n    toughnessMod: { value: 0, sources: [] },\n    apMod: { value: 0, sources: [] },\n  };\n\n  // Hit / wound mods: sum, then cap at ±1, with dominant source picked from\n  // the contributors whose sign matches the surviving value.\n  const hitContribs: { value: number; source: BuffSource }[] = [];\n  const woundContribs: { value: number; source: BuffSource }[] = [];\n\n  for (const b of live) {\n    const c = b.contribution;\n    switch (c.type) {\n      case \"hit-mod\":\n        hitContribs.push({ value: c.value, source: b.source });\n        break;\n      case \"wound-mod\":\n        woundContribs.push({ value: c.value, source: b.source });\n        break;\n      case \"save-mod\":\n        out.saveMod.value += c.value;\n        out.saveMod.sources.push(b.source);\n        break;\n      case \"cover\":\n        if (!out.cover.active || rank(b.source) < rank(out.cover.source!)) {\n          out.cover = { active: true, source: b.source };\n        }\n        break;\n      case \"reroll\": {\n        const cur = out.rerolls[c.roll];\n        const incoming = c.subset;\n        if (!cur) {\n          out.rerolls[c.roll] = { subset: incoming, dominantSource: b.source };\n        } else {\n          const incomingStronger =\n            (incoming === \"all-failures\" && cur.subset === \"ones\") ||\n            (incoming === cur.subset && rank(b.source) < rank(cur.dominantSource));\n          if (incomingStronger) {\n            out.rerolls[c.roll] = { subset: incoming, dominantSource: b.source };\n          }\n        }\n        break;\n      }\n      case \"extra-keyword\": {\n        const key = `${c.keywordRef.keyword_id}::${JSON.stringify(c.keywordRef.parameters ?? {})}`;\n        if (!out.extraKeywords.some((e) => keyOf(e.keywordRef) === key)) {\n          out.extraKeywords.push({ keywordRef: c.keywordRef, source: b.source });\n        }\n        break;\n      }\n      case \"feel-no-pain\":\n        if (out.feelNoPain === null || c.threshold < out.feelNoPain.threshold) {\n          out.feelNoPain = { threshold: c.threshold, dominantSource: b.source };\n        }\n        break;\n      case \"damage-mod\":\n        out.damageMod.value += c.value;\n        out.damageMod.sources.push(b.source);\n        break;\n      case \"attacks-mod\":\n        out.attacksMod.value += c.value;\n        out.attacksMod.sources.push(b.source);\n        break;\n      case \"strength-mod\":\n        out.strengthMod.value += c.value;\n        out.strengthMod.sources.push(b.source);\n        break;\n      case \"toughness-mod\":\n        out.toughnessMod.value += c.value;\n        out.toughnessMod.sources.push(b.source);\n        break;\n      case \"ap-mod\":\n        out.apMod.value += c.value;\n        out.apMod.sources.push(b.source);\n        break;\n    }\n  }\n\n  out.hitMod = capModifier(hitContribs);\n  out.woundMod = capModifier(woundContribs);\n\n  return out;\n}\n\nfunction keyOf(ref: WeaponKeywordRef): string {\n  return `${ref.keyword_id}::${JSON.stringify(ref.parameters ?? {})}`;\n}\n\n/** Sum, clamp to ±1, then pick the dominant contributing source by rank. */\nfunction capModifier(\n  contribs: { value: number; source: BuffSource }[],\n): { value: number; dominantSource: BuffSource | null } {\n  if (contribs.length === 0) return { value: 0, dominantSource: null };\n  const sum = contribs.reduce((a, c) => a + c.value, 0);\n  const capped = Math.max(-1, Math.min(1, sum));\n  if (capped === 0) return { value: 0, dominantSource: null };\n  const sign = Math.sign(capped);\n  const matching = contribs.filter((c) => Math.sign(c.value) === sign);\n  matching.sort((a, b) => rank(a.source) - rank(b.source));\n  return { value: capped, dominantSource: matching[0]?.source ?? null };\n}\n"]}

package/dist/cruncher/engine.d.ts

@@ -0,0 +1,50 @@
+/**
+ * The expected-value damage engine.
+ *
+ * Closed-form math over schema profiles + a flat {@link Buff} stack. No
+ * sampling, no I/O. Auto-injects every weapon-keyword on the attacker's
+ * profile as a buff (so callers don't have to enumerate intrinsics), then
+ * resolves the stack via {@link resolveBuffs}, then walks
+ * attacks → hits → wounds → unsaved → damage → after-fnp → models-killed.
+ *
+ * The dataset is required (and defaults to the embedded one) — without it
+ * the engine can't look up weapon-keyword effects.
+ */
+import type { Phase, Unit, Weapon } from "../generated.js";
+import { type Buff, type EngineContext, type ResolvedModifiers } from "./buffs.js";
+import { Dataset } from "../data/dataset.js";
+export type AttackProfileRef = {
+    weapon: Weapon;
+    profileIndex: number;
+};
+export type TargetProfileRef = {
+    unit: Unit;
+    profileIndex: number;
+    /** Override target model count (otherwise read from `unit.model_count.min`). */
+    modelCount?: number;
+};
+export type Stage = {
+    name: "attacks" | "hits" | "wounds" | "unsaved" | "damage" | "after-fnp" | "models-killed";
+    expected: number;
+    detail: string;
+};
+export type EngineInput = {
+    attacker: AttackProfileRef;
+    target: TargetProfileRef;
+    modelsFiring: number;
+    /** User / ability / manual buffs. Weapon-keyword buffs are auto-injected. */
+    buffs: Buff[];
+    context: EngineContext;
+};
+export type EngineOutput = {
+    stages: Stage[];
+    resolved: ResolvedModifiers;
+};
+/**
+ * Compute the expected per-stage projection for one (attacker, target, buffs)
+ * triple. The dataset defaults to the embedded one — pass an alternate when
+ * crunching against a different bundle (e.g. tests).
+ */
+export declare function crunch(input: EngineInput, dataset?: Dataset): EngineOutput;
+export type { Phase };
+//# sourceMappingURL=engine.d.ts.map

package/dist/cruncher/engine.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"engine.d.ts","sourceRoot":"","sources":["../../src/cruncher/engine.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AACH,OAAO,KAAK,EAAE,KAAK,EAAE,IAAI,EAAE,MAAM,EAAE,MAAM,iBAAiB,CAAC;AAC3D,OAAO,EACL,KAAK,IAAI,EACT,KAAK,aAAa,EAElB,KAAK,iBAAiB,EAEvB,MAAM,YAAY,CAAC;AACpB,OAAO,EAAE,OAAO,EAAE,MAAM,oBAAoB,CAAC;AAE7C,MAAM,MAAM,gBAAgB,GAAG;IAAE,MAAM,EAAE,MAAM,CAAC;IAAC,YAAY,EAAE,MAAM,CAAA;CAAE,CAAC;AACxE,MAAM,MAAM,gBAAgB,GAAG;IAC7B,IAAI,EAAE,IAAI,CAAC;IACX,YAAY,EAAE,MAAM,CAAC;IACrB,gFAAgF;IAChF,UAAU,CAAC,EAAE,MAAM,CAAC;CACrB,CAAC;AAEF,MAAM,MAAM,KAAK,GAAG;IAClB,IAAI,EAAE,SAAS,GAAG,MAAM,GAAG,QAAQ,GAAG,SAAS,GAAG,QAAQ,GAAG,WAAW,GAAG,eAAe,CAAC;IAC3F,QAAQ,EAAE,MAAM,CAAC;IACjB,MAAM,EAAE,MAAM,CAAC;CAChB,CAAC;AAEF,MAAM,MAAM,WAAW,GAAG;IACxB,QAAQ,EAAE,gBAAgB,CAAC;IAC3B,MAAM,EAAE,gBAAgB,CAAC;IACzB,YAAY,EAAE,MAAM,CAAC;IACrB,6EAA6E;IAC7E,KAAK,EAAE,IAAI,EAAE,CAAC;IACd,OAAO,EAAE,aAAa,CAAC;CACxB,CAAC;AAEF,MAAM,MAAM,YAAY,GAAG;IAAE,MAAM,EAAE,KAAK,EAAE,CAAC;IAAC,QAAQ,EAAE,iBAAiB,CAAA;CAAE,CAAC;AAE5E;;;;GAIG;AACH,wBAAgB,MAAM,CAAC,KAAK,EAAE,WAAW,EAAE,OAAO,CAAC,EAAE,OAAO,GAAG,YAAY,CA0L1E;AAgKD,YAAY,EAAE,KAAK,EAAE,CAAC"}