@sensigo/realm 0.32.0 → 0.34.0

package/dist/engine/settlement.js

@@ -20,11 +20,14 @@ function norm(t) {
 function tokensEqual(a, b) {
     return norm(a) === norm(b);
 }
-/** `M := {complete: completed_steps, fail: failed_steps, skip: skipped_steps}` — the membership
- *  array a settled-map entry's `outcome` maps to. */
+/** `M := {complete: completed_steps, fail: failed_steps, skip: skipped_steps, gate:
+ *  completed_steps}` — the membership array a settled-map entry's `outcome` maps to. `gate`
+ *  (issue #279, increment 2, PR-C — design record §2) joined alongside `completed_steps`: a
+ *  resolved gate's step physically lands there, same as a `complete` settle_step outcome. */
 function membershipFor(fresh, outcome) {
     switch (outcome) {
         case 'complete':
+        case 'gate':
             return fresh.completed_steps;
         case 'fail':
             return fresh.failed_steps;
@@ -81,16 +84,29 @@ function finalizerTriggers(stepDef) {
     return new Set(Array.isArray(raw) ? raw : [raw]);
 }
 /**
- * Selects the finalizer steps that fire for a terminal `outcome`, in the drain order (design
- * record §4/§6; extracted from `buildFinalizedSeal`'s selection, execution-loop.ts :3117-3126):
- * Group A (rank precedence) — `on_outcome` contains `outcome` (the specific catch/complete arm);
- * Group B — `on_outcome` contains `'always'` but NOT `outcome` (a finalizer listing both runs
- * once, in Group A). Each group in `Object.entries` declaration order; Group A then Group B.
+ * Selects the finalizer steps that fire for a terminal outcome, in the drain order (design
+ * record §4/§6, widened by #302's S2 fold; extracted from `buildFinalizedSeal`'s selection,
+ * execution-loop.ts :3117-3126): Group A (rank precedence) — the finalizer's OWN declared
+ * `on_outcome` set intersects the EFFECTIVE trigger set non-emptily; Group B — `on_outcome`
+ * contains `'always'` but the finalizer missed Group A (a finalizer listing both runs once, in
+ * Group A). Each group in `Object.entries` declaration order; Group A then Group B.
  * `settledStepNames` excludes any finalizer already at-most-once settled (resume/re-drive safety)
  * — pass `completed_steps ∪ failed_steps`, NEVER the `RunRecord.settled` map (a different,
  * per-step-outcome-keyed structure this selection does not consult).
+ *
+ * `outcome` accepts EITHER shape (issue #302, S2 — `selectFinalizers` is a PUBLIC export,
+ * `index.ts`, so widening the param rather than replacing it is an API-compat requirement, not a
+ * style choice):
+ *  - a bare `SettleStepOutcome` string — every pre-#302 caller's shape, normalized internally to
+ *    a singleton set; BYTE-IDENTICAL selection to the pre-widening behavior (pinned by the
+ *    string-form compat test) and supported INDEFINITELY — this is not a deprecated compat shim.
+ *  - a pre-derived `ReadonlySet<FinalizerTrigger>` (via {@link deriveEffectiveTriggers}) — the
+ *    #302 call shape both engine chokepoints (`mintFresh`, `buildFinalizedSeal`) now use, letting
+ *    a seal satisfy more than one trigger at once (e.g. `{'complete', 'completed_with_failed_steps'}`).
+ * Semver: additive or (minor) — no existing call site's behavior changes.
  */
 export function selectFinalizers(definition, settledStepNames, outcome) {
+    const effective = typeof outcome === 'string' ? new Set([outcome]) : outcome;
     const groupA = [];
     const groupB = [];
     for (const [name, step] of Object.entries(definition.steps)) {
@@ -99,13 +115,45 @@ export function selectFinalizers(definition, settledStepNames, outcome) {
         if (settledStepNames.has(name))
             continue; // at-most-once per run (resume / re-drive safety)
         const triggers = finalizerTriggers(step);
-        if (triggers.has(outcome))
+        let inGroupA = false;
+        for (const t of triggers) {
+            if (effective.has(t)) {
+                inGroupA = true;
+                break;
+            }
+        }
+        if (inGroupA)
             groupA.push(name);
         else if (triggers.has('always'))
             groupB.push(name);
     }
     return [...groupA, ...groupB];
 }
+/**
+ * Derives the full set of finalizer triggers a terminal `outcome` satisfies for `record` (issue
+ * #302, design record §Mechanics-1): `{outcome}` — always — plus `'completed_with_failed_steps'`
+ * when `outcome === 'complete' ∧ record.failed_steps.length > 0` (a "mixed complete" seal — the
+ * SAME class #304's `completed_with_failed_steps` run-health finding already surfaces at read
+ * time; this is the mint-time trigger, sharing that one predicate).
+ *
+ * Uniform across epochs (design record M1, deliberate): 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 this trigger — no exclusion of finalizer-declared step names. The
+ * alternative (excluding finalizer names from the predicate) buys mint-time purity at the cost of
+ * diverging from the read-time #304 finding's own uniform predicate; this design keeps ONE
+ * predicate for both surfaces, deliberately.
+ *
+ * Pure; this ONE function is the seam a future authorable tolerance threshold (SFN-style: fire
+ * only when `failed_steps.length` exceeds some declared N) would extend — banked, not built
+ * (design record R2).
+ */
+export function deriveEffectiveTriggers(outcome, record) {
+    const triggers = new Set([outcome]);
+    if (outcome === 'complete' && record.failed_steps.length > 0) {
+        triggers.add('completed_with_failed_steps');
+    }
+    return triggers;
+}
 // ---------------------------------------------------------------------------
 // §4 mintFresh (terminal false→true edge only; same atomic write)
 // ---------------------------------------------------------------------------
@@ -123,7 +171,10 @@ export function selectFinalizers(definition, settledStepNames, outcome) {
  */
 function mintFresh(record, definition, outcome) {
     const settledStepNames = new Set([...record.completed_steps, ...record.failed_steps]);
-    const selected = selectFinalizers(definition, settledStepNames, outcome);
+    // issue #302: derive the FULL effective trigger set (chokepoint 1 of 2) — record already
+    // reflects this settlement's own membership effects (a 'complete' outcome's failed_steps here
+    // is PRIOR failures only), so this is the correct read point for the mixed-complete predicate.
+    const selected = selectFinalizers(definition, settledStepNames, deriveEffectiveTriggers(outcome, record));
     if (selected.length === 0)
         return record.finalizer_ledger;
     const ledger = { ...record.finalizer_ledger };
@@ -137,6 +188,41 @@ function mintFresh(record, definition, outcome) {
     return ledger;
 }
 // ---------------------------------------------------------------------------
+// §4 shared APPLY postconditions (design record design-d5-increment2.md §4, hoisted — lens-2 F4:
+// "one implementation, every kind routes through it"). Every kind whose APPLY can terminalize
+// (settle_step complete/fail/abort [shipped]; settle_gate resolution-complete; settle_guard
+// pass/resolution_error/abort [increment 2, PR-C]) calls this ONE function to (1) mint fresh
+// finalizers on a genuine terminal false→true edge (§4.1), (2) stamp `defaulted_steps` on a
+// COMPLETE-terminal edge only (§4.2), and (3) derive `run_phase` uniformly (§4.5) — regardless of
+// whether this particular APPLY actually transitioned.
+// ---------------------------------------------------------------------------
+/**
+ * `record.terminal_state` must already reflect the kind-specific terminal decision (each arm
+ * computes its own `isComplete`/unconditional-abort logic BEFORE calling this) — every in-contract
+ * caller has already refused `run_terminal` earlier in its own arm, so `record.terminal_state` can
+ * only be transitioning `false → true` here, never `true → true`; `transitioned` is therefore
+ * simply the post-write value, read back explicitly (not assumed) so a future caller that ever
+ * violates that precondition fails loudly via a wrong `transitioned` value rather than silently.
+ */
+function applyTerminalPostconditions(record, definition, mintOutcome, stampDefaulted) {
+    const transitioned = record.terminal_state === true;
+    let sealed = record;
+    if (transitioned) {
+        // On terminal false→true edge: mintFresh (§4.1), same atomic write.
+        const ledger = mintFresh(record, definition, mintOutcome);
+        sealed = { ...record, ...(ledger !== undefined ? { finalizer_ledger: ledger } : {}) };
+        // defaulted_steps stamped IFF a COMPLETE-terminal edge (§4.2; the FM-5/#232 guard) — never on
+        // a fail/abort seal, even one that terminalizes.
+        if (stampDefaulted) {
+            const defaultedSteps = deriveDefaultedSteps(sealed.evidence);
+            if (defaultedSteps.length > 0)
+                sealed = { ...sealed, defaulted_steps: defaultedSteps };
+        }
+    }
+    const withPhase = { ...sealed, run_phase: deriveRunPhase(sealed) };
+    return { run: withPhase, transitioned };
+}
+// ---------------------------------------------------------------------------
 // §3 settleStepArms
 // ---------------------------------------------------------------------------
 function applySettleStep(fresh, delta, definition, now) {
@@ -209,6 +295,7 @@ function applyAbortEdge(fresh, withMembership, step, abort, definition, now) {
     // nothing above has touched it.
     if (fresh.pending_gate !== undefined && fresh.pending_gate.step_name !== step) {
         const gateStepName = fresh.pending_gate.step_name;
+        const cancelledGateId = fresh.pending_gate.gate_id;
         const { pending_gate: _droppedGate, ...withoutGate } = aborted;
         aborted = {
             ...withoutGate,
@@ -217,7 +304,9 @@ function applyAbortEdge(fresh, withMembership, step, abort, definition, now) {
             skipped_steps: [...withoutGate.skipped_steps, gateStepName],
             skip_details: {
                 ...withoutGate.skip_details,
-                [gateStepName]: { kind: 'gate_cancelled_by_abort' },
+                // gate_id additive (design record §5 D-4) — the settle_gate run_terminal envelope's
+                // cancelled-variant discriminator binds by this once populated.
+                [gateStepName]: { kind: 'gate_cancelled_by_abort', gate_id: cancelledGateId },
             },
             evidence: [
                 ...withoutGate.evidence,
@@ -226,24 +315,20 @@ function applyAbortEdge(fresh, withMembership, step, abort, definition, now) {
                     startedAt: now,
                     completedAt: now,
                     input: {},
-                    output: { gate_cancelled_by_abort: true, aborted_by: step },
+                    output: { gate_cancelled_by_abort: true, aborted_by: step, gate_id: cancelledGateId },
                 }),
             ],
         };
     }
-    // On terminal false→true edge: mintFresh (§4), same atomic write. abort NEVER stamps
-    // defaulted_steps (the FM-5/#232 guard — only the complete edge does).
-    const ledger = mintFresh(aborted, definition, 'abort');
-    const finalRun = {
-        ...aborted,
-        ...(ledger !== undefined ? { finalizer_ledger: ledger } : {}),
-    };
-    const withPhase = { ...finalRun, run_phase: deriveRunPhase(finalRun) };
+    // §4 shared postconditions: abort NEVER stamps defaulted_steps (the FM-5/#232 guard — only the
+    // complete edge does); `transitioned` is always true here (isTerminal(fresh) was already
+    // refused above, and `aborted.terminal_state` is unconditionally true).
+    const { run, transitioned } = applyTerminalPostconditions(aborted, definition, 'abort', false);
     return {
         applied: true,
-        run: withPhase,
-        transitioned: true, // isTerminal(fresh) was already refused above — abort is always false→true
-        pendingFinalizers: pendingFinalizerNames(withPhase.finalizer_ledger),
+        run,
+        transitioned,
+        pendingFinalizers: pendingFinalizerNames(run.finalizer_ledger),
     };
 }
 /** complete / fail: the TWO-DISJUNCT `isComplete` predicate (execution-loop.ts :2579-2583 /
@@ -270,25 +355,562 @@ function applyCompleteOrFailEdge(withMembership, step, outcome, failureMessage,
             }
             : {}),
     };
-    let sealed = draft;
-    if (isComplete) {
-        // On terminal edge: mintFresh (§4), same atomic write.
-        const ledger = mintFresh(draft, definition, outcome);
-        sealed = { ...draft, ...(ledger !== undefined ? { finalizer_ledger: ledger } : {}) };
-        // defaulted_steps stamped IFF complete-terminal edge (FM-5/#232 guard) — never on a fail seal,
-        // even one that terminalizes.
-        if (outcome === 'complete') {
-            const defaultedSteps = deriveDefaultedSteps(sealed.evidence);
-            if (defaultedSteps.length > 0)
-                sealed = { ...sealed, defaulted_steps: defaultedSteps };
+    // §4 shared postconditions: defaulted_steps stamps IFF this is a COMPLETE-terminal edge — never
+    // on a fail seal, even one that terminalizes.
+    const { run, transitioned } = applyTerminalPostconditions(draft, definition, outcome, outcome === 'complete' && isComplete);
+    return {
+        applied: true,
+        run,
+        transitioned,
+        pendingFinalizers: pendingFinalizerNames(run.finalizer_ledger),
+    };
+}
+// ---------------------------------------------------------------------------
+// §3 openGateArms (issue #279, increment 2, PR-C) — fence = claimToken; entry lookup FIRST
+// (design record lens-2 F1).
+// ---------------------------------------------------------------------------
+function applyOpenGate(fresh, delta) {
+    const { step, claimToken, pendingGate, evidence } = delta;
+    // Idempotence arm BEFORE terminal/claim (mirrors settleStepArms's own ordering, L21 ii).
+    const existing = entryOf(fresh, step);
+    if (existing !== undefined) {
+        if (existing.outcome === 'gate' && existing.token === pendingGate.gate_id) {
+            // Exact-delta replay AFTER the gate already resolved (BU F6) — the gate this delta is
+            // trying to open is the SAME one already committed as resolved.
+            return { applied: false, reason: 'already_settled', run: fresh };
         }
+        // Envelope text stays neutral (N1 — no "by_other" amplification) at the caller (PR-D).
+        return { applied: false, reason: 'already_settled_by_other', run: fresh };
     }
-    const withPhase = { ...sealed, run_phase: deriveRunPhase(sealed) };
+    if (isTerminal(fresh)) {
+        return { applied: false, reason: 'run_terminal', run: fresh };
+    }
+    if (fresh.pending_gate !== undefined) {
+        if (fresh.pending_gate.step_name === step) {
+            if (fresh.pending_gate.gate_id === pendingGate.gate_id) {
+                // Exact-delta replay, gate still open (e.g. a retried gate-open write).
+                return { applied: false, reason: 'already_settled', run: fresh };
+            }
+            const claim = fresh.claims?.[step];
+            if (claim !== undefined && tokensEqual(claim.token, claimToken)) {
+                // D-1: the LIVE gate wins, rendered VERBATIM. In-contract UNREACHABLE (claimStep's
+                // in-flight guard + reclaim's own open-gate refusal both prevent a second open_gate
+                // attempt from ever reaching here with a live claim) — defensive.
+                return { applied: false, reason: 'already_open', run: fresh, gate: fresh.pending_gate };
+            }
+            // Same step, different claimant — defensive (a claim can't be re-acquired under an open
+            // gate; findEligibleSteps returns [] while a gate is open).
+            return { applied: false, reason: 'claim_lost', run: fresh };
+        }
+        // A gate open on ANOTHER step — serialization; the step named here STAYS claimed (L13
+        // asserts this — the caller's recovery path is to wait for the live gate to resolve).
+        return { applied: false, reason: 'gate_mismatch', run: fresh };
+    }
+    const claim = fresh.claims?.[step];
+    if (claim === undefined || !tokensEqual(claim.token, claimToken)) {
+        return { applied: false, reason: 'claim_lost', run: fresh };
+    }
+    // APPLY OPEN: pending_gate set (delta-carried verbatim); evidence append; CLAIM RETAINED + step
+    // stays in_progress (execution-loop.ts:2958 — retention keeps isComplete sound, G-1). Never
+    // terminalizes (design record §4.1) — run_phase still derives (§4.5: transform-owned uniformly).
+    const withGate = {
+        ...fresh,
+        evidence: [...fresh.evidence, ...evidence],
+        pending_gate: pendingGate,
+    };
+    const run = { ...withGate, run_phase: deriveRunPhase(withGate) };
+    return {
+        applied: true,
+        run,
+        transitioned: false,
+        pendingFinalizers: pendingFinalizerNames(run.finalizer_ledger),
+    };
+}
+// ---------------------------------------------------------------------------
+// §3 settleGateArms (issue #279, increment 2, PR-C) — fence = gateId ONLY (L20). ZERO claim arms.
+// ---------------------------------------------------------------------------
+/**
+ * Finds the (at most one, per G-2) `settled` entry recording a resolved gate matching `gateId` —
+ * searched by gateId (the settle_gate fence), not by a known step name, since a gate submission
+ * carries only the gate_id. `first` (design record §3): lookup runs FIRST for fail-safety under
+ * corruption (D3 §0.2) — soundness of both the lookup and the "first" quantifier rests on G-2
+ * (TERMINAL_GATE_EXCLUSION) plus per-attempt gate_id uniqueness plus the membership conjunct (the
+ * orphan rule, generalized): a G-2-violating corrupt both-match record makes iteration order
+ * store-dependent, which is exactly why the fail-safe direction (NOOP, never RESOLVE) is pinned
+ * at the CALLER (this function returns whichever match Object.entries visits first — a real store
+ * never produces two, so this never matters in-contract).
+ */
+function findSettledGateEntry(fresh, gateId) {
+    for (const [step, entry] of Object.entries(fresh.settled ?? {})) {
+        if (entry.outcome !== 'gate' || entry.token !== gateId)
+            continue;
+        if (!membershipFor(fresh, entry.outcome).includes(step))
+            continue; // orphan rule
+        return { step, choice: entry.choice };
+    }
+    return undefined;
+}
+function applySettleGate(fresh, delta, definition, 
+// issue #291 ([F3] shape c, lane-1 authorized): injectable `now` threaded through, mirroring
+// every other `now`-consuming arm (`applySettleStep`'s abort branch, `applyExpireGate` below).
+// The ONE authorized addition to this function — every other line is byte-unchanged from PR-C.
+now) {
+    const { gateId, choice, evidence } = delta;
+    // Lookup FIRST (D3 §0.2 fail-safer-under-corruption; L21 ii: the own-commit may have already
+    // flipped terminal).
+    const hit = findSettledGateEntry(fresh, gateId);
+    if (hit !== undefined) {
+        if (hit.choice === choice) {
+            // Double-submit / two-gates delayed retry (TD F1) — same choice, idempotent no-op.
+            return { applied: false, reason: 'already_settled', run: fresh };
+        }
+        return {
+            applied: false,
+            reason: 'gate_choice_conflict',
+            run: fresh,
+            ...(hit.choice !== undefined ? { winningChoice: hit.choice } : {}),
+        };
+    }
+    // Zombie / stale submit — BEFORE the live-gate arm (matches the shipped `applySettleStep`
+    // terminal-first order `:215-217`, AND the live `submitHumanResponse` site's own terminal-first
+    // check `:3431`): a grandfathered terminal∧pending_gate record refuses run_terminal instead of
+    // resurrecting the run or falsely completing it.
+    if (isTerminal(fresh)) {
+        return { applied: false, reason: 'run_terminal', run: fresh };
+    }
+    if (fresh.pending_gate !== undefined && fresh.pending_gate.gate_id === gateId) {
+        // issue #291 ([F3] shape c, the expiry-WINS mechanism): a WRITE-FREE refusal when the live
+        // gate has expired unresolved AND has an enactable disposition (`on_expiry` frozen) —
+        // checked under the lock, with the injectable `now`, BEFORE choice_not_eligible. The caller
+        // (submitHumanResponse) reacts to this refusal by issuing its OWN `expire_gate` settleStep
+        // (this function never enacts anything itself — that stays applyExpireGate's job) and
+        // composing the honest envelope from the enactment result. This is exact-at-the-
+        // serialization-point-once-observed, uniform-fleet-only: a gate minted by an old binary (no
+        // `expires_at` frozen) can never trip this arm. The `on_expiry !== undefined` conjunct is
+        // load-bearing: a FINDING-ONLY gate (expires_at present, on_expiry absent) has NOTHING that
+        // could ever win this race — refusing the human here with no enactable disposition to
+        // compose an envelope from would strand the human's response forever (the exact
+        // undisposable dead-end this feature exists to cure), since expire_gate would just refuse
+        // `no_disposition` right back. A finding-only gate's human response always resolves
+        // normally, however overdue.
+        if (fresh.pending_gate.expires_at !== undefined &&
+            fresh.pending_gate.on_expiry !== undefined &&
+            now.getTime() >= new Date(fresh.pending_gate.expires_at).getTime()) {
+            return { applied: false, reason: 'gate_expired_pending', run: fresh };
+        }
+        if (!fresh.pending_gate.choices.includes(choice)) {
+            return {
+                applied: false,
+                reason: 'choice_not_eligible',
+                run: fresh,
+                choices: fresh.pending_gate.choices,
+            };
+        }
+        // APPLY RESOLVE: clear pending_gate; completed_steps += step_name; release claim +
+        // in_progress (execution-loop.ts:3519-3520 parity); settled[step] = {token: gateId,
+        // outcome:'gate', choice} — 'gate' LITERAL here, toSettledOutcome's own SettleStepOutcome
+        // domain stays untouched (§2).
+        const stepName = fresh.pending_gate.step_name;
+        const { pending_gate: _pg, ...rest } = fresh;
+        const withMembership = {
+            ...rest,
+            in_progress_steps: rest.in_progress_steps.filter((s) => s !== stepName),
+            claims: omitClaim(rest.claims, stepName),
+            completed_steps: [...rest.completed_steps, stepName],
+            evidence: [...rest.evidence, ...evidence],
+            settled: { ...rest.settled, [stepName]: { token: gateId, outcome: 'gate', choice } },
+        };
+        const propagated = propagateSkips(withMembership, definition);
+        const withSkipped = {
+            ...withMembership,
+            skipped_steps: propagated.skipped,
+            skip_details: propagated.details,
+        };
+        const isComplete = isWorkflowComplete(withSkipped, definition) ||
+            (withSkipped.in_progress_steps.length === 0 &&
+                findEligibleSteps(definition, withSkipped).length === 0 &&
+                findEligibleGuardSteps(definition, withSkipped).length === 0);
+        const draft = {
+            ...withSkipped,
+            terminal_state: isComplete,
+            // eligibility.ts:47 keys deriveRunPhase's 'completed' on this exact string.
+            ...(isComplete ? { terminal_reason: 'Workflow completed.' } : {}),
+        };
+        const { run, transitioned } = applyTerminalPostconditions(draft, definition, 'complete', isComplete);
+        return {
+            applied: true,
+            run,
+            transitioned,
+            pendingFinalizers: pendingFinalizerNames(run.finalizer_ledger),
+        };
+    }
+    // Superseded/unknown gateId on a live run.
+    return { applied: false, reason: 'gate_mismatch', run: fresh };
+}
+// ---------------------------------------------------------------------------
+// §3 expireGateArms (issue #291; design record `plans/issue-291/design-d2.md` [F1]/[F2]/[F3]/[F9])
+// — fence = gateId ONLY (mirrors settleGateArms — L20). Enacts a gate's FROZEN enforce-clock
+// disposition once expired-unresolved. Reads the RECORD only, never the workflow definition
+// (F2's whole point — kills the definition-drift livelock: a re-registered workflow's changed
+// `choices`/`default_choice` can never make an already-open gate's expiry refuse forever).
+// ---------------------------------------------------------------------------
+function applyExpireGate(fresh, delta, definition, now) {
+    const { gateId } = delta;
+    // Lookup FIRST ([F1] i; D3 §0.2 fail-safer-under-corruption — same order as settleGateArms).
+    const hit = findSettledGateEntry(fresh, gateId);
+    if (hit !== undefined) {
+        return { applied: false, reason: 'already_settled', run: fresh };
+    }
+    // Terminal split ([F1] iv, the replay/crash-recovery arm): a prior expire-abort enactment for
+    // THIS gateId already sealed the run — NOOP (idempotent replay). Any OTHER terminal cause
+    // (a different disposition, a concurrent human resolve that raced ahead, a handler-abort on a
+    // sibling) REFUSES run_terminal — never silently resurrect or re-terminalize.
+    if (isTerminal(fresh)) {
+        const expiredEntry = Object.entries(fresh.skip_details ?? {}).find(([, d]) => d.kind === 'gate_expired' && d.gate_id === gateId);
+        if (expiredEntry !== undefined) {
+            return { applied: false, reason: 'already_settled', run: fresh };
+        }
+        return { applied: false, reason: 'run_terminal', run: fresh };
+    }
+    // No/other pending_gate ([F1] iii) — superseded or unknown gateId on a live run. Mirrors
+    // settleGateArms's own final fallthrough exactly.
+    if (fresh.pending_gate === undefined || fresh.pending_gate.gate_id !== gateId) {
+        return { applied: false, reason: 'gate_mismatch', run: fresh };
+    }
+    const gate = fresh.pending_gate;
+    // now < expires_at ([F1] the new arm-verified refusal, NEVER trusting the caller's own clock):
+    // premature enactment attempt. Absent expires_at (a grandfathered/old-binary-minted gate, R-d)
+    // falls into this same refusal — it can never legitimately expire, so no in-contract caller
+    // should ever construct this delta for one; defensive rather than a crash either way.
+    if (gate.expires_at === undefined || now.getTime() < new Date(gate.expires_at).getTime()) {
+        return { applied: false, reason: 'not_expired', run: fresh };
+    }
+    // Finding-only mode (the prompt's own addendum, MA-ratified): timeout_seconds is present
+    // (expires_at exists) but on_expiry is absent — REFUSE no_disposition, arm-level, BEFORE APPLY.
+    // Never enacted; disclosed only via the run-health finding + the notifier's finding-only wording.
+    if (gate.on_expiry === undefined) {
+        return { applied: false, reason: 'no_disposition', run: fresh };
+    }
+    const respondedAt = now;
+    const stepName = gate.step_name;
+    if (gate.on_expiry === 'settle_default') {
+        // APPLY settle_default: reuses settleGateArms' own RESOLVE shape end-to-end (choice =
+        // FROZEN default_choice, clear gate, complete step, release claim, isComplete/terminalize) —
+        // written as its OWN independent implementation (settleGateArms itself stays byte-untouched
+        // beyond the F3 addition above), attributed `resolved_by: 'timeout'`.
+        const choice = gate.default_choice; // E2/[F10]-enforced at load: required-iff-settle_default.
+        const evidence = captureEvidence({
+            stepId: stepName,
+            startedAt: new Date(gate.opened_at),
+            completedAt: respondedAt,
+            input: { choice },
+            output: { ...gate.preview, choice },
+        });
+        const gateResponseSnapshot = {
+            ...evidence,
+            kind: 'gate_response',
+            ...(gate.resolved_message !== undefined ? { gate_message: gate.resolved_message } : {}),
+            responded_by: 'timeout',
+            resolution: 'expired_default',
+        };
+        const { pending_gate: _pg, ...rest } = fresh;
+        const withMembership = {
+            ...rest,
+            in_progress_steps: rest.in_progress_steps.filter((s) => s !== stepName),
+            claims: omitClaim(rest.claims, stepName),
+            completed_steps: [...rest.completed_steps, stepName],
+            evidence: [...rest.evidence, gateResponseSnapshot],
+            settled: {
+                ...rest.settled,
+                [stepName]: { token: gateId, outcome: 'gate', choice, resolved_by: 'timeout' },
+            },
+        };
+        const propagated = propagateSkips(withMembership, definition);
+        const withSkipped = {
+            ...withMembership,
+            skipped_steps: propagated.skipped,
+            skip_details: propagated.details,
+        };
+        const isComplete = isWorkflowComplete(withSkipped, definition) ||
+            (withSkipped.in_progress_steps.length === 0 &&
+                findEligibleSteps(definition, withSkipped).length === 0 &&
+                findEligibleGuardSteps(definition, withSkipped).length === 0);
+        const draft = {
+            ...withSkipped,
+            terminal_state: isComplete,
+            ...(isComplete ? { terminal_reason: 'Workflow completed.' } : {}),
+        };
+        const { run, transitioned } = applyTerminalPostconditions(draft, definition, 'complete', isComplete);
+        return {
+            applied: true,
+            run,
+            transitioned,
+            pendingFinalizers: pendingFinalizerNames(run.finalizer_ledger),
+        };
+    }
+    // APPLY abort (on_expiry === 'abort'): a NEW own-step arm — applyAbortEdge is sibling-only
+    // (its cancel-gate branch only fires for `pending_gate.step_name !== step`), so aborting the
+    // GATE'S OWN step needs its own shape: clear pending_gate + aborted_at + skip_details
+    // {kind:'gate_expired', gate_id} (day-one, F9) + mintFresh — in ONE write (TERMINAL_GATE_
+    // EXCLUSION: never leave BOTH a live pending_gate AND a settled 'gate' entry — this branch
+    // writes NEITHER a settled entry NOR a completed_steps membership; the step lands in
+    // skipped_steps instead, mirroring every other abort disposition in this file).
+    const evidence = captureEvidence({
+        stepId: stepName,
+        startedAt: new Date(gate.opened_at),
+        completedAt: respondedAt,
+        input: {},
+        output: { gate_expired: true, disposition: 'abort' },
+    });
+    const gateResponseSnapshot = {
+        ...evidence,
+        kind: 'gate_response',
+        ...(gate.resolved_message !== undefined ? { gate_message: gate.resolved_message } : {}),
+        responded_by: 'timeout',
+        resolution: 'expired_abort',
+    };
+    const { pending_gate: _pg2, ...withoutGate } = fresh;
+    const withSkippedSelf = {
+        ...withoutGate,
+        in_progress_steps: withoutGate.in_progress_steps.filter((s) => s !== stepName),
+        claims: omitClaim(withoutGate.claims, stepName),
+        skipped_steps: [...withoutGate.skipped_steps, stepName],
+        skip_details: {
+            ...withoutGate.skip_details,
+            [stepName]: { kind: 'gate_expired', gate_id: gateId },
+        },
+        evidence: [...withoutGate.evidence, gateResponseSnapshot],
+    };
+    const propagated = propagateSkips(withSkippedSelf, definition);
+    const withSkipped = {
+        ...withSkippedSelf,
+        skipped_steps: propagated.skipped,
+        skip_details: { ...propagated.details, [stepName]: { kind: 'gate_expired', gate_id: gateId } },
+    };
+    const aborted = {
+        ...withSkipped,
+        terminal_state: true,
+        terminal_reason: `Gate '${stepName}' expired and the run aborted per the workflow's declared on_expiry.`,
+        aborted_at: {
+            step_id: stepName,
+            abort_message: `Gate expired (timeout_seconds elapsed with no human response); on_expiry: 'abort'.`,
+        },
+    };
+    // §4 shared postconditions: abort NEVER stamps defaulted_steps (the FM-5/#232 guard);
+    // `transitioned` is always true (isTerminal(fresh) already refused above).
+    const { run, transitioned } = applyTerminalPostconditions(aborted, definition, 'abort', false);
+    return {
+        applied: true,
+        run,
+        transitioned,
+        pendingFinalizers: pendingFinalizerNames(run.finalizer_ledger),
+    };
+}
+// ---------------------------------------------------------------------------
+// §3 settleGuardArms (issue #279, increment 2, PR-C) — fence = ⊥ (guards are never claimed,
+// eligibility.ts:418); writes NO settled entry (SE-4).
+// ---------------------------------------------------------------------------
+function ownMembershipFor(fresh, outcome) {
+    switch (outcome) {
+        case 'pass':
+            return fresh.completed_steps;
+        case 'resolution_error':
+            return fresh.failed_steps;
+        case 'abort':
+            return fresh.skipped_steps;
+    }
+}
+function applySettleGuard(fresh, delta, definition) {
+    const { step, outcome, evidence, resolutionError, abort } = delta;
+    if (outcome === 'resolution_error' && resolutionError === undefined) {
+        // Caller-programming-error, not a predicate outcome (the SettleStepDelta abort precedent).
+        throw new Error(`applySettlement contract violation: settle_guard delta for step '${step}' has ` +
+            `outcome:'resolution_error' but no 'resolutionError' payload`);
+    }
+    if (outcome === 'abort' && abort === undefined) {
+        throw new Error(`applySettlement contract violation: settle_guard delta for step '${step}' has ` +
+            `outcome:'abort' but no 'abort' payload`);
+    }
+    // A := {pass: completed_steps, resolution_error: failed_steps, abort: skipped_steps} (lens-1 F8).
+    if (ownMembershipFor(fresh, outcome).includes(step)) {
+        if (outcome === 'abort' && fresh.skip_details?.[step]?.kind !== 'guard_abort') {
+            // In skipped_steps, but NOT via a prior guard_abort (e.g. when_false/trigger_rule_
+            // unsatisfiable instead) — a genuine divergence, not this guard's own convergent retry.
+            return {
+                applied: false,
+                reason: 'settled_outcome_divergence',
+                run: fresh,
+                persisted: 'skip-non-abort',
+            };
+        }
+        // Convergence on own-APPLY coordinates (L21) — idempotent retry.
+        return { applied: false, reason: 'already_settled', run: fresh };
+    }
+    // Any OTHER membership array already containing this step is a genuine divergence — a
+    // different settle already committed a DIFFERENT outcome for the same guard.
+    if (fresh.completed_steps.includes(step)) {
+        return {
+            applied: false,
+            reason: 'settled_outcome_divergence',
+            run: fresh,
+            persisted: 'complete',
+        };
+    }
+    if (fresh.failed_steps.includes(step)) {
+        return { applied: false, reason: 'settled_outcome_divergence', run: fresh, persisted: 'fail' };
+    }
+    if (fresh.skipped_steps.includes(step)) {
+        return { applied: false, reason: 'settled_outcome_divergence', run: fresh, persisted: 'skip' };
+    }
+    if (isTerminal(fresh)) {
+        return { applied: false, reason: 'run_terminal', run: fresh }; // terminal by OTHER
+    }
+    if (fresh.pending_gate !== undefined && outcome !== 'pass') {
+        // D-2: the GATE WINS; quiet end-of-pass — the guard re-evaluates at the NEXT drive (N8).
+        return { applied: false, reason: 'gate_open_wait', run: fresh };
+    }
+    // APPLY GUARD.
+    if (outcome === 'resolution_error') {
+        const withFailed = {
+            ...fresh,
+            evidence: [...fresh.evidence, evidence],
+            failed_steps: [...fresh.failed_steps, step],
+        };
+        const propagated = propagateSkips(withFailed, definition);
+        const withSkipped = {
+            ...withFailed,
+            skipped_steps: propagated.skipped,
+            skip_details: propagated.details,
+        };
+        const draft = {
+            ...withSkipped,
+            terminal_state: true,
+            // execution-loop.ts:3671 parity.
+            terminal_reason: `Guard step '${step}' failed: unresolvable path '${resolutionError.unresolvable_path}'`,
+        };
+        const { run, transitioned } = applyTerminalPostconditions(draft, definition, 'fail', false);
+        return {
+            applied: true,
+            run,
+            transitioned,
+            pendingFinalizers: pendingFinalizerNames(run.finalizer_ledger),
+        };
+    }
+    if (outcome === 'abort') {
+        const withSkippedSelf = {
+            ...fresh,
+            evidence: [...fresh.evidence, evidence],
+            skipped_steps: [...fresh.skipped_steps, step],
+        };
+        const propagated = propagateSkips(withSkippedSelf, definition);
+        const withSkipped = {
+            ...withSkippedSelf,
+            skipped_steps: propagated.skipped,
+            // #111: the merge preserves any cascade details for OTHER now-unreachable steps alongside
+            // this guard's own guard_abort tag (execution-loop.ts:3728-3735 parity).
+            skip_details: { ...propagated.details, [step]: { kind: 'guard_abort' } },
+        };
+        const draft = {
+            ...withSkipped,
+            terminal_state: true,
+            // terminal_reason ABSENT — phase 'aborted' derives from aborted_at (§4 table).
+            aborted_at: {
+                step_id: step,
+                conditions: abort.conditions,
+                ...(abort.abort_message !== undefined ? { abort_message: abort.abort_message } : {}),
+            },
+        };
+        const { run, transitioned } = applyTerminalPostconditions(draft, definition, 'abort', false);
+        return {
+            applied: true,
+            run,
+            transitioned,
+            pendingFinalizers: pendingFinalizerNames(run.finalizer_ledger),
+        };
+    }
+    // pass: two-disjunct isComplete predicate (same shape as settleStepArms's own).
+    const withCompleted = {
+        ...fresh,
+        evidence: [...fresh.evidence, evidence],
+        completed_steps: [...fresh.completed_steps, step],
+    };
+    const propagated = propagateSkips(withCompleted, definition);
+    const withSkipped = {
+        ...withCompleted,
+        skipped_steps: propagated.skipped,
+        skip_details: propagated.details,
+    };
+    const isComplete = isWorkflowComplete(withSkipped, definition) ||
+        (withSkipped.in_progress_steps.length === 0 &&
+            findEligibleSteps(definition, withSkipped).length === 0 &&
+            findEligibleGuardSteps(definition, withSkipped).length === 0);
+    const draft = {
+        ...withSkipped,
+        terminal_state: isComplete,
+        // execution-loop.ts:3675-3705 parity; eligibility.ts:47 keys deriveRunPhase's 'completed' on
+        // this exact string.
+        ...(isComplete ? { terminal_reason: 'Workflow completed.' } : {}),
+    };
+    const { run, transitioned } = applyTerminalPostconditions(draft, definition, 'complete', isComplete);
+    return {
+        applied: true,
+        run,
+        transitioned,
+        pendingFinalizers: pendingFinalizerNames(run.finalizer_ledger),
+    };
+}
+// ---------------------------------------------------------------------------
+// §3 releaseStepArms (issue #279, increment 2, PR-C) — fence = claimToken. NEVER terminal, writes
+// NO settled entry — the step returns to eligible.
+// ---------------------------------------------------------------------------
+function applyReleaseStep(fresh, delta, now) {
+    const { step, claimToken, capabilityBlock, evidence } = delta;
+    if (entryOf(fresh, step) !== undefined) {
+        return { applied: false, reason: 'already_settled_by_other', run: fresh };
+    }
+    if (isTerminal(fresh)) {
+        return { applied: false, reason: 'run_terminal', run: fresh };
+    }
+    const claim = fresh.claims?.[step];
+    if (claim === undefined) {
+        // TD F10: the claim is already gone — the RELEASE intent already holds. Idempotent no-op.
+        return { applied: false, reason: 'already_released', run: fresh };
+    }
+    if (!tokensEqual(claim.token, claimToken)) {
+        // Never stomp a successor's claim (execution-loop.ts:660-671 parity).
+        return { applied: false, reason: 'claim_lost', run: fresh };
+    }
+    if (fresh.pending_gate?.step_name === step) {
+        // reclaim-step.ts:389 parity — a claim pinned by an open gate is never released this way.
+        return { applied: false, reason: 'gate_mismatch', run: fresh };
+    }
+    // APPLY RELEASE: release claim + in_progress; optional capability_blocks merge
+    // (execution-loop.ts:2461-2475 semantics); optional evidence append (execution-loop.ts:679
+    // semantics — the compensating un-claim's own audit snapshot). NEVER terminal, NO settled entry.
+    const withRelease = {
+        ...fresh,
+        in_progress_steps: fresh.in_progress_steps.filter((s) => s !== step),
+        claims: omitClaim(fresh.claims, step),
+        ...(capabilityBlock !== undefined
+            ? {
+                capability_blocks: {
+                    ...fresh.capability_blocks,
+                    [step]: {
+                        requirement: capabilityBlock.requirement,
+                        code: capabilityBlock.code,
+                        at: now.toISOString(),
+                    },
+                },
+            }
+            : {}),
+        ...(evidence !== undefined ? { evidence: [...fresh.evidence, ...evidence] } : {}),
+    };
+    const run = { ...withRelease, run_phase: deriveRunPhase(withRelease) };
     return {
         applied: true,
-        run: withPhase,
-        transitioned: isComplete,
-        pendingFinalizers: pendingFinalizerNames(withPhase.finalizer_ledger),
+        run,
+        transitioned: false,
+        pendingFinalizers: pendingFinalizerNames(run.finalizer_ledger),
     };
 }
 // ---------------------------------------------------------------------------
@@ -409,6 +1031,37 @@ export function applySettlement(fresh, delta, definition, options) {
             return applyLeaseFinalizer(fresh, delta, now);
         case 'mark_finalizer':
             return applyMarkFinalizer(fresh, delta);
+        case 'open_gate':
+            return applyOpenGate(fresh, delta);
+        case 'settle_gate':
+            return applySettleGate(fresh, delta, definition, now);
+        case 'settle_guard':
+            return applySettleGuard(fresh, delta, definition);
+        case 'release_step':
+            return applyReleaseStep(fresh, delta, now);
+        case 'expire_gate':
+            return applyExpireGate(fresh, delta, definition, now);
     }
 }
+/**
+ * Named constant (issue #279, increment 2, PR-C; design record §4.3) tying reclaim-step.ts's own
+ * open-gate refusal (`reclaimStep`, ~line 389: "the claim is legitimately pinned by a human gate")
+ * to this design's "unfenced-release soundness rests on reclaim" premise. **Reworded (issue #291,
+ * [F6]):** the ORIGINAL text claimed `applyAbortEdge`'s cancel-gate write was "the ONLY path that
+ * may release an open gate's claim" — issue #291's `applyExpireGate` (both dispositions) ALSO
+ * releases it now, making that literal claim false. The invariant this constant actually protects
+ * — `reclaimStep`/`isAutoReclaimable` must NEVER release an open gate's claim, or a concurrent
+ * release could race and double-release the same claim — still holds exactly; the closed set of
+ * paths that MAY release it is now: `settle_step` abort's cancel-gate write (another step's
+ * handler-abort), and `expire_gate`'s settle_default/abort dispositions (the gate's OWN step,
+ * enforce-clock-driven) — all three live inside `applySettlement`, under the SAME store lock,
+ * which is exactly WHY they can never race `reclaimStep`'s own (separate) CAS write. Referenced
+ * (not asserted via) by this invariant's two existing pinning tests (`reclaim-step.test.ts` +
+ * the CLI's `reclaim.test.ts`) so a future reader can grep this name to find both, and
+ * reclaim-step.ts's own SOURCE stays untouched by this PR.
+ */
+export const RECLAIM_REFUSES_GATE_STEP = 'reclaim never releases the open-gate claim (design record design-d5-increment2.md §4.3 + ' +
+    'issue #291 design-d2.md [F6], unfenced-release soundness — the closed set: settle_step abort ' +
+    "(another step), expire_gate settle_default/abort (the gate's own step), all inside " +
+    'applySettlement under the same lock)';
 //# sourceMappingURL=settlement.js.map