feat: expand ISAC content modeling

src/lib/calculations/mechanic.test.ts

@@ -19,6 +19,276 @@ const custom = (
   inputs,
 });
 
+describe('deterministic mechanic probabilities and assigned abilities', () => {
+  it('rolls outcome probability independently with a reproducible seed and preserves a refreshed window', () => {
+    const program: MechanicProgram = {
+      id: 'ammo-refill',
+      name: 'Ammo Refill',
+      pools: [
+        {
+          key: 'tactical-link-window',
+          label: 'Tactical Link window',
+          scope: 'agent',
+          initial: 0,
+          min: 0,
+          max: 1,
+          expiresAfterSeconds: 6,
+        },
+      ],
+      clauses: [
+        {
+          id: 'start-window',
+          when: 'signature_ability_deployed',
+          reducer: { kind: 'none' },
+          mutations: [{ kind: 'set', pool: 'tactical-link-window', value: 1 }],
+        },
+        {
+          id: 'refresh-window',
+          when: 'enemy_killed',
+          reducer: { kind: 'none' },
+          mutations: [{ kind: 'set', pool: 'tactical-link-window', value: 1 }],
+        },
+        {
+          id: 'recover-ammo',
+          when: 'shot_fired',
+          if: {
+            kind: 'compare',
+            left: { source: 'pool', pool: 'tactical-link-window' },
+            operator: 'eq',
+            right: 1,
+          },
+          reducer: { kind: 'none' },
+          mutations: [],
+          outcomes: [
+            {
+              id: 'recover-one-ammo',
+              label: 'Recover one ammo',
+              phase: 'after_event',
+              kind: 'restoration',
+              scope: 'self',
+              basis: 'flat',
+              resource: 'ammo',
+              value: 1,
+              probabilityPercent: 29,
+            },
+          ],
+        },
+      ],
+    };
+    const events = [
+      {
+        kind: 'signature_ability_deployed' as const,
+        at: 0,
+        values: { assignedAbilityDurationSeconds: 6 },
+      },
+      { kind: 'shot_fired' as const, at: 1 },
+      { kind: 'shot_fired' as const, at: 2 },
+      { kind: 'enemy_killed' as const, at: 5 },
+      { kind: 'shot_fired' as const, at: 6 },
+      { kind: 'shot_fired' as const, at: 11 },
+    ];
+    const first = evaluateMechanicProgram(
+      program,
+      events,
+      { mode: 'custom', encounterSeconds: 12, randomSeed: 1 },
+      { maxHealth: 100, currentHealth: 100, maxAmmo: 20, currentAmmo: 5 },
+    );
+    const second = evaluateMechanicProgram(
+      program,
+      events,
+      { mode: 'custom', encounterSeconds: 12, randomSeed: 1 },
+      { maxHealth: 100, currentHealth: 100, maxAmmo: 20, currentAmmo: 5 },
+    );
+
+    expect(first.status).toBe('OK');
+    expect(first.randomSeed).toBe(1);
+    expect(first.outcomes.map((outcome) => outcome.at)).toEqual([2]);
+    expect(first.outcomes[0]).toMatchObject({
+      probabilityPercent: 29,
+      probabilityRoll: expect.any(Number),
+      appliedValue: 1,
+    });
+    expect(first.finalCombat?.currentAmmo).toBe(6);
+    expect(second.outcomes).toEqual(first.outcomes);
+  });
+
+  it('gates a proc before mutations, extends a live assigned ability, and starts cooldown on the eighth stack', () => {
+    const program: MechanicProgram = {
+      id: 'tactical-loop',
+      name: 'Tactical Loop',
+      pools: [
+        {
+          key: 'extension-stacks',
+          label: 'Extension stacks',
+          scope: 'agent',
+          initial: 7,
+          min: 0,
+          max: 8,
+        },
+        {
+          key: 'extension-cooldown',
+          label: 'Extension cooldown',
+          scope: 'agent',
+          initial: 0,
+          min: 0,
+          max: 1,
+          expiresAfterSeconds: 15,
+        },
+      ],
+      clauses: [
+        {
+          id: 'extend-tactical-link',
+          when: 'skill_hit',
+          if: {
+            kind: 'compare',
+            left: { source: 'pool', pool: 'extension-cooldown' },
+            operator: 'eq',
+            right: 0,
+          },
+          requiresAssignedAbilityActive: true,
+          procChancePercent: 10,
+          reducer: { kind: 'none' },
+          mutations: [
+            { kind: 'add', pool: 'extension-stacks', value: 1 },
+            {
+              kind: 'extend_duration',
+              target: 'assigned_ability',
+              seconds: 0.3,
+            },
+            {
+              kind: 'start_cooldown_on_max',
+              stackPool: 'extension-stacks',
+              cooldownPool: 'extension-cooldown',
+            },
+          ],
+        },
+      ],
+    };
+    const success = evaluateMechanicProgram(
+      program,
+      [
+        {
+          kind: 'signature_ability_deployed',
+          at: 0,
+          values: { assignedAbilityDurationSeconds: 6 },
+        },
+        { kind: 'skill_hit', at: 5.9 },
+        { kind: 'skill_hit', at: 6.1 },
+      ],
+      { mode: 'custom', encounterSeconds: 7, randomSeed: 7 },
+    );
+    const failed = evaluateMechanicProgram(
+      program,
+      [
+        {
+          kind: 'signature_ability_deployed',
+          at: 0,
+          values: { assignedAbilityDurationSeconds: 6 },
+        },
+        { kind: 'skill_hit', at: 5.9 },
+      ],
+      { mode: 'custom', encounterSeconds: 7, randomSeed: 1 },
+    );
+
+    expect(success.status).toBe('OK');
+    expect(success.emissions).toHaveLength(1);
+    const extension = success.emissions[0].mutations.find(
+      (mutation) => mutation.kind === 'extend_duration',
+    );
+    expect(extension).toMatchObject({ kind: 'extend_duration' });
+    expect(extension?.before).toBeCloseTo(0.1);
+    expect(extension?.after).toBeCloseTo(0.4);
+    expect(success.emissions[0].mutations).toEqual(
+      expect.arrayContaining([
+        expect.objectContaining({
+          kind: 'start_cooldown_on_max',
+          pool: 'extension-cooldown',
+          after: 1,
+        }),
+      ]),
+    );
+    expect(success.finalState).toEqual(
+      expect.arrayContaining([
+        expect.objectContaining({
+          pool: 'extension-stacks',
+          value: 8,
+        }),
+        expect.objectContaining({
+          pool: 'extension-cooldown',
+          value: 1,
+          expiresAt: 20.9,
+        }),
+      ]),
+    );
+    expect(failed.emissions).toEqual([]);
+  });
+
+  it('does not extend an assigned ability at its exact expiry and rejects invalid chance data', () => {
+    const boundaryProgram: MechanicProgram = {
+      id: 'exact-expiry',
+      name: 'Exact expiry',
+      clauses: [
+        {
+          id: 'extend',
+          when: 'skill_hit',
+          requiresAssignedAbilityActive: true,
+          procChancePercent: 100,
+          reducer: { kind: 'none' },
+          mutations: [
+            {
+              kind: 'extend_duration',
+              target: 'assigned_ability',
+              seconds: 0.3,
+            },
+          ],
+        },
+      ],
+    };
+    expect(
+      evaluateMechanicProgram(
+        boundaryProgram,
+        [
+          {
+            kind: 'signature_ability_deployed',
+            at: 0,
+            values: { assignedAbilityDurationSeconds: 1 },
+          },
+          { kind: 'skill_hit', at: 1 },
+        ],
+        { mode: 'custom', encounterSeconds: 2, randomSeed: 7 },
+      ).emissions,
+    ).toEqual([]);
+
+    const invalid = structuredClone(boundaryProgram);
+    invalid.clauses[0].procChancePercent = 101;
+    expect(validateMechanicProgram(invalid)).toMatchObject({
+      ok: false,
+      errors: [
+        expect.stringContaining('proc chance must be from 0 through 100'),
+      ],
+    });
+    const invalidOutcome = structuredClone(boundaryProgram);
+    invalidOutcome.clauses[0].outcomes = [
+      {
+        id: 'bad-chance',
+        label: 'Bad chance',
+        phase: 'after_event',
+        kind: 'marker',
+        scope: 'self',
+        basis: 'flat',
+        value: 1,
+        probabilityPercent: -1,
+      },
+    ];
+    expect(validateMechanicProgram(invalidOutcome)).toMatchObject({
+      ok: false,
+      errors: [
+        expect.stringContaining('probability must be from 0 through 100'),
+      ],
+    });
+  });
+});
+
 describe('structured mechanic runtime', () => {
   it('advertises the authoritative weapon-hit target and headshot fields', () => {
     expect(MECHANIC_EVENT_REGISTRY.weapon_hit).toMatchObject({
@@ -32,6 +302,11 @@ describe('structured mechanic runtime', () => {
         },
         { path: 'values.headshot', label: 'Headshot', type: 'boolean' },
         { path: 'values.critical', label: 'Critical hit', type: 'boolean' },
+        {
+          path: 'values.aiming',
+          label: 'Aiming down sights',
+          type: 'boolean',
+        },
         {
           path: 'values.behindCover',
           label: 'Agent behind cover',
@@ -305,6 +580,161 @@ describe('structured mechanic runtime', () => {
     });
   });
 
+  it('matches kills and assists only while the assigned ability is active', () => {
+    const weaponCriticalHitChance = 'weapon-critical-hit-chance';
+    const activeOutcome = {
+      id: 'tactical-link-critical-chance',
+      label: 'Weapon Critical Hit Chance',
+      phase: 'while_active' as const,
+      kind: 'attribute_modifier' as const,
+      scope: 'self' as const,
+      basis: 'flat' as const,
+      value: 10.2,
+      attributeId: weaponCriticalHitChance,
+      statePool: 'tactical-link-kill-bonus',
+    };
+    const activePredicate = {
+      kind: 'compare' as const,
+      left: {
+        source: 'event' as const,
+        path: 'values.assignedAbilityActive',
+      },
+      operator: 'eq' as const,
+      right: true,
+    };
+    const program: MechanicProgram = {
+      id: 'tactical-link-kill-bonus',
+      name: 'Tactical Link Kill Bonus',
+      pools: [
+        {
+          key: 'tactical-link-kill-bonus',
+          label: 'Tactical Link kill bonus',
+          scope: 'agent',
+          initial: 0,
+          min: 0,
+          max: 1,
+          expiresAfterSeconds: 10,
+        },
+      ],
+      clauses: [
+        {
+          id: 'kill-during-tactical-link',
+          when: 'enemy_killed',
+          if: activePredicate,
+          reducer: { kind: 'none' },
+          mutations: [
+            { kind: 'set', pool: 'tactical-link-kill-bonus', value: 1 },
+          ],
+          outcomes: [activeOutcome],
+        },
+        {
+          id: 'assist-during-tactical-link',
+          when: 'assist',
+          if: activePredicate,
+          reducer: { kind: 'none' },
+          mutations: [
+            { kind: 'set', pool: 'tactical-link-kill-bonus', value: 1 },
+          ],
+          outcomes: [{ ...activeOutcome }],
+        },
+      ],
+    };
+
+    expect(validateMechanicProgram(program)).toMatchObject({ ok: true });
+    const result = evaluateMechanicProgram(
+      program,
+      [
+        {
+          kind: 'enemy_killed',
+          at: 0,
+          values: { assignedAbilityActive: true },
+        },
+        {
+          kind: 'assist',
+          at: 4,
+          values: { assignedAbilityActive: false },
+        },
+        { kind: 'enemy_killed', at: 6 },
+        {
+          kind: 'assist',
+          at: 10,
+          values: { assignedAbilityActive: true },
+        },
+      ],
+      custom(19),
+      {
+        maxHealth: 1_000,
+        currentHealth: 1_000,
+        attributes: { [weaponCriticalHitChance]: 0 },
+      },
+    );
+
+    expect(result.status).toBe('OK');
+    expect(result.outcomes.map((outcome) => outcome.at)).toEqual([0, 10]);
+    expect(result.finalState).toContainEqual(
+      expect.objectContaining({
+        pool: 'tactical-link-kill-bonus',
+        value: 1,
+        expiresAt: 20,
+      }),
+    );
+  });
+
+  it('rejects invalid assigned-ability activity predicates and event values', () => {
+    const program: MechanicProgram = {
+      id: 'assigned-ability-activity',
+      name: 'Assigned ability activity',
+      clauses: [
+        {
+          id: 'kill',
+          when: 'enemy_killed',
+          if: {
+            kind: 'compare',
+            left: {
+              source: 'event',
+              path: 'values.assignedAbilityActive',
+            },
+            operator: 'eq',
+            right: true,
+          },
+          reducer: { kind: 'none' },
+          mutations: [],
+        },
+      ],
+    };
+    const invalidPredicate = structuredClone(program);
+    invalidPredicate.clauses[0].if = {
+      kind: 'compare',
+      left: { source: 'event', path: 'values.assignedAbilityActive' },
+      operator: 'eq',
+      right: 'yes',
+    };
+    expect(validateMechanicProgram(invalidPredicate)).toMatchObject({
+      ok: false,
+      errors: [
+        expect.stringContaining('Assigned ability active with a boolean value'),
+      ],
+    });
+    expect(
+      evaluateMechanicProgram(
+        program,
+        [
+          {
+            kind: 'enemy_killed',
+            at: 0,
+            values: { assignedAbilityActive: 'yes' },
+          } as unknown as MechanicEvent,
+        ],
+        custom(1),
+      ),
+    ).toMatchObject({
+      status: 'INVALID',
+      errors: [
+        expect.stringContaining('Assigned ability active must be a boolean'),
+      ],
+    });
+  });
+
   it('executes imported talent trigger families as first-class events', () => {
     const eventKinds: MechanicEventKind[] = [
       'ally_downed',
@@ -2550,4 +2980,251 @@ describe('mechanic validation and pseudo-script', () => {
     expect(result.script).toContain('TO ALLIES WITHIN 40m');
     expect(result.script).toContain('TO ENEMIES WITHIN 20m');
   });
+
+  it('applies aimed critical-hit area damage once to each valid enemy at or inside the radius', () => {
+    const program: MechanicProgram = {
+      id: 'aimed-critical-explosion',
+      name: 'Aimed Critical Explosion',
+      clauses: [
+        {
+          id: 'aimed-critical-hit',
+          when: 'weapon_hit',
+          if: {
+            kind: 'all',
+            predicates: [
+              {
+                kind: 'compare',
+                left: { source: 'event', path: 'values.critical' },
+                operator: 'eq',
+                right: true,
+              },
+              {
+                kind: 'compare',
+                left: { source: 'event', path: 'values.aiming' },
+                operator: 'eq',
+                right: true,
+              },
+            ],
+          },
+          reducer: { kind: 'none' },
+          mutations: [],
+          outcomes: [
+            {
+              id: 'explosion',
+              label: 'Explosion',
+              phase: 'after_event',
+              kind: 'direct_damage',
+              scope: 'target',
+              basis: 'flat',
+              value: {
+                op: 'multiply',
+                left: 20,
+                right: {
+                  ref: { source: 'attribute', attributeId: 'firepower' },
+                },
+              },
+              targeting: {
+                kind: 'event_target_area',
+                center: 'event_target',
+                validTargets: 'enemies',
+                radiusMeters: 5,
+              },
+              probabilityPercent: 100,
+            },
+          ],
+        },
+      ],
+    };
+    const result = evaluateMechanicProgram(
+      program,
+      [
+        {
+          kind: 'weapon_hit',
+          at: 1,
+          targetId: 'enemy-b',
+          values: { critical: true, aiming: true },
+          areaTargetSample: {
+            center: 'event_target',
+            validTargets: [
+              {
+                entityId: 'enemy-c',
+                population: 'enemy',
+                distanceMeters: 5.001,
+              },
+              { entityId: 'enemy-b', population: 'enemy', distanceMeters: 0 },
+              { entityId: 'ally-a', population: 'ally', distanceMeters: 2 },
+              { entityId: 'enemy-a', population: 'enemy', distanceMeters: 5 },
+            ],
+          },
+        },
+      ],
+      custom(5),
+      { maxHealth: 1000, currentHealth: 1000, attributes: { firepower: 100 } },
+    );
+
+    expect(result.status).toBe('OK');
+    expect(result.outcomes.map((outcome) => outcome.targetId)).toEqual([
+      'enemy-a',
+      'enemy-b',
+    ]);
+    expect(result.outcomes.map((outcome) => outcome.appliedValue)).toEqual([
+      2000, 2000,
+    ]);
+    expect(
+      new Set(result.outcomes.map((outcome) => outcome.probabilityRoll)).size,
+    ).toBe(1);
+    expect(result.outcomes[0].probabilityRoll).not.toBeNull();
+    expect(result.script).toContain(
+      'EXPLOSION CENTERED ON EVENT TARGET; APPLY TO VALID ENEMIES WITHIN 5m',
+    );
+    const maximum = evaluateMechanicProgram(
+      program,
+      [
+        {
+          kind: 'weapon_hit',
+          at: 1,
+          targetId: 'enemy-b',
+          values: { critical: true, aiming: true },
+          areaTargetSample: {
+            center: 'event_target',
+            validTargets: [
+              { entityId: 'enemy-b', population: 'enemy', distanceMeters: 0 },
+              { entityId: 'enemy-a', population: 'enemy', distanceMeters: 5 },
+            ],
+          },
+        },
+      ],
+      { mode: 'maximum', encounterSeconds: 5 },
+      { maxHealth: 1000, currentHealth: 1000, attributes: { firepower: 100 } },
+    );
+    expect(maximum.outcomes.map((outcome) => outcome.targetId)).toEqual([
+      'enemy-a',
+      'enemy-b',
+    ]);
+    expect(
+      maximum.outcomes.every((outcome) => outcome.probabilityRoll === 0),
+    ).toBe(true);
+  });
+
+  it('requires authoritative area evidence only when an area outcome activates', () => {
+    const program: MechanicProgram = {
+      id: 'area-evidence',
+      name: 'Area Evidence',
+      clauses: [
+        {
+          id: 'critical-hit',
+          when: 'weapon_hit',
+          if: {
+            kind: 'compare',
+            left: { source: 'event', path: 'values.critical' },
+            operator: 'eq',
+            right: true,
+          },
+          reducer: { kind: 'none' },
+          mutations: [],
+          outcomes: [
+            {
+              id: 'explosion',
+              label: 'Explosion',
+              phase: 'after_event',
+              kind: 'direct_damage',
+              scope: 'target',
+              basis: 'flat',
+              value: 1,
+              targeting: {
+                kind: 'event_target_area',
+                center: 'event_target',
+                validTargets: 'enemies',
+                radiusMeters: 5,
+              },
+            },
+          ],
+        },
+      ],
+    };
+    expect(
+      evaluateMechanicProgram(
+        program,
+        [
+          {
+            kind: 'weapon_hit',
+            at: 1,
+            targetId: 'enemy',
+            values: { critical: false },
+          },
+        ],
+        custom(5),
+      ),
+    ).toMatchObject({ status: 'OK', outcomes: [] });
+    expect(
+      evaluateMechanicProgram(
+        program,
+        [
+          {
+            kind: 'weapon_hit',
+            at: 1,
+            targetId: 'enemy',
+            values: { critical: true },
+          },
+        ],
+        custom(5),
+      ),
+    ).toMatchObject({
+      status: 'INVALID',
+      errors: [
+        expect.stringContaining('authoritative event-target area sample'),
+      ],
+    });
+  });
+
+  it('rejects malformed and duplicate area-target samples', () => {
+    const result = evaluateMechanicProgram(
+      { id: 'sample-validation', name: 'Sample Validation', clauses: [] },
+      [
+        {
+          kind: 'weapon_hit',
+          at: 1,
+          targetId: 'enemy',
+          areaTargetSample: {
+            center: 'event_target',
+            validTargets: [
+              { entityId: 'enemy', population: 'enemy', distanceMeters: 0 },
+              { entityId: 'enemy', population: 'enemy', distanceMeters: 1 },
+            ],
+          },
+        },
+      ],
+      custom(5),
+    );
+    expect(result).toMatchObject({
+      status: 'INVALID',
+      errors: [expect.stringContaining('duplicates entity "enemy"')],
+    });
+
+    const oversizedTargets = Array.from({ length: 257 }, (_, index) => ({
+      entityId: index === 0 ? 'enemy' : `enemy-${index}`,
+      population: 'enemy' as const,
+      distanceMeters: index === 0 ? 0 : 1,
+    }));
+    expect(
+      evaluateMechanicProgram(
+        { id: 'sample-bound', name: 'Sample Bound', clauses: [] },
+        [
+          {
+            kind: 'weapon_hit',
+            at: 1,
+            targetId: 'enemy',
+            areaTargetSample: {
+              center: 'event_target',
+              validTargets: oversizedTargets,
+            },
+          },
+        ],
+        custom(5),
+      ),
+    ).toMatchObject({
+      status: 'INVALID',
+      errors: [expect.stringContaining('cannot contain more than 256')],
+    });
+  });
 });