@sensigo/realm-testing 0.33.0 → 0.34.0

package/dist/store/settlement-contract.js

@@ -88,6 +88,9 @@ function makePendingGate(stepName, opts) {
         preview: {},
         choices: opts?.choices ?? ['approve', 'reject'],
         opened_at: '2026-01-01T00:00:00.000Z',
+        ...(opts?.expiresAt !== undefined ? { expires_at: opts.expiresAt } : {}),
+        ...(opts?.onExpiry !== undefined ? { on_expiry: opts.onExpiry } : {}),
+        ...(opts?.defaultChoice !== undefined ? { default_choice: opts.defaultChoice } : {}),
     };
 }
 function makeEvidence(stepId, overrides = {}) {
@@ -2444,6 +2447,771 @@ function phaseIsGeneratedCases(adapter) {
     ];
 }
 // ---------------------------------------------------------------------------
+// issue #302 (finalizer outcome×trigger matrix) — completed_with_failed_steps laws.
+// ---------------------------------------------------------------------------
+/** CWFS_FIRES_PER_ARM — mixed-complete mints the declared completed_with_failed_steps finalizer,
+ *  discriminated per settlement ARM (S3): VIA settle_step, VIA settle_gate resolution, VIA
+ *  settle_guard pass. Each case independently fails a step FIRST (claimed, then settled), THEN
+ *  drives the arm under test as the run's LAST remaining piece — so failed_steps is non-empty at
+ *  the moment that arm's own settle terminalizes the run to 'complete'. */
+function cwfsFiresPerArmCases(adapter) {
+    const fixture = adapter.settlementFixture;
+    const { minimalDefinition, withFinalizer } = fixture;
+    const settleStep = requireSettleStep(adapter.store);
+    const cases = [
+        {
+            law: 'CWFS_FIRES_PER_ARM',
+            name: `[${adapter.storeName}] mixed-complete VIA settle_step mints the declared completed_with_failed_steps finalizer`,
+            run: async () => {
+                const def = withFinalizer(minimalDefinition(['fail_step', 'complete_step']), 'fin', 'completed_with_failed_steps');
+                const { run, token: failToken } = await createClaimed(adapter.store, def, 'fail_step');
+                const claimedComplete = await adapter.store.claimStep(run.id, 'complete_step', def);
+                const completeToken = claimedComplete.claims['complete_step'].token;
+                const failed = await settleStep(run.id, {
+                    kind: 'settle_step',
+                    step: 'fail_step',
+                    outcome: 'fail',
+                    claimToken: failToken,
+                    evidence: [],
+                    failureMessage: 'x',
+                }, def);
+                assertApplied(failed, 'fail fail_step');
+                if (failed.run.terminal_state) {
+                    throw new Error('fixture setup: run must NOT terminalize while complete_step is still claimed');
+                }
+                const completed = await settleStep(run.id, {
+                    kind: 'settle_step',
+                    step: 'complete_step',
+                    outcome: 'complete',
+                    claimToken: completeToken,
+                    evidence: [makeEvidence('complete_step')],
+                }, def);
+                assertApplied(completed, 'complete complete_step (terminalizes mixed-complete)');
+                if (completed.run.finalizer_ledger?.['fin']?.status !== 'pending') {
+                    throw new Error(`expected 'fin' minted pending on the settle_step-driven mixed-complete seal, got: ${JSON.stringify(completed.run.finalizer_ledger)}`);
+                }
+            },
+        },
+        {
+            law: 'CWFS_FIRES_PER_ARM',
+            name: `[${adapter.storeName}] mixed-complete VIA settle_gate resolution mints the declared completed_with_failed_steps finalizer`,
+            run: async () => {
+                const def = withFinalizer(minimalDefinition(['fail_step', 'gated_step']), 'fin', 'completed_with_failed_steps');
+                // PR-C ordering rule: claim BOTH steps before any gate opens — once a gate is open,
+                // findEligibleSteps returns [] globally, so a fresh claim for 'gated_step' after opening a
+                // gate on it would be the wrong sequencing (this claims first, opens second).
+                const { run, token: failToken } = await createClaimed(adapter.store, def, 'fail_step');
+                const claimedGated = await adapter.store.claimStep(run.id, 'gated_step', def);
+                const gatedToken = claimedGated.claims['gated_step'].token;
+                const failed = await settleStep(run.id, {
+                    kind: 'settle_step',
+                    step: 'fail_step',
+                    outcome: 'fail',
+                    claimToken: failToken,
+                    evidence: [],
+                    failureMessage: 'x',
+                }, def);
+                assertApplied(failed, 'fail fail_step');
+                const gate = makePendingGate('gated_step');
+                const opened = await settleStep(run.id, {
+                    kind: 'open_gate',
+                    step: 'gated_step',
+                    claimToken: gatedToken,
+                    pendingGate: gate,
+                    evidence: [],
+                }, def);
+                assertApplied(opened, 'open_gate on gated_step');
+                if (opened.run.terminal_state) {
+                    throw new Error('fixture setup: run must not be terminal merely from opening the gate');
+                }
+                const resolved = await settleStep(run.id, { kind: 'settle_gate', gateId: gate.gate_id, choice: 'approve', evidence: [] }, def);
+                assertApplied(resolved, 'settle_gate resolve (terminalizes mixed-complete)');
+                if (resolved.run.finalizer_ledger?.['fin']?.status !== 'pending') {
+                    throw new Error(`expected 'fin' minted pending on the settle_gate-driven mixed-complete seal, got: ${JSON.stringify(resolved.run.finalizer_ledger)}`);
+                }
+            },
+        },
+    ];
+    if (fixture.withGuard === undefined) {
+        cases.push({
+            law: 'ADAPTER_WIRING',
+            name: `[${adapter.storeName}] declares RunStore.settleStep but the supplied settlementFixture has no withGuard — CWFS_FIRES_PER_ARM's guard leg is a WIRING GAP, not a vacuous pass`,
+            run: async () => {
+                throw new Error(`[${adapter.storeName}] settlementContract: adapter.settlementFixture.withGuard is ` +
+                    "undefined — pass 'defaultSettlementFixture' (or a store-specific fixture " +
+                    'implementing withGuard) to exercise the CWFS_FIRES_PER_ARM guard-leg coverage.');
+            },
+        });
+    }
+    else {
+        const withGuard = fixture.withGuard;
+        cases.push({
+            law: 'CWFS_FIRES_PER_ARM',
+            name: `[${adapter.storeName}] mixed-complete VIA settle_guard pass mints the declared completed_with_failed_steps finalizer`,
+            run: async () => {
+                const def = withFinalizer(withGuard(minimalDefinition(['fail_step']), 'g', []), // empty abort_unless ⇒ always passes
+                'fin', 'completed_with_failed_steps');
+                const { run, token: failToken } = await createClaimed(adapter.store, def, 'fail_step');
+                const failed = await settleStep(run.id, {
+                    kind: 'settle_step',
+                    step: 'fail_step',
+                    outcome: 'fail',
+                    claimToken: failToken,
+                    evidence: [],
+                    failureMessage: 'x',
+                }, def);
+                assertApplied(failed, 'fail fail_step');
+                if (failed.run.terminal_state) {
+                    throw new Error("fixture setup: run must NOT terminalize while guard 'g' is still eligible");
+                }
+                const passed = await settleStep(run.id, { kind: 'settle_guard', step: 'g', outcome: 'pass', evidence: makeEvidence('g') }, def);
+                assertApplied(passed, 'settle_guard pass (terminalizes mixed-complete)');
+                if (passed.run.finalizer_ledger?.['fin']?.status !== 'pending') {
+                    throw new Error(`expected 'fin' minted pending on the settle_guard-driven mixed-complete seal, got: ${JSON.stringify(passed.run.finalizer_ledger)}`);
+                }
+            },
+        });
+    }
+    return cases;
+}
+/** CWFS_NEGATIVES — the new trigger never over-fires: a clean complete (no failed_steps) does not
+ *  select it; a pure fail seal (never reaches complete) does not select it either. */
+function cwfsNegativesCases(adapter) {
+    const { minimalDefinition, withFinalizer } = adapter.settlementFixture;
+    const settleStep = requireSettleStep(adapter.store);
+    return [
+        {
+            law: 'CWFS_NEGATIVES',
+            name: `[${adapter.storeName}] a CLEAN complete seal (no failed_steps) does NOT select completed_with_failed_steps`,
+            run: async () => {
+                const def = withFinalizer(minimalDefinition(['a']), 'fin', 'completed_with_failed_steps');
+                const { run, token } = await createClaimed(adapter.store, def, 'a');
+                const completed = await settleStep(run.id, {
+                    kind: 'settle_step',
+                    step: 'a',
+                    outcome: 'complete',
+                    claimToken: token,
+                    evidence: [makeEvidence('a')],
+                }, def);
+                assertApplied(completed, 'clean complete of a');
+                if (completed.run.finalizer_ledger?.['fin'] !== undefined) {
+                    throw new Error(`expected 'fin' NOT selected on a clean complete seal, got: ${JSON.stringify(completed.run.finalizer_ledger)}`);
+                }
+            },
+        },
+        {
+            law: 'CWFS_NEGATIVES',
+            name: `[${adapter.storeName}] a PURE fail seal does NOT select completed_with_failed_steps (it requires a complete seal, never a fail seal)`,
+            run: async () => {
+                const def = withFinalizer(minimalDefinition(['a']), 'fin', 'completed_with_failed_steps');
+                const { run, token } = await createClaimed(adapter.store, def, 'a');
+                const failed = await settleStep(run.id, {
+                    kind: 'settle_step',
+                    step: 'a',
+                    outcome: 'fail',
+                    claimToken: token,
+                    evidence: [],
+                    failureMessage: 'x',
+                }, def);
+                assertApplied(failed, 'pure fail of a');
+                if (failed.run.finalizer_ledger?.['fin'] !== undefined) {
+                    throw new Error(`expected 'fin' NOT selected on a pure fail seal, got: ${JSON.stringify(failed.run.finalizer_ledger)}`);
+                }
+            },
+        },
+    ];
+}
+/** CWFS_SECOND_EPOCH — the M1 uniform-predicate pin: a second-epoch complete seal whose ONLY
+ *  failed_steps scar is a PRIOR epoch's finalizer self-failure (unresumable, so it never leaves
+ *  failed_steps) still fires completed_with_failed_steps. The post-resume state is HAND-AUTHORED
+ *  via update() (the mintFreshCases/L14 precedent) — this TCK case does not drive real
+ *  applyResume; a core-homed witness through the REAL applyResume lives in core's own test suite
+ *  (finalizer-matrix-302.test.ts), per the hand-off prompt's "Core tests" bullet. */
+function cwfsSecondEpochCases(adapter) {
+    const { minimalDefinition, withFinalizer } = adapter.settlementFixture;
+    const settleStep = requireSettleStep(adapter.store);
+    return [
+        {
+            law: 'CWFS_SECOND_EPOCH',
+            name: `[${adapter.storeName}] a second-epoch complete seal driven SOLELY by a prior epoch's finalizer self-failure still fires completed_with_failed_steps`,
+            run: async () => {
+                const def = withFinalizer(withFinalizer(minimalDefinition(['a']), 'onFail', 'fail'), 'fin', 'completed_with_failed_steps');
+                const { run, token } = await createClaimed(adapter.store, def, 'a');
+                const failedA = await settleStep(run.id, {
+                    kind: 'settle_step',
+                    step: 'a',
+                    outcome: 'fail',
+                    claimToken: token,
+                    evidence: [],
+                    failureMessage: 'x',
+                }, def);
+                assertApplied(failedA, 'fail step a (terminalizes fail, mints onFail)');
+                if (failedA.run.finalizer_ledger?.['onFail']?.status !== 'pending') {
+                    throw new Error('fixture setup: expected onFail minted pending on the fail-terminal edge');
+                }
+                if (failedA.run.finalizer_ledger?.['fin'] !== undefined) {
+                    throw new Error("fixture setup: 'fin' must NOT be selected on a pure fail seal");
+                }
+                // The prior epoch's finalizer self-failure: onFail itself FAILS (unresumable — its name
+                // enters failed_steps and stays there forever).
+                const leaseToken = uid('lease');
+                const leased = await settleStep(run.id, { kind: 'lease_finalizer', finalizer: 'onFail', leaseToken, leaseSeconds: 60 }, def);
+                assertApplied(leased, 'lease onFail');
+                const markedFailed = await settleStep(run.id, {
+                    kind: 'mark_finalizer',
+                    finalizer: 'onFail',
+                    leaseToken,
+                    result: 'failed',
+                    evidence: makeEvidence('onFail'),
+                }, def);
+                assertApplied(markedFailed, 'mark onFail failed');
+                if (!markedFailed.run.failed_steps.includes('onFail')) {
+                    throw new Error("fixture setup: expected 'onFail' in failed_steps after its own self-failure");
+                }
+                // Hand-author the post-resume state: 'a' is resumed/cleared (eligible again), but
+                // 'onFail' — a FINALIZER, unresumable — stays in failed_steps (the M1 scenario's own
+                // premise). terminal_state:false / in_progress_steps:[] / settled:{} mirror the
+                // mintFreshCases precedent's own void shape.
+                const postResumeVoid = await adapter.store.update({
+                    ...markedFailed.run,
+                    terminal_state: false,
+                    in_progress_steps: [],
+                    failed_steps: ['onFail'],
+                    settled: {},
+                });
+                if (postResumeVoid.finalizer_ledger?.['onFail']?.status !== 'failed') {
+                    throw new Error("fixture setup: onFail must still read 'failed' after the hand-authored void");
+                }
+                // Second epoch: re-claim + complete 'a'. Its own failed_steps has NOTHING from this
+                // epoch — only onFail's own prior-epoch scar.
+                const reclaimed = await adapter.store.claimStep(run.id, 'a', def);
+                const reToken = reclaimed.claims['a'].token;
+                const reCompleted = await settleStep(run.id, {
+                    kind: 'settle_step',
+                    step: 'a',
+                    outcome: 'complete',
+                    claimToken: reToken,
+                    evidence: [makeEvidence('a')],
+                }, def);
+                assertApplied(reCompleted, 're-complete step a on its second epoch');
+                if (reCompleted.run.finalizer_ledger?.['fin']?.status !== 'pending') {
+                    throw new Error(`expected 'fin' minted pending on the second-epoch complete seal (driven solely by ` +
+                        `onFail's prior-epoch self-failure), got: ${JSON.stringify(reCompleted.run.finalizer_ledger)}`);
+                }
+                // onFail itself must NOT be re-selected (its own trigger is 'fail', not 'complete'/
+                // 'completed_with_failed_steps') — it stays 'failed', never rewritten.
+                if (reCompleted.run.finalizer_ledger?.['onFail']?.status !== 'failed') {
+                    throw new Error(`expected onFail to STAY 'failed' (never re-selected on a complete seal), got: '${reCompleted.run.finalizer_ledger?.['onFail']?.status}'`);
+                }
+            },
+        },
+    ];
+}
+/** CWFS_ARRAY_ONCE — a finalizer never fires twice for one seal: the array form fires exactly
+ *  once on mixed-complete (Group A, a single push despite a multi-element intersection); `always`
+ *  fires exactly once on mixed-complete too (Group B). */
+function cwfsArrayOnceCases(adapter) {
+    const { minimalDefinition, withFinalizer } = adapter.settlementFixture;
+    const settleStep = requireSettleStep(adapter.store);
+    /** Builds a mixed-complete seal (fail 'fail_step' first, then complete 'complete_step' last)
+     *  over whatever finalizer(s) `withFin` has already added to the definition. */
+    async function driveMixedComplete(def) {
+        const { run, token: failToken } = await createClaimed(adapter.store, def, 'fail_step');
+        const claimedComplete = await adapter.store.claimStep(run.id, 'complete_step', def);
+        const completeToken = claimedComplete.claims['complete_step'].token;
+        const failed = await settleStep(run.id, {
+            kind: 'settle_step',
+            step: 'fail_step',
+            outcome: 'fail',
+            claimToken: failToken,
+            evidence: [],
+            failureMessage: 'x',
+        }, def);
+        assertApplied(failed, 'fail fail_step');
+        return settleStep(run.id, {
+            kind: 'settle_step',
+            step: 'complete_step',
+            outcome: 'complete',
+            claimToken: completeToken,
+            evidence: [makeEvidence('complete_step')],
+        }, def);
+    }
+    return [
+        {
+            law: 'CWFS_ARRAY_ONCE',
+            name: `[${adapter.storeName}] on_outcome: [complete, completed_with_failed_steps] fires EXACTLY ONCE on a mixed-complete seal (Group A, one push despite a two-element intersection)`,
+            run: async () => {
+                const def = withFinalizer(minimalDefinition(['fail_step', 'complete_step']), 'fin', [
+                    'complete',
+                    'completed_with_failed_steps',
+                ]);
+                const result = await driveMixedComplete(def);
+                assertApplied(result, 'array-form mixed-complete seal');
+                const entry = result.run.finalizer_ledger?.['fin'];
+                if (entry?.status !== 'pending' || entry.rank !== 0) {
+                    throw new Error(`expected exactly one 'fin' entry (rank 0, pending), got: ${JSON.stringify(entry)}`);
+                }
+                if (result.run.completed_steps.filter((s) => s === 'fin').length > 1) {
+                    throw new Error("'fin' must not appear more than once in completed_steps");
+                }
+            },
+        },
+        {
+            law: 'CWFS_ARRAY_ONCE',
+            name: `[${adapter.storeName}] on_outcome: 'always' fires EXACTLY ONCE on a mixed-complete seal (Group B, never double-counted alongside a Group A hit)`,
+            run: async () => {
+                const def = withFinalizer(minimalDefinition(['fail_step', 'complete_step']), 'fin', 'always');
+                const result = await driveMixedComplete(def);
+                assertApplied(result, 'always-form mixed-complete seal');
+                const entry = result.run.finalizer_ledger?.['fin'];
+                if (entry?.status !== 'pending' || entry.rank !== 0) {
+                    throw new Error(`expected exactly one 'fin' entry (rank 0, pending), got: ${JSON.stringify(entry)}`);
+                }
+            },
+        },
+    ];
+}
+/** CURRENT_BEHAVIOR_PINNED — the REJECTED design alternative (D-C: auto-firing 'fail' on
+ *  mixed-complete) never happens, pinned both ways. */
+function currentBehaviorPinnedCases(adapter) {
+    const { minimalDefinition, withFinalizer } = adapter.settlementFixture;
+    const settleStep = requireSettleStep(adapter.store);
+    return [
+        {
+            law: 'CURRENT_BEHAVIOR_PINNED',
+            name: `[${adapter.storeName}] a clean complete seal does NOT select a 'fail'-only finalizer`,
+            run: async () => {
+                const def = withFinalizer(minimalDefinition(['a']), 'onFail', 'fail');
+                const { run, token } = await createClaimed(adapter.store, def, 'a');
+                const completed = await settleStep(run.id, {
+                    kind: 'settle_step',
+                    step: 'a',
+                    outcome: 'complete',
+                    claimToken: token,
+                    evidence: [makeEvidence('a')],
+                }, def);
+                assertApplied(completed, 'clean complete of a');
+                if (completed.run.finalizer_ledger?.['onFail'] !== undefined) {
+                    throw new Error("expected 'onFail' NOT selected on a clean complete seal");
+                }
+            },
+        },
+        {
+            law: 'CURRENT_BEHAVIOR_PINNED',
+            name: `[${adapter.storeName}] a MIXED-complete seal (failed_steps ≠ ∅) still does NOT select a 'fail'-only finalizer — D-C's rejected auto-fire alternative is contract, not merely untested`,
+            run: async () => {
+                const def = withFinalizer(minimalDefinition(['fail_step', 'complete_step']), 'onFail', 'fail');
+                const { run, token: failToken } = await createClaimed(adapter.store, def, 'fail_step');
+                const claimedComplete = await adapter.store.claimStep(run.id, 'complete_step', def);
+                const completeToken = claimedComplete.claims['complete_step'].token;
+                const failed = await settleStep(run.id, {
+                    kind: 'settle_step',
+                    step: 'fail_step',
+                    outcome: 'fail',
+                    claimToken: failToken,
+                    evidence: [],
+                    failureMessage: 'x',
+                }, def);
+                assertApplied(failed, 'fail fail_step');
+                const completed = await settleStep(run.id, {
+                    kind: 'settle_step',
+                    step: 'complete_step',
+                    outcome: 'complete',
+                    claimToken: completeToken,
+                    evidence: [makeEvidence('complete_step')],
+                }, def);
+                assertApplied(completed, 'complete complete_step (terminalizes mixed-complete)');
+                if (completed.run.finalizer_ledger?.['onFail'] !== undefined) {
+                    throw new Error(`expected 'onFail' (fail-only trigger) NOT selected on a mixed-complete seal — the ` +
+                        `rejected auto-fire-fail-on-mixed-complete alternative must not happen; got: ` +
+                        `${JSON.stringify(completed.run.finalizer_ledger)}`);
+                }
+            },
+        },
+    ];
+}
+// ---------------------------------------------------------------------------
+// EXPIRE_ARM_MATRIX / EXPIRE_ABORT_CASCADE / EXPIRE_DEFAULT_RESOLVE (issue #291,
+// gate-timeout-291-correction Leg 2 — ported from the dedicated core-only
+// gate-expiry-tck-laws.test.ts per the PR-C precedent: new delta kinds' laws join this shared,
+// cross-store conformance kit rather than staying core-internal only). The dedicated core file
+// stays (see its own SCOPE NOTE, amended) as fast unit-level coverage exercising `applySettlement`
+// directly with hand-rolled fixtures — this is the STORE-EXERCISING cross-conformance layer,
+// proving BOTH JsonFileStore and InMemoryStore's `settleStep` reach the identical, correct
+// `applyExpireGate` behavior through the real store surface, matching every other delta kind's
+// own dual coverage (a dedicated engine-level test file + a settlement-contract.ts law family).
+// ---------------------------------------------------------------------------
+function expireArmMatrixCases(adapter) {
+    const { minimalDefinition } = adapter.settlementFixture;
+    const settleStep = requireSettleStep(adapter.store);
+    return [
+        {
+            law: 'EXPIRE_ARM_MATRIX',
+            name: `[${adapter.storeName}] expire_gate refuses not_expired with the injectable now, never the caller-implied clock`,
+            run: async () => {
+                const def = minimalDefinition(['gated']);
+                const { run, token } = await createClaimed(adapter.store, def, 'gated');
+                const gate = makePendingGate('gated', {
+                    gateId: 'gate-1',
+                    expiresAt: '2026-01-01T00:05:00.000Z',
+                    onExpiry: 'abort',
+                });
+                const opened = await settleStep(run.id, { kind: 'open_gate', step: 'gated', claimToken: token, pendingGate: gate, evidence: [] }, def);
+                assertApplied(opened, 'open_gate');
+                const result = await settleStep(run.id, { kind: 'expire_gate', gateId: 'gate-1' }, def, {
+                    now: new Date('2026-01-01T00:00:30.000Z'),
+                });
+                assertRefused(result, 'not_expired', 'expire_gate before expires_at');
+            },
+        },
+        {
+            law: 'EXPIRE_ARM_MATRIX',
+            name: `[${adapter.storeName}] expire_gate replay ×2 (settle_default): the SECOND attempt NOOPs already_settled — version-safe idempotence`,
+            run: async () => {
+                const def = minimalDefinition(['gated']);
+                const { run, token } = await createClaimed(adapter.store, def, 'gated');
+                const gate = makePendingGate('gated', {
+                    gateId: 'gate-1',
+                    expiresAt: '2026-01-01T00:05:00.000Z',
+                    onExpiry: 'settle_default',
+                    defaultChoice: 'approve',
+                });
+                const opened = await settleStep(run.id, { kind: 'open_gate', step: 'gated', claimToken: token, pendingGate: gate, evidence: [] }, def);
+                assertApplied(opened, 'open_gate');
+                const now = new Date('2026-01-01T00:10:00.000Z');
+                const first = await settleStep(run.id, { kind: 'expire_gate', gateId: 'gate-1' }, def, {
+                    now,
+                });
+                assertApplied(first, 'first expire_gate (settle_default)');
+                const second = await settleStep(run.id, { kind: 'expire_gate', gateId: 'gate-1' }, def, {
+                    now,
+                });
+                assertRefused(second, 'already_settled', 'replay expire_gate for an already-settled settle_default gate');
+            },
+        },
+        {
+            law: 'EXPIRE_ARM_MATRIX',
+            name: `[${adapter.storeName}] expire_gate replay ×2 (abort): the SECOND attempt NOOPs already_settled (terminal split)`,
+            run: async () => {
+                const def = minimalDefinition(['gated']);
+                const { run, token } = await createClaimed(adapter.store, def, 'gated');
+                const gate = makePendingGate('gated', {
+                    gateId: 'gate-1',
+                    expiresAt: '2026-01-01T00:05:00.000Z',
+                    onExpiry: 'abort',
+                });
+                const opened = await settleStep(run.id, { kind: 'open_gate', step: 'gated', claimToken: token, pendingGate: gate, evidence: [] }, def);
+                assertApplied(opened, 'open_gate');
+                const now = new Date('2026-01-01T00:10:00.000Z');
+                const first = await settleStep(run.id, { kind: 'expire_gate', gateId: 'gate-1' }, def, {
+                    now,
+                });
+                assertApplied(first, 'first expire_gate (abort)');
+                const second = await settleStep(run.id, { kind: 'expire_gate', gateId: 'gate-1' }, def, {
+                    now,
+                });
+                assertRefused(second, 'already_settled', 'replay expire_gate for an already-aborted gate (terminal-split arm)');
+            },
+        },
+        {
+            law: 'EXPIRE_ARM_MATRIX',
+            name: `[${adapter.storeName}] expire_gate against a run terminalized by a DIFFERENT cause refuses run_terminal — never resurrecting or re-terminalizing`,
+            run: async () => {
+                const def = minimalDefinition(['gated']);
+                const { run, token } = await createClaimed(adapter.store, def, 'gated');
+                const completed = await settleStep(run.id, {
+                    kind: 'settle_step',
+                    step: 'gated',
+                    outcome: 'complete',
+                    claimToken: token,
+                    evidence: [makeEvidence('gated')],
+                }, def);
+                assertApplied(completed, 'complete gated (terminalizes — sole step, unrelated to any gate)');
+                const result = await settleStep(run.id, { kind: 'expire_gate', gateId: 'gate-1' }, def, {
+                    now: new Date('2026-01-01T00:10:00.000Z'),
+                });
+                assertRefused(result, 'run_terminal', 'expire_gate against a run terminalized by an unrelated cause');
+            },
+        },
+        {
+            law: 'EXPIRE_ARM_MATRIX',
+            name: `[${adapter.storeName}] expire_gate with an unknown/superseded gateId refuses gate_mismatch`,
+            run: async () => {
+                const def = minimalDefinition(['gated']);
+                const { run, token } = await createClaimed(adapter.store, def, 'gated');
+                const gate = makePendingGate('gated', {
+                    gateId: 'live-gate',
+                    expiresAt: '2026-01-01T00:05:00.000Z',
+                    onExpiry: 'abort',
+                });
+                const opened = await settleStep(run.id, { kind: 'open_gate', step: 'gated', claimToken: token, pendingGate: gate, evidence: [] }, def);
+                assertApplied(opened, 'open_gate');
+                const result = await settleStep(run.id, { kind: 'expire_gate', gateId: 'stale-unknown-gate' }, def, { now: new Date('2026-01-01T00:10:00.000Z') });
+                assertRefused(result, 'gate_mismatch', 'expire_gate with an unknown gateId');
+            },
+        },
+        {
+            law: 'EXPIRE_ARM_MATRIX',
+            name: `[${adapter.storeName}] expire_gate on a finding-only gate (expires_at present, on_expiry absent) refuses no_disposition, arm-level, before APPLY — never cleared`,
+            run: async () => {
+                const def = minimalDefinition(['gated']);
+                const { run, token } = await createClaimed(adapter.store, def, 'gated');
+                const gate = makePendingGate('gated', {
+                    gateId: 'gate-1',
+                    expiresAt: '2026-01-01T00:05:00.000Z',
+                    // no onExpiry — finding-only.
+                });
+                const opened = await settleStep(run.id, { kind: 'open_gate', step: 'gated', claimToken: token, pendingGate: gate, evidence: [] }, def);
+                assertApplied(opened, 'open_gate');
+                const result = await settleStep(run.id, { kind: 'expire_gate', gateId: 'gate-1' }, def, {
+                    now: new Date('2026-01-01T00:10:00.000Z'),
+                });
+                assertRefused(result, 'no_disposition', 'expire_gate on a finding-only gate');
+                if (result.run.pending_gate === undefined) {
+                    throw new Error('a finding-only refusal must NEVER clear pending_gate');
+                }
+            },
+        },
+    ];
+}
+function expireAbortCascadeCases(adapter) {
+    const { minimalDefinition, withFinalizer } = adapter.settlementFixture;
+    const settleStep = requireSettleStep(adapter.store);
+    return [
+        {
+            law: 'EXPIRE_ABORT_CASCADE',
+            name: `[${adapter.storeName}] expire_gate (abort) clears pending_gate + claim, writes aborted_at + skip_details {gate_expired, gate_id} (day-one), mints finalizers — all in ONE write`,
+            run: async () => {
+                const def = withFinalizer(minimalDefinition(['gated']), 'fin', 'abort');
+                const { run, token } = await createClaimed(adapter.store, def, 'gated');
+                const gate = makePendingGate('gated', {
+                    gateId: 'gate-1',
+                    expiresAt: '2026-01-01T00:05:00.000Z',
+                    onExpiry: 'abort',
+                });
+                const opened = await settleStep(run.id, { kind: 'open_gate', step: 'gated', claimToken: token, pendingGate: gate, evidence: [] }, def);
+                assertApplied(opened, 'open_gate');
+                const result = await settleStep(run.id, { kind: 'expire_gate', gateId: 'gate-1' }, def, {
+                    now: new Date('2026-01-01T00:10:00.000Z'),
+                });
+                assertApplied(result, 'expire_gate (abort)');
+                if (result.run.pending_gate !== undefined) {
+                    throw new Error('expected pending_gate cleared');
+                }
+                if (result.run.claims?.['gated'] !== undefined) {
+                    throw new Error('expected the claim cleared');
+                }
+                if (result.run.in_progress_steps.includes('gated')) {
+                    throw new Error("expected 'gated' removed from in_progress_steps");
+                }
+                if (result.run.terminal_state !== true) {
+                    throw new Error('expected the run to terminalize');
+                }
+                if (result.run.aborted_at?.step_id !== 'gated') {
+                    throw new Error(`expected aborted_at.step_id === 'gated', got ${JSON.stringify(result.run.aborted_at)}`);
+                }
+                const detail = result.run.skip_details?.['gated'];
+                if (detail === undefined || detail.kind !== 'gate_expired' || detail.gate_id !== 'gate-1') {
+                    throw new Error(`expected skip_details.gated = {kind:'gate_expired', gate_id:'gate-1'}, got ${JSON.stringify(detail)}`);
+                }
+                if (result.run.settled?.['gated'] !== undefined) {
+                    throw new Error('TERMINAL_GATE_EXCLUSION: the abort disposition must never ALSO write a settled gate entry');
+                }
+                if (result.run.finalizer_ledger?.['fin'] === undefined) {
+                    throw new Error("expected the 'abort'-triggered finalizer minted on the abort edge");
+                }
+            },
+        },
+        {
+            law: 'EXPIRE_ABORT_CASCADE',
+            name: `[${adapter.storeName}] the D-4 discriminator: a gate_expired skip_detail is NEVER mistaken for gate_cancelled_by_abort`,
+            run: async () => {
+                const def = minimalDefinition(['gated']);
+                const { run, token } = await createClaimed(adapter.store, def, 'gated');
+                const gate = makePendingGate('gated', {
+                    gateId: 'gate-1',
+                    expiresAt: '2026-01-01T00:05:00.000Z',
+                    onExpiry: 'abort',
+                });
+                const opened = await settleStep(run.id, { kind: 'open_gate', step: 'gated', claimToken: token, pendingGate: gate, evidence: [] }, def);
+                assertApplied(opened, 'open_gate');
+                const result = await settleStep(run.id, { kind: 'expire_gate', gateId: 'gate-1' }, def, {
+                    now: new Date('2026-01-01T00:10:00.000Z'),
+                });
+                assertApplied(result, 'expire_gate (abort)');
+                const kind = result.run.skip_details?.['gated']?.kind;
+                if (kind !== 'gate_expired') {
+                    throw new Error(`expected skip_details.gated.kind === 'gate_expired', got '${kind}'`);
+                }
+                // TypeScript narrows `kind` to the literal above; the discriminator being tested is that
+                // it is NEVER 'gate_cancelled_by_abort' — asserted by construction (the union excludes it
+                // once narrowed) and restated here as an explicit, readable pin.
+            },
+        },
+        {
+            law: 'EXPIRE_ABORT_CASCADE',
+            name: `[${adapter.storeName}] expire_gate (abort) never stamps defaulted_steps, even though it terminalizes (the FM-5/#232 guard)`,
+            run: async () => {
+                const def = minimalDefinition(['gated']);
+                const { run, token } = await createClaimed(adapter.store, def, 'gated');
+                const gate = makePendingGate('gated', {
+                    gateId: 'gate-1',
+                    expiresAt: '2026-01-01T00:05:00.000Z',
+                    onExpiry: 'abort',
+                });
+                const opened = await settleStep(run.id, { kind: 'open_gate', step: 'gated', claimToken: token, pendingGate: gate, evidence: [] }, def);
+                assertApplied(opened, 'open_gate');
+                const result = await settleStep(run.id, { kind: 'expire_gate', gateId: 'gate-1' }, def, {
+                    now: new Date('2026-01-01T00:10:00.000Z'),
+                });
+                assertApplied(result, 'expire_gate (abort)');
+                if (result.run.defaulted_steps !== undefined) {
+                    throw new Error('expire_gate (abort) must never stamp defaulted_steps');
+                }
+            },
+        },
+    ];
+}
+function expireDefaultResolveCases(adapter) {
+    const { minimalDefinition } = adapter.settlementFixture;
+    const settleStep = requireSettleStep(adapter.store);
+    return [
+        {
+            law: 'EXPIRE_DEFAULT_RESOLVE',
+            name: `[${adapter.storeName}] expire_gate (settle_default) resolves with resolved_by:'timeout' attribution + terminalizes (sole step)`,
+            run: async () => {
+                const def = minimalDefinition(['gated']);
+                const { run, token } = await createClaimed(adapter.store, def, 'gated');
+                const gate = makePendingGate('gated', {
+                    gateId: 'gate-1',
+                    expiresAt: '2026-01-01T00:05:00.000Z',
+                    onExpiry: 'settle_default',
+                    defaultChoice: 'approve',
+                });
+                const opened = await settleStep(run.id, { kind: 'open_gate', step: 'gated', claimToken: token, pendingGate: gate, evidence: [] }, def);
+                assertApplied(opened, 'open_gate');
+                const result = await settleStep(run.id, { kind: 'expire_gate', gateId: 'gate-1' }, def, {
+                    now: new Date('2026-01-01T00:10:00.000Z'),
+                });
+                assertApplied(result, 'expire_gate (settle_default)');
+                const entry = result.run.settled?.['gated'];
+                if (entry?.token !== 'gate-1' ||
+                    entry.outcome !== 'gate' ||
+                    entry.choice !== 'approve' ||
+                    entry.resolved_by !== 'timeout') {
+                    throw new Error(`expected settled.gated = {token:'gate-1', outcome:'gate', choice:'approve', ` +
+                        `resolved_by:'timeout'}, got ${JSON.stringify(entry)}`);
+                }
+                if (result.run.terminal_state !== true) {
+                    throw new Error('sole step ⇒ isComplete ⇒ the run must terminalize');
+                }
+            },
+        },
+        {
+            law: 'EXPIRE_DEFAULT_RESOLVE',
+            name: `[${adapter.storeName}] expire_gate (settle_default): a sibling step still in progress keeps the run non-terminal`,
+            run: async () => {
+                const def = minimalDefinition(['gated', 'sibling']);
+                const { run, token } = await createClaimed(adapter.store, def, 'gated');
+                await adapter.store.claimStep(run.id, 'sibling', def);
+                const gate = makePendingGate('gated', {
+                    gateId: 'gate-1',
+                    expiresAt: '2026-01-01T00:05:00.000Z',
+                    onExpiry: 'settle_default',
+                    defaultChoice: 'approve',
+                });
+                const opened = await settleStep(run.id, { kind: 'open_gate', step: 'gated', claimToken: token, pendingGate: gate, evidence: [] }, def);
+                assertApplied(opened, 'open_gate');
+                const result = await settleStep(run.id, { kind: 'expire_gate', gateId: 'gate-1' }, def, {
+                    now: new Date('2026-01-01T00:10:00.000Z'),
+                });
+                assertApplied(result, 'expire_gate (settle_default)');
+                if (result.run.terminal_state !== false) {
+                    throw new Error("'sibling' still in_progress ⇒ the run must stay non-terminal");
+                }
+                if (!result.run.completed_steps.includes('gated')) {
+                    throw new Error("expected 'gated' in completed_steps");
+                }
+            },
+        },
+        {
+            law: 'EXPIRE_DEFAULT_RESOLVE',
+            name: `[${adapter.storeName}] FROZEN-BEATS-DEFINITION: expire_gate reads the RECORD-frozen default_choice, NEVER a re-registered definition's drifted value`,
+            run: async () => {
+                const def = minimalDefinition(['gated']);
+                const { run, token } = await createClaimed(adapter.store, def, 'gated');
+                // The gate was minted under a definition whose gate.default_choice was 'approve' — frozen
+                // into the record's own pending_gate.default_choice at mint (simulated directly here, as
+                // the source test targets applyExpireGate's own read behavior, not the mint site).
+                const gate = makePendingGate('gated', {
+                    gateId: 'gate-1',
+                    expiresAt: '2026-01-01T00:05:00.000Z',
+                    onExpiry: 'settle_default',
+                    defaultChoice: 'approve',
+                });
+                const opened = await settleStep(run.id, { kind: 'open_gate', step: 'gated', claimToken: token, pendingGate: gate, evidence: [] }, def);
+                assertApplied(opened, 'open_gate');
+                // A DIFFERENT definition — simulating a workflow re-registered with a changed
+                // default_choice ('reject') and a different choice set entirely — passed only at
+                // enactment time. applyExpireGate never reads step-def gate config (gate state lives
+                // entirely on the RECORD's frozen pending_gate), so this must have zero effect.
+                const driftedDef = {
+                    id: uid('settlement-wf-drifted'),
+                    name: 'Drifted default_choice',
+                    version: 1,
+                    steps: {
+                        gated: {
+                            description: 'gated',
+                            execution: 'agent',
+                            depends_on: [],
+                            trust: 'human_confirmed',
+                            gate: {
+                                choices: ['ship', 'hold'],
+                                on_expiry: 'settle_default',
+                                default_choice: 'reject',
+                            },
+                        },
+                    },
+                };
+                const result = await settleStep(run.id, { kind: 'expire_gate', gateId: 'gate-1' }, driftedDef, {
+                    now: new Date('2026-01-01T00:10:00.000Z'),
+                });
+                assertApplied(result, 'expire_gate against a drifted definition');
+                if (result.run.settled?.['gated']?.choice !== 'approve') {
+                    throw new Error(`expected the FROZEN choice 'approve' to win, got '${result.run.settled?.['gated']?.choice}'`);
+                }
+            },
+        },
+        {
+            law: 'EXPIRE_DEFAULT_RESOLVE',
+            name: `[${adapter.storeName}] expire_gate (settle_default): the evidence gate_response snapshot carries responded_by:'timeout' + resolution:'expired_default'`,
+            run: async () => {
+                const def = minimalDefinition(['gated']);
+                const { run, token } = await createClaimed(adapter.store, def, 'gated');
+                const gate = makePendingGate('gated', {
+                    gateId: 'gate-1',
+                    expiresAt: '2026-01-01T00:05:00.000Z',
+                    onExpiry: 'settle_default',
+                    defaultChoice: 'approve',
+                });
+                const opened = await settleStep(run.id, { kind: 'open_gate', step: 'gated', claimToken: token, pendingGate: gate, evidence: [] }, def);
+                assertApplied(opened, 'open_gate');
+                const result = await settleStep(run.id, { kind: 'expire_gate', gateId: 'gate-1' }, def, {
+                    now: new Date('2026-01-01T00:10:00.000Z'),
+                });
+                assertApplied(result, 'expire_gate (settle_default)');
+                const snapshot = result.run.evidence.at(-1);
+                if (snapshot?.kind !== 'gate_response' ||
+                    snapshot.responded_by !== 'timeout' ||
+                    snapshot.resolution !== 'expired_default') {
+                    throw new Error(`expected the last evidence entry to be a gate_response with responded_by:'timeout'/` +
+                        `resolution:'expired_default', got ${JSON.stringify(snapshot)}`);
+                }
+            },
+        },
+    ];
+}
+// ---------------------------------------------------------------------------
 // Assembly
 // ---------------------------------------------------------------------------
 /**
@@ -2503,6 +3271,16 @@ export function settlementContract(adapter) {
         ...guardCases(adapter),
         ...releaseIdempotentCases(adapter),
         ...phaseIsGeneratedCases(adapter),
+        // issue #302 (finalizer outcome×trigger matrix).
+        ...cwfsFiresPerArmCases(adapter),
+        ...cwfsNegativesCases(adapter),
+        ...cwfsSecondEpochCases(adapter),
+        ...cwfsArrayOnceCases(adapter),
+        ...currentBehaviorPinnedCases(adapter),
+        // issue #291 (gate-timeout-291-correction, Leg 2).
+        ...expireArmMatrixCases(adapter),
+        ...expireAbortCascadeCases(adapter),
+        ...expireDefaultResolveCases(adapter),
     ];
 }
 //# sourceMappingURL=settlement-contract.js.map