@sensigo/realm 0.38.0 → 0.40.0

package/dist/engine/execution-loop.js

@@ -5,7 +5,7 @@ import { storeDeclaresSeal, storeDeclaresNonceCarriage } from '../store/trace-bu
 import { partitionBufferedEntries } from './trace-adoption.js';
 import { deriveDefaultedSteps } from './defaulted-steps.js';
 import { computeGateDueState } from './gate-timing.js';
-import { selectFinalizers, deriveEffectiveTriggers, applySettlement } from './settlement.js';
+import { selectFinalizers, deriveEffectiveTriggers, applySettlement, renderFailCause, failureMessagesFromEvidence, failureMessagesWithOverlay, } from './settlement.js';
 import { captureEvidence } from '../evidence/snapshot.js';
 import { validateInputSchema, validateOutputSchema, validateTraceSchema, } from '../validation/input-schema.js';
 import { normalizeTrace } from './trace-normalizer.js';
@@ -18,7 +18,7 @@ import { createDefaultRegistry } from '../extensions/default-registry.js';
 import { renderTemplate, resolvePath, UnknownFilterError } from './render-template.js';
 import { generateSchemaSkeleton } from '../utils/schema-skeleton.js';
 import { loadWorkflowContext } from './workflow-context-loader.js';
-import { findEligibleSteps, findEligibleGuardSteps, isWorkflowComplete, buildEvidenceByStep, propagateSkips, deriveRunPhase, } from './eligibility.js';
+import { findEligibleSteps, findEligibleGuardSteps, isWorkflowComplete, buildEvidenceByStep, propagateSkips, deriveRunPhase, armToOutcome, assertSealMarkersAgree, } from './eligibility.js';
 import { requirementForStep } from './capability.js';
 import { resolvePreExecutionAgentAction, resolvePostDispatchAgentAction, } from './error-resolution.js';
 function delayMs(ms) {
@@ -370,7 +370,12 @@ function stepToNextAction(stepName, step, context) {
             : {}),
         human_readable: `Execute step '${stepName}': ${step.description}`,
         orientation: `Run is active. Next step ready: '${stepName}'.`,
-        ...(step.timeout_seconds !== undefined ? { expected_timeout: `${step.timeout_seconds}s` } : {}),
+        // issue #412: the `expected_timeout` display is GONE, not scoped. It rendered wherever a
+        // NextAction was built — agent steps, and handler-bearing steps of any kind — and on both
+        // the instructed action is outside anything that enforced the number: an agent step's
+        // dispatch is never wrapped in a timeout, and a handler NextAction tells the reader to call
+        // the handler themselves, which no withTimeout covers. A displayed bound that never governs
+        // the action it is displayed beside is worse than no display.
         ...(resolvedPrompt !== undefined ? { prompt: resolvedPrompt } : {}),
     };
 }
@@ -1764,6 +1769,8 @@ export async function executeStep(store, definition, options) {
                     const abortDraft = {
                         ...withAllSkipped,
                         terminal_state: true,
+                        // issue #367: the seal fields live in the SAME object literal as the terminal flip.
+                        sealed_by: { arm: 'handler_abort', step: options.command },
                         terminal_reason: `Handler '${options.command}' aborted the run: ${abortMessage}`,
                         aborted_at: {
                             step_id: options.command,
@@ -2394,14 +2401,34 @@ export async function executeStep(store, definition, options) {
             (withSkippedFail.in_progress_steps.length === 0 &&
                 findEligibleSteps(definition, withSkippedFail).length === 0 &&
                 findEligibleGuardSteps(definition, withSkippedFail).length === 0);
-        const failDraft = {
-            ...withSkippedFail,
-            evidence: [...pendingRun.evidence, ...allEvidence],
-            terminal_state: isComplete,
-            ...(isComplete
-                ? { terminal_reason: `Step '${options.command}' failed: ${dispatchError.message}` }
-                : {}),
-        };
+        // Hoisted so the #373 message walk below reads the SAME evidence the record will carry —
+        // `withSkippedFail` does not yet include this attempt's snapshots.
+        const failEvidence = [...pendingRun.evidence, ...allEvidence];
+        // issue #373 — twin of settlement.ts's fail seal; both layers must emit byte-identical
+        // sentences for identical inputs. Single-failure shape unchanged (this site has never had the
+        // `?? 'unknown error'` fallback — `dispatchError.message` is always a string).
+        const failCause = new Set(withSkippedFail.failed_steps).size > 1
+            ? renderFailCause(withSkippedFail.failed_steps, failureMessagesWithOverlay(failEvidence, options.command, dispatchError.message))
+            : `Step '${options.command}' failed: ${dispatchError.message}`;
+        // issue #367: seal fields staged FIRST in the SAME object literal, and a stale prior seal
+        // never survives either fork. #373's `failCause` (computed above) is untouched — the arm sits
+        // BESIDE the rendered sentence, never inside it. Validation exhaustion is deliberately NOT a
+        // distinct arm: a VALIDATION_EXHAUSTED failure seals 'step_failure' like any other terminal
+        // step failure, and the distinction lives in defaulted_steps/diagnostics.
+        const { sealed_by: _priorFailSeal, ...withSkippedFailBase } = withSkippedFail;
+        const failDraft = isComplete
+            ? {
+                ...withSkippedFailBase,
+                terminal_state: true,
+                sealed_by: { arm: 'step_failure', step: options.command },
+                evidence: failEvidence,
+                terminal_reason: failCause,
+            }
+            : {
+                ...withSkippedFailBase,
+                terminal_state: false,
+                evidence: failEvidence,
+            };
         // On the terminal transition, drain the fail/always finalizers before the single seal.
         // Non-terminal failures (recovery steps remain) run no finalizers.
         const failedRun = isComplete
@@ -2979,11 +3006,16 @@ export async function executeStep(store, definition, options) {
         (withSkippedComplete.in_progress_steps.length === 0 &&
             findEligibleSteps(definition, withSkippedComplete).length === 0 &&
             findEligibleGuardSteps(definition, withSkippedComplete).length === 0);
-    const completeDraft = {
-        ...withSkippedComplete,
-        terminal_state: isComplete,
-        ...(isComplete ? { terminal_reason: `Workflow completed.` } : {}),
-    };
+    // issue #367: seal fields staged first in the SAME object literal; stale prior seal stripped.
+    const { sealed_by: _priorCompleteSeal, ...withSkippedCompleteBase } = withSkippedComplete;
+    const completeDraft = isComplete
+        ? {
+            ...withSkippedCompleteBase,
+            terminal_state: true,
+            sealed_by: { arm: 'complete', step: options.command },
+            terminal_reason: `Workflow completed.`,
+        }
+        : { ...withSkippedCompleteBase, terminal_state: false };
     // On the terminal transition, drain the complete/always finalizers before the single seal.
     // issue #220 PR-2 (D6): stamp defaulted_steps onto the SEALED terminal record only — the
     // non-terminal branch (`completeDraft`) is never stamped (FM-5 guard: it must never leak onto a
@@ -3244,7 +3276,7 @@ async function composeExpiredGateEnvelope(store, definition, registry, originalG
     // — never attribute the outcome to THIS gate's expiry (no matched entry exists to attribute it
     // to), and never claim "expired" at all, since nothing here witnessed this gate expiring.
     const err = new WorkflowError(`Gate '${originalGateId}': the run reached a terminal outcome concurrently — your choice ` +
-        `was NOT recorded. 'realm resume' clears a stale pending gate on a resumable run, or ` +
+        `was NOT recorded. 'realm run resume' clears a stale pending gate on a resumable run, or ` +
         `'realm run purge' removes the record entirely.`, {
         code: 'STATE_RUN_TERMINAL',
         category: 'STATE',
@@ -3454,7 +3486,7 @@ export async function submitHumanResponse(store, definition, options) {
                     // Zombie/grandfathered variant — the #282 class: a terminal record may still carry a
                     // stale pending_gate (never cleared), which is the best-effort step label here.
                     const zombieStep = result.run.pending_gate?.step_name ?? 'submit_gate';
-                    const err = new WorkflowError(`Run '${options.runId}' is terminal; cannot submit a gate response — 'realm resume' ` +
+                    const err = new WorkflowError(`Run '${options.runId}' is terminal; cannot submit a gate response — 'realm run resume' ` +
                         `clears a stale pending gate on a resumable run, or 'realm run purge' removes the ` +
                         `record entirely.`, {
                         code: 'STATE_RUN_TERMINAL',
@@ -3619,7 +3651,11 @@ export async function submitHumanResponse(store, definition, options) {
             ? { gate_message: run.pending_gate.resolved_message }
             : {}),
     };
-    const { pending_gate: _pg, terminal_reason: _tr, ...rest } = run;
+    // issue #367: `sealed_by` joins the strip list — this write re-derives the run's liveness from
+    // scratch, so a stale seal (a grandfathered/mixed-fleet record) must not survive it. The
+    // explicit `terminal_state: false` below keeps the strip inside the store boundary's ORPHANED
+    // exemption: a strip site flips non-terminal in the SAME write.
+    const { pending_gate: _pg, terminal_reason: _tr, sealed_by: _sb, ...rest } = run;
     const afterGate = {
         ...rest,
         in_progress_steps: rest.in_progress_steps.filter((s) => s !== gateStepName),
@@ -3643,11 +3679,16 @@ export async function submitHumanResponse(store, definition, options) {
         (withSkippedGate.in_progress_steps.length === 0 &&
             findEligibleSteps(definition, withSkippedGate).length === 0 &&
             findEligibleGuardSteps(definition, withSkippedGate).length === 0);
-    const gateDraft = {
-        ...withSkippedGate,
-        terminal_state: isComplete,
-        ...(isComplete ? { terminal_reason: `Workflow completed.` } : {}),
-    };
+    // issue #367: seal fields staged first (the prior seal was already stripped at the `afterGate`
+    // construction above, so this fork starts clean by construction).
+    const gateDraft = isComplete
+        ? {
+            ...withSkippedGate,
+            terminal_state: true,
+            sealed_by: { arm: 'gate_resolution_complete', step: gateStepName },
+            terminal_reason: `Workflow completed.`,
+        }
+        : { ...withSkippedGate, terminal_state: false };
     // On the gate-completion terminal transition, drain complete/always finalizers before seal.
     // issue #220 PR-2 (D6): stamp defaulted_steps onto the SEALED terminal record only (never the
     // non-terminal `gateDraft` — the FM-5 guard).
@@ -3736,7 +3777,19 @@ async function executeGuardStep(stepName, stepDef, definition, run) {
             completedAt: now,
             input: {},
             output: { error: `Unresolvable path: ${outcome.unresolvable_path}` },
-            error: `Guard resolution error on condition: ${outcome.condition}`,
+            // issue #373 correction: the path is the DIAGNOSTIC, and it used to live only in
+            // `output_summary` + a transient seal-time overlay — so the post-drain re-render, which
+            // rebuilds the cause from evidence alone, replaced it with the generic condition text.
+            // Carrying it here makes every downstream read of this failure lossless. Sole production
+            // mint: the settlement delta reuses this exact snapshot via `guardOwnEvidence`.
+            //
+            // The path goes FIRST because the per-message cap slices from the head: with the path last,
+            // a long enough condition pushed it off the tail and the diagnostic vanished again. Honest
+            // bound: a pathological PATH over ~230 chars still truncates itself, which is accepted —
+            // head-first truncation keeps its prefix, and the prefix is the orienting part. ASCII
+            // parenthetical, not an em dash, for the same reason the truncation marker is ASCII (logs,
+            // terminals, a Postgres text column) — and a cut-off parenthetical reads as obviously partial.
+            error: `Guard resolution error: unresolvable path '${outcome.unresolvable_path}' (condition: ${outcome.condition})`,
         });
         const withFailed = {
             ...run,
@@ -3749,10 +3802,18 @@ async function executeGuardStep(stepName, stepDef, definition, run) {
             skipped_steps: resolutionErrorPropagated.skipped,
             skip_details: resolutionErrorPropagated.details,
         };
+        // issue #373 — twin of settlement.ts's guard seal. The overlay is DEFENSIVE once evidence
+        // carries the path (issue #373 correction, the `error` above); kept against caller-shaped
+        // evidence that arrives without it.
+        const guardPath = `unresolvable path '${outcome.unresolvable_path}'`;
         return {
             ...withSkipped,
             terminal_state: true,
-            terminal_reason: `Guard step '${stepName}' failed: unresolvable path '${outcome.unresolvable_path}'`,
+            // issue #367: the arm sits BESIDE #373's rendered sentence, never inside it.
+            sealed_by: { arm: 'guard_resolution_error', step: stepName },
+            terminal_reason: new Set(withSkipped.failed_steps).size > 1
+                ? renderFailCause(withSkipped.failed_steps, failureMessagesWithOverlay(withSkipped.evidence, stepName, guardPath))
+                : `Guard step '${stepName}' failed: ${guardPath}`,
         };
     }
     if (outcome.kind === 'pass') {
@@ -3779,11 +3840,16 @@ async function executeGuardStep(stepName, stepDef, definition, run) {
             (withSkipped.in_progress_steps.length === 0 &&
                 findEligibleSteps(definition, withSkipped).length === 0 &&
                 findEligibleGuardSteps(definition, withSkipped).length === 0);
-        return {
-            ...withSkipped,
-            terminal_state: isComplete,
-            ...(isComplete ? { terminal_reason: 'Workflow completed.' } : {}),
-        };
+        // issue #367: the stamp lives INSIDE the isComplete arm ONLY — a non-terminal guard pass must
+        // never carry a seal.
+        return isComplete
+            ? {
+                ...withSkipped,
+                terminal_state: true,
+                sealed_by: { arm: 'guard_pass_complete', step: stepName },
+                terminal_reason: 'Workflow completed.',
+            }
+            : { ...withSkipped, terminal_state: false };
     }
     // Guard fired — one or more conditions false; abort the run.
     const evidenceEntry = captureEvidence({
@@ -3816,6 +3882,10 @@ async function executeGuardStep(stepName, stepDef, definition, run) {
     return {
         ...withAllSkipped,
         terminal_state: true,
+        // issue #367: same object literal as the terminal flip. terminal_reason stays ABSENT here (a
+        // guard abort is the one reason-less seal) — the phase now derives from the arm, and
+        // `aborted_at` is asserted congruent rather than consulted.
+        sealed_by: { arm: 'guard_abort', step: stepName },
         aborted_at: {
             step_id: stepName,
             conditions: outcome.conditions,
@@ -3841,8 +3911,10 @@ async function executeGuardStep(stepName, stepDef, definition, run) {
  * `withTimeout` honoring `timeout_seconds` (default `DRAIN_CEILING_SECONDS`). Success →
  * evidence + completed_steps; thrown error / STEP_TIMEOUT / handler `{ abort }` → evidence
  * marked failed + failed_steps, NON-FATAL (the drain continues). A finalizer NEVER mutates
- * `aborted_at`, `terminal_reason`, `terminal_state`, `skipped_steps`, or emits next_actions —
- * the terminal marks come from `sealDraft` and `deriveRunPhase` precedence keeps the phase.
+ * `aborted_at`, `terminal_state`, `skipped_steps`, or emits next_actions, and never changes the
+ * sealed OUTCOME — the terminal marks come from `sealDraft` and `deriveRunPhase` precedence keeps
+ * the phase. issue #373: a finalizer whose OWN failure grows `failed_steps` on a fail-class seal
+ * DOES re-render `terminal_reason`, so the one-line cause keeps agreeing with the record.
  */
 async function buildFinalizedSeal(definition, sealDraft, outcome, registry) {
     // Zero-finalizer fast path: no finalizer steps declared ⇒ return the seal draft
@@ -3858,6 +3930,13 @@ async function buildFinalizedSeal(definition, sealDraft, outcome, registry) {
     // legacy seal path for a non-declaring external store (the dormancy fallback).
     const settled = new Set([...sealDraft.completed_steps, ...sealDraft.failed_steps]);
     const selected = selectFinalizers(definition, settled, deriveEffectiveTriggers(outcome, sealDraft));
+    // issue #367: the draft already carries sealed_by (every caller stamps at construction), so the
+    // fast path above can never bypass the stamp.
+    // issue #373: the post-drain re-render fires only if the drain ACTUALLY appended a failure.
+    // The legacy seal is reached on every fail-class outcome, including one where every finalizer
+    // succeeds — re-rendering there would rebuild the sentence without the seal site's in-hand
+    // overlay (the guard sites' unresolvable-path text) and silently drop it.
+    const failedBeforeDrain = sealDraft.failed_steps.length;
     let record = sealDraft;
     for (const name of selected) {
         const step = definition.steps[name];
@@ -3876,8 +3955,10 @@ async function buildFinalizedSeal(definition, sealDraft, outcome, registry) {
         try {
             const result = await withTimeout((signal) => callHandler(step, options, record, evidenceByStep, signal), timeoutMs, name);
             if (result.kind === 'abort') {
-                // A finalizer handler returning { abort } is a recorded NON-FATAL failure — it must
-                // never mutate aborted_at/terminal_reason (that would corrupt the sealed outcome).
+                // A finalizer handler returning { abort } is a recorded NON-FATAL failure — it must never
+                // mutate aborted_at or the sealed OUTCOME. (issue #373: it does join `failed_steps`, and
+                // the post-drain re-render below folds it into the one-line cause — that reports the
+                // outcome faithfully, it does not change it.)
                 record = {
                     ...record,
                     evidence: [
@@ -3932,7 +4013,44 @@ async function buildFinalizedSeal(definition, sealDraft, outcome, registry) {
             };
         }
     }
-    return { ...record, terminal_state: true };
+    // issue #367: `sealed_by` is INHERITED from sealDraft, never re-derived here — a finalizer never
+    // changes which arm sealed the run, and re-deriving from `outcome` would re-couple the arm to
+    // mintOutcome, the exact coupling the recorded fact exists to break. `sealDraft` is terminal at
+    // every call site (all of them sit inside an isComplete/abort branch), so this narrow is total;
+    // it throws rather than fabricating an arm if a future caller violates that.
+    if (sealDraft.terminal_state !== true) {
+        throw new Error('buildFinalizedSeal called with a non-terminal sealDraft');
+    }
+    // Conditional spread, NOT `sealed_by: sealDraft.sealed_by`: under the flat optional plus
+    // exactOptionalPropertyTypes the unconditional form does not compile. An unstamped draft passes
+    // through honest-absent, and refusing it is the store boundary's job.
+    /* eslint-disable-next-line no-restricted-syntax --
+     * issue #367 (part 2), AUTHORIZED: the stamp IS in this literal, as a conditional spread —
+     * `exactOptionalPropertyTypes` forbids the unconditional `sealed_by: sealDraft.sealed_by` form,
+     * and a spread is not a `sealed_by` Property the selector can see. An unstamped draft passes
+     * through honest-absent on purpose; refusing it is the store boundary's job, per the comment
+     * directly above.
+     */
+    const drained = {
+        ...record,
+        terminal_state: true,
+        ...(sealDraft.sealed_by !== undefined ? { sealed_by: sealDraft.sealed_by } : {}),
+    };
+    // issue #367: SEAL_MARKERS_AGREE — transform-scoped assertion on the record THIS function
+    // produces (the second of the two transform homes; never universal).
+    assertSealMarkersAgree(drained);
+    // Twin of applyMarkFinalizer's failed-arm re-render. `deriveRunPhase`, not `outcome`: an aborted
+    // run whose finalizer also failed keeps its abort sentence (aborted_at wins), and a
+    // complete-outcome run keeps the complete-seal literal untouched.
+    if (record.failed_steps.length > failedBeforeDrain &&
+        deriveRunPhase(drained) === 'failed' &&
+        new Set(record.failed_steps).size > 1) {
+        return {
+            ...drained,
+            terminal_reason: renderFailCause(record.failed_steps, failureMessagesFromEvidence(record.evidence)),
+        };
+    }
+    return drained;
 }
 /** Every currently-`'pending'` finalizer in `run`'s ledger, ascending by rank — the order the
  *  drain loop below consumes (design record §6). */
@@ -4412,13 +4530,30 @@ depth0Warnings) {
         // (terminal_reason 'Workflow completed.', no aborted_at). `aborted_at ? 'abort' : 'fail'`
         // would wrongly run the catch finalizers on that success. When terminal, drain the
         // matching finalizers before the single seal write; non-terminal guard passes persist as-is.
-        const guardOutcome = guardResult.terminal_state
+        const guardProse = guardResult.terminal_state
             ? guardResult.aborted_at !== undefined
                 ? 'abort'
                 : guardResult.terminal_reason === 'Workflow completed.'
                     ? 'complete'
                     : 'fail'
             : undefined;
+        // issue #367: this classifier stays the PRODUCER of guardOutcome (it feeds buildFinalizedSeal,
+        // so a wrong answer here silently drains the wrong finalizers — the executed harm). It now
+        // prefers the RECORDED arm, keeps the prose branch as the fallback for an unstamped record,
+        // and throws if the two disagree: a future writer gap here is loud, never a silent loss.
+        const guardArmOutcome = guardResult.terminal_state && guardResult.sealed_by !== undefined
+            ? armToOutcome(guardResult.sealed_by.arm)
+            : undefined;
+        if (guardArmOutcome === 'abandon') {
+            throw new Error(`guard seal on '${guardName}' produced a non-guard arm`);
+        }
+        if (guardArmOutcome !== undefined &&
+            guardProse !== undefined &&
+            guardArmOutcome !== guardProse) {
+            throw new Error(`sealed_by.arm (${guardArmOutcome}) disagrees with the prose classifier (${guardProse}) ` +
+                `on guard '${guardName}'`);
+        }
+        const guardOutcome = guardArmOutcome ?? guardProse;
         // issue #220 PR-2 (D6): stamp defaulted_steps ONLY on the 'complete' seal — a guard that FAILS
         // or ABORTS the run does not get the qualifier (the FM-5 guard: never on a non-complete
         // terminal, and never on the non-terminal `guardResult` passthrough).