@exaudeus/workrail 0.11.0 → 0.13.0

package/dist/mcp/handlers/v2-execution.js

@@ -0,0 +1,1044 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.handleV2StartWorkflow = handleV2StartWorkflow;
+exports.handleV2ContinueWorkflow = handleV2ContinueWorkflow;
+const os = __importStar(require("os"));
+const crypto_1 = require("crypto");
+const types_js_1 = require("../types.js");
+const output_schemas_js_1 = require("../output-schemas.js");
+const snapshot_state_js_1 = require("../../v2/durable-core/projections/snapshot-state.js");
+const step_instance_key_js_1 = require("../../v2/durable-core/schemas/execution-snapshot/step-instance-key.js");
+const index_js_1 = require("../../v2/durable-core/tokens/index.js");
+const index_js_2 = require("../../v2/durable-core/tokens/index.js");
+const workflow_js_1 = require("../../types/workflow.js");
+const index_js_3 = require("../../v2/durable-core/ids/index.js");
+const neverthrow_1 = require("neverthrow");
+const v1_to_v2_shim_js_1 = require("../../v2/read-only/v1-to-v2-shim.js");
+const hashing_js_1 = require("../../v2/durable-core/canonical/hashing.js");
+const jcs_js_1 = require("../../v2/durable-core/canonical/jcs.js");
+const constants_js_1 = require("../../v2/durable-core/constants.js");
+const notes_markdown_js_1 = require("../../v2/durable-core/domain/notes-markdown.js");
+const outputs_js_1 = require("../../v2/durable-core/domain/outputs.js");
+const ack_advance_append_plan_js_1 = require("../../v2/durable-core/domain/ack-advance-append-plan.js");
+const workflow_source_js_1 = require("../../types/workflow-source.js");
+const workflow_definition_js_1 = require("../../types/workflow-definition.js");
+const workflow_compiler_js_1 = require("../../application/services/workflow-compiler.js");
+const workflow_interpreter_js_1 = require("../../application/services/workflow-interpreter.js");
+const v2_execution_helpers_js_1 = require("./v2-execution-helpers.js");
+function normalizeTokenErrorMessage(message) {
+    return message.split(os.homedir()).join('~');
+}
+const MAX_CONTEXT_BYTES_V2 = constants_js_1.MAX_CONTEXT_BYTES;
+function validateJsonValueOrIssue(value, path, depth, seen) {
+    if (depth > constants_js_1.MAX_CONTEXT_DEPTH)
+        return { kind: 'too_deep', path, maxDepth: constants_js_1.MAX_CONTEXT_DEPTH };
+    if (value === null)
+        return null;
+    const t = typeof value;
+    if (t === 'string' || t === 'boolean')
+        return null;
+    if (t === 'number') {
+        if (!Number.isFinite(value)) {
+            return { kind: 'non_finite_number', path, value: String(value) };
+        }
+        return null;
+    }
+    if (t === 'object') {
+        if (Array.isArray(value)) {
+            if (seen.has(value))
+                return { kind: 'circular_reference', path };
+            seen.add(value);
+            for (let i = 0; i < value.length; i++) {
+                const child = validateJsonValueOrIssue(value[i], `${path}[${i}]`, depth + 1, seen);
+                if (child)
+                    return child;
+            }
+            return null;
+        }
+        if (seen.has(value))
+            return { kind: 'circular_reference', path };
+        seen.add(value);
+        for (const [k, v] of Object.entries(value)) {
+            const child = validateJsonValueOrIssue(v, path === '$' ? `$.${k}` : `${path}.${k}`, depth + 1, seen);
+            if (child)
+                return child;
+        }
+        return null;
+    }
+    return { kind: 'unsupported_value', path, valueType: t };
+}
+function checkContextBudget(args) {
+    if (args.context === undefined)
+        return { ok: true };
+    if (typeof args.context !== 'object' || args.context === null || Array.isArray(args.context)) {
+        const details = {
+            kind: 'context_invalid_shape',
+            tool: args.tool,
+            expected: 'object',
+        };
+        return {
+            ok: false,
+            error: (0, types_js_1.errNotRetryable)('VALIDATION_ERROR', `context must be a JSON object for ${args.tool}.`, {
+                suggestion: 'Pass context as an object of external inputs (e.g., {"ticketId":"...","repoPath":"..."}). Do not pass arrays or primitives.',
+                details,
+            }),
+        };
+    }
+    const contextObj = args.context;
+    const issue = validateJsonValueOrIssue(contextObj, '$', 0, new WeakSet());
+    if (issue) {
+        const details = (() => {
+            switch (issue.kind) {
+                case 'unsupported_value':
+                    return {
+                        kind: 'context_unsupported_value',
+                        tool: args.tool,
+                        path: issue.path,
+                        valueType: issue.valueType,
+                    };
+                case 'non_finite_number':
+                    return {
+                        kind: 'context_non_finite_number',
+                        tool: args.tool,
+                        path: issue.path,
+                        value: issue.value,
+                    };
+                case 'circular_reference':
+                    return {
+                        kind: 'context_circular_reference',
+                        tool: args.tool,
+                        path: issue.path,
+                    };
+                case 'too_deep':
+                    return {
+                        kind: 'context_too_deep',
+                        tool: args.tool,
+                        path: issue.path,
+                        maxDepth: issue.maxDepth,
+                    };
+                default: {
+                    const _exhaustive = issue;
+                    return {
+                        kind: 'context_invalid_shape',
+                        tool: args.tool,
+                        expected: 'object',
+                    };
+                }
+            }
+        })();
+        return {
+            ok: false,
+            error: (0, types_js_1.errNotRetryable)('VALIDATION_ERROR', normalizeTokenErrorMessage(`context is not JSON-serializable for ${args.tool} (see details).`), {
+                suggestion: 'Remove non-JSON values (undefined/functions/symbols), circular references, and non-finite numbers. Keep context to plain JSON objects/arrays/primitives only.',
+                details: details,
+            }),
+        };
+    }
+    const canonicalRes = (0, jcs_js_1.toCanonicalBytes)(contextObj);
+    if (canonicalRes.isErr()) {
+        const details = {
+            kind: 'context_not_canonical_json',
+            tool: args.tool,
+            measuredAs: 'jcs_utf8_bytes',
+            code: canonicalRes.error.code,
+            message: canonicalRes.error.message,
+        };
+        const suggestion = canonicalRes.error.code === 'CANONICAL_JSON_NON_FINITE_NUMBER'
+            ? 'Remove NaN/Infinity/-Infinity from context. Canonical JSON forbids non-finite numbers.'
+            : 'Ensure context contains only JSON primitives, arrays, and objects (no undefined/functions/symbols).';
+        return {
+            ok: false,
+            error: (0, types_js_1.errNotRetryable)('VALIDATION_ERROR', normalizeTokenErrorMessage(`context cannot be canonicalized for ${args.tool}: ${canonicalRes.error.code}`), {
+                suggestion,
+                details,
+            }),
+        };
+    }
+    const measuredBytes = canonicalRes.value.length;
+    if (measuredBytes > MAX_CONTEXT_BYTES_V2) {
+        const details = {
+            kind: 'context_budget_exceeded',
+            tool: args.tool,
+            measuredBytes,
+            maxBytes: MAX_CONTEXT_BYTES_V2,
+            measuredAs: 'jcs_utf8_bytes',
+        };
+        return {
+            ok: false,
+            error: (0, types_js_1.errNotRetryable)('VALIDATION_ERROR', `context is too large for ${args.tool}: ${measuredBytes} bytes (max ${MAX_CONTEXT_BYTES_V2}). Size is measured as UTF-8 bytes of RFC 8785 (JCS) canonical JSON.`, {
+                suggestion: 'Remove large blobs from context (docs/logs/diffs). Pass references instead (file paths, IDs, hashes). If you must include text, include only the minimal excerpt, then retry.',
+                details,
+            }),
+        };
+    }
+    return { ok: true };
+}
+function isInternalError(e) {
+    if (typeof e !== 'object' || e === null || !('kind' in e))
+        return false;
+    const kind = e.kind;
+    return (kind === 'missing_node_or_run' ||
+        kind === 'workflow_hash_mismatch' ||
+        kind === 'missing_snapshot' ||
+        kind === 'no_pending_step' ||
+        kind === 'invariant_violation' ||
+        kind === 'advance_apply_failed' ||
+        kind === 'advance_next_failed');
+}
+function mapInternalErrorToToolError(e) {
+    switch (e.kind) {
+        case 'missing_node_or_run':
+            return (0, types_js_1.errNotRetryable)('PRECONDITION_FAILED', 'No durable run/node state was found for this stateToken. Advancement cannot be recorded.', { suggestion: 'Use a stateToken returned by WorkRail for an existing run/node.' });
+        case 'workflow_hash_mismatch':
+            return (0, types_js_1.errNotRetryable)('TOKEN_WORKFLOW_HASH_MISMATCH', 'workflowHash mismatch for this node.', { suggestion: 'Use the stateToken returned by WorkRail for this node.' });
+        case 'missing_snapshot':
+        case 'no_pending_step':
+            return internalError('Incomplete execution state.', 'Retry; if this persists, treat as invariant violation.');
+        case 'invariant_violation':
+            return internalError(normalizeTokenErrorMessage(e.message), 'Treat as invariant violation.');
+        case 'advance_apply_failed':
+        case 'advance_next_failed':
+            return internalError(normalizeTokenErrorMessage(e.message), 'Retry; if this persists, treat as invariant violation.');
+        default:
+            const _exhaustive = e;
+            return internalError('Unknown internal error kind', 'Treat as invariant violation.');
+    }
+}
+function replayFromRecordedAdvance(args) {
+    const { recordedEvent, truth, sessionId, runId, nodeId, workflowHash, attemptId, inputStateToken, inputAckToken, pinnedWorkflow, snapshotStore, keyring, hmac, base64url, } = args;
+    const checkpointTokenRes = signTokenOrErr({
+        unsignedPrefix: 'chk.v1.',
+        payload: { tokenVersion: 1, tokenKind: 'checkpoint', sessionId, runId, nodeId, attemptId },
+        keyring,
+        hmac,
+        base64url,
+    });
+    if (checkpointTokenRes.isErr()) {
+        return (0, neverthrow_1.errAsync)({ kind: 'token_signing_failed', cause: checkpointTokenRes.error });
+    }
+    const checkpointToken = checkpointTokenRes.value;
+    if (recordedEvent.data.outcome.kind === 'blocked') {
+        const blockers = recordedEvent.data.outcome.blockers;
+        const snapNode = truth.events.find((e) => e.kind === 'node_created' && e.scope?.nodeId === String(nodeId));
+        const snapRA = snapNode
+            ? snapshotStore.getExecutionSnapshotV1(snapNode.data.snapshotRef).mapErr((cause) => ({ kind: 'snapshot_load_failed', cause }))
+            : (0, neverthrow_1.okAsync)(null);
+        return snapRA.map((snap) => {
+            const pendingNow = snap ? (0, snapshot_state_js_1.derivePendingStep)(snap.enginePayload.engineState) : null;
+            const isCompleteNow = snap ? (0, snapshot_state_js_1.deriveIsComplete)(snap.enginePayload.engineState) : false;
+            return output_schemas_js_1.V2ContinueWorkflowOutputSchema.parse({
+                kind: 'blocked',
+                stateToken: inputStateToken,
+                ackToken: inputAckToken,
+                checkpointToken,
+                isComplete: isCompleteNow,
+                pending: pendingNow
+                    ? { stepId: String(pendingNow.stepId), title: String(pendingNow.stepId), prompt: `Pending step: ${String(pendingNow.stepId)}` }
+                    : null,
+                blockers,
+            });
+        });
+    }
+    const toNodeId = recordedEvent.data.outcome.toNodeId;
+    const toNodeIdBranded = (0, index_js_3.asNodeId)(String(toNodeId));
+    const toNode = truth.events.find((e) => e.kind === 'node_created' && e.scope?.nodeId === String(toNodeId));
+    if (!toNode) {
+        return (0, neverthrow_1.errAsync)({
+            kind: 'invariant_violation',
+            message: 'Missing node_created for advanced toNodeId (invariant violation).',
+            suggestion: 'Retry; if this persists, treat as invariant violation.',
+        });
+    }
+    return snapshotStore
+        .getExecutionSnapshotV1(toNode.data.snapshotRef)
+        .mapErr((cause) => ({ kind: 'snapshot_load_failed', cause }))
+        .andThen((snap) => {
+        if (!snap) {
+            return (0, neverthrow_1.errAsync)({
+                kind: 'invariant_violation',
+                message: 'Missing execution snapshot for advanced node (invariant violation).',
+                suggestion: 'Retry; if this persists, treat as invariant violation.',
+            });
+        }
+        const pending = (0, snapshot_state_js_1.derivePendingStep)(snap.enginePayload.engineState);
+        const isComplete = (0, snapshot_state_js_1.deriveIsComplete)(snap.enginePayload.engineState);
+        const nextAttemptId = attemptIdForNextNode(attemptId);
+        const nextAckTokenRes = signTokenOrErr({
+            unsignedPrefix: 'ack.v1.',
+            payload: { tokenVersion: 1, tokenKind: 'ack', sessionId, runId, nodeId: toNodeIdBranded, attemptId: nextAttemptId },
+            keyring,
+            hmac,
+            base64url,
+        });
+        if (nextAckTokenRes.isErr()) {
+            return (0, neverthrow_1.errAsync)({ kind: 'token_signing_failed', cause: nextAckTokenRes.error });
+        }
+        const nextCheckpointTokenRes = signTokenOrErr({
+            unsignedPrefix: 'chk.v1.',
+            payload: { tokenVersion: 1, tokenKind: 'checkpoint', sessionId, runId, nodeId: toNodeIdBranded, attemptId: nextAttemptId },
+            keyring,
+            hmac,
+            base64url,
+        });
+        if (nextCheckpointTokenRes.isErr()) {
+            return (0, neverthrow_1.errAsync)({ kind: 'token_signing_failed', cause: nextCheckpointTokenRes.error });
+        }
+        const nextStateTokenRes = signTokenOrErr({
+            unsignedPrefix: 'st.v1.',
+            payload: { tokenVersion: 1, tokenKind: 'state', sessionId, runId, nodeId: toNodeIdBranded, workflowHash },
+            keyring,
+            hmac,
+            base64url,
+        });
+        if (nextStateTokenRes.isErr()) {
+            return (0, neverthrow_1.errAsync)({ kind: 'token_signing_failed', cause: nextStateTokenRes.error });
+        }
+        const { stepId, title, prompt } = extractStepMetadata(pinnedWorkflow, pending ? String(pending.stepId) : null);
+        return (0, neverthrow_1.okAsync)(output_schemas_js_1.V2ContinueWorkflowOutputSchema.parse({
+            kind: 'ok',
+            stateToken: nextStateTokenRes.value,
+            ackToken: nextAckTokenRes.value,
+            checkpointToken: nextCheckpointTokenRes.value,
+            isComplete,
+            pending: stepId ? { stepId, title, prompt } : null,
+        }));
+    });
+}
+function advanceAndRecord(args) {
+    const { truth, sessionId, runId, nodeId, attemptId, workflowHash, dedupeKey, inputContext, inputOutput, lock, pinnedWorkflow, snapshotStore, sessionStore } = args;
+    const hasRun = truth.events.some((e) => e.kind === 'run_started' && e.scope?.runId === String(runId));
+    const hasNode = truth.events.some((e) => e.kind === 'node_created' && e.scope?.runId === String(runId) && e.scope?.nodeId === String(nodeId));
+    if (!hasRun || !hasNode) {
+        return errAsync({ kind: 'missing_node_or_run' });
+    }
+    const compiler = new workflow_compiler_js_1.WorkflowCompiler();
+    const interpreter = new workflow_interpreter_js_1.WorkflowInterpreter();
+    const compiledWf = compiler.compile(pinnedWorkflow);
+    if (compiledWf.isErr()) {
+        return errAsync({ kind: 'advance_apply_failed', message: compiledWf.error.message });
+    }
+    const nodeCreated = truth.events.find((e) => e.kind === 'node_created' && e.scope?.nodeId === String(nodeId));
+    if (!nodeCreated) {
+        return errAsync({ kind: 'missing_node_or_run' });
+    }
+    if (String(nodeCreated.data.workflowHash) !== String(workflowHash)) {
+        return errAsync({ kind: 'workflow_hash_mismatch' });
+    }
+    return snapshotStore.getExecutionSnapshotV1(nodeCreated.data.snapshotRef).andThen((snap) => {
+        if (!snap)
+            return errAsync({ kind: 'missing_snapshot' });
+        const currentState = toV1ExecutionState(snap.enginePayload.engineState);
+        const pendingStep = (currentState.kind === 'running' && currentState.pendingStep) ? currentState.pendingStep : null;
+        if (!pendingStep) {
+            return errAsync({ kind: 'no_pending_step' });
+        }
+        const event = { kind: 'step_completed', stepInstanceId: pendingStep };
+        const advanced = interpreter.applyEvent(currentState, event);
+        if (advanced.isErr()) {
+            return errAsync({ kind: 'advance_apply_failed', message: advanced.error.message });
+        }
+        const ctxObj = inputContext && typeof inputContext === 'object' && inputContext !== null && !Array.isArray(inputContext)
+            ? inputContext
+            : {};
+        const nextRes = interpreter.next(compiledWf.value, advanced.value, ctxObj);
+        if (nextRes.isErr()) {
+            return errAsync({ kind: 'advance_next_failed', message: nextRes.error.message });
+        }
+        const out = nextRes.value;
+        const newEngineState = fromV1ExecutionState(out.state);
+        const snapshotFile = {
+            v: 1,
+            kind: 'execution_snapshot',
+            enginePayload: { v: 1, engineState: newEngineState },
+        };
+        return snapshotStore.putExecutionSnapshotV1(snapshotFile).andThen((newSnapshotRef) => {
+            const toNodeId = `node_${(0, crypto_1.randomUUID)()}`;
+            const nextEventIndex = truth.events.length === 0 ? 0 : truth.events[truth.events.length - 1].eventIndex + 1;
+            const evtAdvanceRecorded = `evt_${(0, crypto_1.randomUUID)()}`;
+            const evtNodeCreated = `evt_${(0, crypto_1.randomUUID)()}`;
+            const evtEdgeCreated = `evt_${(0, crypto_1.randomUUID)()}`;
+            const hasChildren = truth.events.some((e) => e.kind === 'edge_created' && e.data.fromNodeId === String(nodeId));
+            const causeKind = hasChildren ? 'non_tip_advance' : 'intentional_fork';
+            const outputId = (0, index_js_1.asOutputId)(`out_recap_${String(attemptId)}`);
+            const outputsToAppend = inputOutput?.notesMarkdown
+                ? [
+                    {
+                        outputId: String(outputId),
+                        outputChannel: 'recap',
+                        payload: {
+                            payloadKind: 'notes',
+                            notesMarkdown: (0, notes_markdown_js_1.toNotesMarkdownV1)(inputOutput.notesMarkdown),
+                        },
+                    },
+                ]
+                : [];
+            const normalizedOutputs = (0, outputs_js_1.normalizeOutputsForAppend)(outputsToAppend);
+            const outputEventIds = normalizedOutputs.map(() => `evt_${(0, crypto_1.randomUUID)()}`);
+            const planRes = (0, ack_advance_append_plan_js_1.buildAckAdvanceAppendPlanV1)({
+                sessionId: String(sessionId),
+                runId: String(runId),
+                fromNodeId: String(nodeId),
+                workflowHash,
+                attemptId: String(attemptId),
+                nextEventIndex,
+                toNodeId,
+                snapshotRef: newSnapshotRef,
+                causeKind,
+                minted: {
+                    advanceRecordedEventId: evtAdvanceRecorded,
+                    nodeCreatedEventId: evtNodeCreated,
+                    edgeCreatedEventId: evtEdgeCreated,
+                    outputEventIds,
+                },
+                outputsToAppend,
+            });
+            if (planRes.isErr())
+                return errAsync({ kind: 'invariant_violation', message: planRes.error.message });
+            return sessionStore.append(lock, planRes.value);
+        });
+    });
+}
+function errAsync(e) {
+    return (0, neverthrow_1.errAsync)(e);
+}
+function extractStepMetadata(workflow, stepId, options) {
+    const resolvedStepId = stepId ?? '';
+    const step = stepId ? (0, workflow_js_1.getStepById)(workflow, stepId) : null;
+    const hasStringProp = (obj, prop) => typeof obj === 'object' &&
+        obj !== null &&
+        prop in obj &&
+        typeof obj[prop] === 'string';
+    const title = hasStringProp(step, 'title')
+        ? String(step.title)
+        : options?.defaultTitle ?? resolvedStepId;
+    const prompt = hasStringProp(step, 'prompt')
+        ? String(step.prompt)
+        : options?.defaultPrompt ?? (stepId ? `Pending step: ${stepId}` : '');
+    return { stepId: resolvedStepId, title, prompt };
+}
+function internalError(message, suggestion) {
+    return (0, types_js_1.errNotRetryable)('INTERNAL_ERROR', normalizeTokenErrorMessage(message), suggestion ? { suggestion } : undefined);
+}
+function sessionStoreErrorToToolError(e) {
+    switch (e.code) {
+        case 'SESSION_STORE_LOCK_BUSY':
+            return (0, types_js_1.errRetryAfterMs)('INTERNAL_ERROR', normalizeTokenErrorMessage(e.message), e.retry.afterMs, {
+                suggestion: 'Another WorkRail process may be writing to this session; retry.',
+            });
+        case 'SESSION_STORE_CORRUPTION_DETECTED':
+            return (0, types_js_1.errNotRetryable)('SESSION_NOT_HEALTHY', `Session corruption detected: ${e.reason.code}`, {
+                suggestion: 'Execution requires a healthy session. Export salvage view, then recreate.',
+                details: (0, types_js_1.detailsSessionHealth)({ kind: e.location === 'head' ? 'corrupt_head' : 'corrupt_tail', reason: e.reason }),
+            });
+        case 'SESSION_STORE_IO_ERROR':
+            return internalError(e.message, 'Retry; check filesystem permissions.');
+        case 'SESSION_STORE_INVARIANT_VIOLATION':
+            return internalError(e.message, 'Treat as invariant violation.');
+        default:
+            const _exhaustive = e;
+            return internalError('Unknown session store error', 'Treat as invariant violation.');
+    }
+}
+function gateErrorToToolError(e) {
+    switch (e.code) {
+        case 'SESSION_LOCKED':
+            return (0, types_js_1.errRetryAfterMs)('TOKEN_SESSION_LOCKED', e.message, e.retry.afterMs, { suggestion: 'Retry in 1–3 seconds; if this persists >10s, ensure no other WorkRail process is running.' });
+        case 'LOCK_RELEASE_FAILED':
+            return (0, types_js_1.errRetryAfterMs)('TOKEN_SESSION_LOCKED', e.message, e.retry.afterMs, { suggestion: 'Retry in 1–3 seconds; if this persists >10s, ensure no other WorkRail process is running.' });
+        case 'SESSION_NOT_HEALTHY':
+            return (0, types_js_1.errNotRetryable)('SESSION_NOT_HEALTHY', e.message, { suggestion: 'Execution requires healthy session.', details: (0, types_js_1.detailsSessionHealth)(e.health) });
+        case 'SESSION_LOAD_FAILED':
+        case 'SESSION_LOCK_REENTRANT':
+        case 'LOCK_ACQUIRE_FAILED':
+        case 'GATE_CALLBACK_FAILED':
+            return internalError(e.message, 'Retry; if persists, treat as invariant violation.');
+        default:
+            const _exhaustive = e;
+            return internalError('Unknown gate error', 'Treat as invariant violation.');
+    }
+}
+function snapshotStoreErrorToToolError(e, suggestion) {
+    return internalError(`Snapshot store error: ${e.message}`, suggestion);
+}
+function pinnedWorkflowStoreErrorToToolError(e, suggestion) {
+    return internalError(`Pinned workflow store error: ${e.message}`, suggestion);
+}
+function parseStateTokenOrFail(raw, keyring, hmac, base64url) {
+    const parsedRes = (0, index_js_1.parseTokenV1)(raw, base64url);
+    if (parsedRes.isErr()) {
+        return { ok: false, failure: (0, v2_execution_helpers_js_1.mapTokenDecodeErrorToToolError)(parsedRes.error) };
+    }
+    const verified = (0, index_js_1.verifyTokenSignatureV1)(parsedRes.value, keyring, hmac, base64url);
+    if (verified.isErr()) {
+        return { ok: false, failure: (0, v2_execution_helpers_js_1.mapTokenVerifyErrorToToolError)(verified.error) };
+    }
+    if (parsedRes.value.payload.tokenKind !== 'state') {
+        return {
+            ok: false,
+            failure: (0, types_js_1.errNotRetryable)('TOKEN_INVALID_FORMAT', 'Expected a state token (st.v1.*).', {
+                suggestion: 'Use the stateToken returned by WorkRail.',
+            }),
+        };
+    }
+    return { ok: true, token: parsedRes.value };
+}
+function parseAckTokenOrFail(raw, keyring, hmac, base64url) {
+    const parsedRes = (0, index_js_1.parseTokenV1)(raw, base64url);
+    if (parsedRes.isErr()) {
+        return { ok: false, failure: (0, v2_execution_helpers_js_1.mapTokenDecodeErrorToToolError)(parsedRes.error) };
+    }
+    const verified = (0, index_js_1.verifyTokenSignatureV1)(parsedRes.value, keyring, hmac, base64url);
+    if (verified.isErr()) {
+        return { ok: false, failure: (0, v2_execution_helpers_js_1.mapTokenVerifyErrorToToolError)(verified.error) };
+    }
+    if (parsedRes.value.payload.tokenKind !== 'ack') {
+        return {
+            ok: false,
+            failure: (0, types_js_1.errNotRetryable)('TOKEN_INVALID_FORMAT', 'Expected an ack token (ack.v1.*).', {
+                suggestion: 'Use the ackToken returned by WorkRail.',
+            }),
+        };
+    }
+    return { ok: true, token: parsedRes.value };
+}
+function newAttemptId() {
+    return (0, index_js_1.asAttemptId)(`attempt_${(0, crypto_1.randomUUID)()}`);
+}
+function attemptIdForNextNode(parentAttemptId) {
+    return (0, index_js_1.asAttemptId)(`next_${parentAttemptId}`);
+}
+function signTokenOrErr(args) {
+    const bytes = (0, index_js_2.encodeTokenPayloadV1)(args.payload);
+    if (bytes.isErr())
+        return (0, neverthrow_1.err)(bytes.error);
+    const token = (0, index_js_2.signTokenV1)(args.unsignedPrefix, bytes.value, args.keyring, args.hmac, args.base64url);
+    if (token.isErr())
+        return (0, neverthrow_1.err)(token.error);
+    return (0, neverthrow_1.ok)(String(token.value));
+}
+function toV1ExecutionState(engineState) {
+    if (engineState.kind === 'init')
+        return { kind: 'init' };
+    if (engineState.kind === 'complete')
+        return { kind: 'complete' };
+    const pendingStep = engineState.pending.kind === 'some'
+        ? {
+            stepId: String(engineState.pending.step.stepId),
+            loopPath: engineState.pending.step.loopPath.map((f) => ({
+                loopId: String(f.loopId),
+                iteration: f.iteration,
+            })),
+        }
+        : undefined;
+    return {
+        kind: 'running',
+        completed: [...engineState.completed.values].map(String),
+        loopStack: engineState.loopStack.map((f) => ({
+            loopId: String(f.loopId),
+            iteration: f.iteration,
+            bodyIndex: f.bodyIndex,
+        })),
+        pendingStep,
+    };
+}
+function convertRunningExecutionStateToEngineState(state) {
+    const completedArray = [...state.completed].sort((a, b) => a.localeCompare(b));
+    const completed = completedArray.map(s => (0, step_instance_key_js_1.stepInstanceKeyFromParts)((0, step_instance_key_js_1.asDelimiterSafeIdV1)(s), []));
+    const loopStack = state.loopStack.map((f) => ({
+        loopId: (0, step_instance_key_js_1.asDelimiterSafeIdV1)(f.loopId),
+        iteration: f.iteration,
+        bodyIndex: f.bodyIndex,
+    }));
+    const pending = state.pendingStep
+        ? {
+            kind: 'some',
+            step: {
+                stepId: (0, step_instance_key_js_1.asDelimiterSafeIdV1)(state.pendingStep.stepId),
+                loopPath: state.pendingStep.loopPath.map((p) => ({
+                    loopId: (0, step_instance_key_js_1.asDelimiterSafeIdV1)(p.loopId),
+                    iteration: p.iteration,
+                })),
+            },
+        }
+        : { kind: 'none' };
+    return {
+        kind: 'running',
+        completed: { kind: 'set', values: completed },
+        loopStack,
+        pending,
+    };
+}
+function fromV1ExecutionState(state) {
+    if (state.kind === 'init') {
+        return { kind: 'init' };
+    }
+    if (state.kind === 'complete') {
+        return { kind: 'complete' };
+    }
+    return convertRunningExecutionStateToEngineState(state);
+}
+const workflowSourceKindMap = {
+    bundled: 'bundled',
+    user: 'user',
+    project: 'project',
+    remote: 'remote',
+    plugin: 'plugin',
+    git: 'remote',
+    custom: 'project',
+};
+function mapWorkflowSourceKind(kind) {
+    const mapped = workflowSourceKindMap[kind];
+    return mapped ?? 'project';
+}
+async function handleV2StartWorkflow(input, ctx) {
+    return executeStartWorkflow(input, ctx).match((payload) => (0, types_js_1.success)(payload), (e) => (0, v2_execution_helpers_js_1.mapStartWorkflowErrorToToolError)(e));
+}
+function executeStartWorkflow(input, ctx) {
+    if (!ctx.v2) {
+        return (0, neverthrow_1.errAsync)({ kind: 'precondition_failed', message: 'v2 tools disabled', suggestion: 'Enable v2Tools flag' });
+    }
+    const { gate, sessionStore, snapshotStore, pinnedStore, keyring, crypto, hmac, base64url } = ctx.v2;
+    const ctxCheck = checkContextBudget({ tool: 'start_workflow', context: input.context });
+    if (!ctxCheck.ok)
+        return (0, neverthrow_1.errAsync)({ kind: 'validation_failed', failure: ctxCheck.error });
+    return neverthrow_1.ResultAsync.fromPromise(ctx.workflowService.getWorkflowById(input.workflowId), (e) => ({
+        kind: 'precondition_failed',
+        message: e instanceof Error ? e.message : String(e),
+    }))
+        .andThen((workflow) => {
+        if (!workflow) {
+            return (0, neverthrow_1.errAsync)({ kind: 'workflow_not_found', workflowId: (0, index_js_3.asWorkflowId)(input.workflowId) });
+        }
+        const firstStep = workflow.definition.steps[0];
+        if (!firstStep) {
+            return (0, neverthrow_1.errAsync)({ kind: 'workflow_has_no_steps', workflowId: (0, index_js_3.asWorkflowId)(input.workflowId) });
+        }
+        return (0, neverthrow_1.okAsync)({ workflow, firstStep });
+    })
+        .andThen(({ workflow, firstStep }) => {
+        const compiled = (0, v1_to_v2_shim_js_1.compileV1WorkflowToPinnedSnapshot)(workflow);
+        const workflowHashRes = (0, hashing_js_1.workflowHashForCompiledSnapshot)(compiled, crypto);
+        if (workflowHashRes.isErr()) {
+            return (0, neverthrow_1.errAsync)({ kind: 'hash_computation_failed', message: workflowHashRes.error.message });
+        }
+        const workflowHash = workflowHashRes.value;
+        return pinnedStore.get(workflowHash)
+            .mapErr((cause) => ({ kind: 'pinned_workflow_store_failed', cause }))
+            .andThen((existingPinned) => {
+            if (!existingPinned) {
+                return pinnedStore.put(workflowHash, compiled)
+                    .mapErr((cause) => ({ kind: 'pinned_workflow_store_failed', cause }));
+            }
+            return (0, neverthrow_1.okAsync)(undefined);
+        })
+            .andThen(() => pinnedStore.get(workflowHash).mapErr((cause) => ({ kind: 'pinned_workflow_store_failed', cause })))
+            .andThen((pinned) => {
+            if (!pinned || pinned.sourceKind !== 'v1_pinned' || !(0, workflow_definition_js_1.hasWorkflowDefinitionShape)(pinned.definition)) {
+                return (0, neverthrow_1.errAsync)({
+                    kind: 'invariant_violation',
+                    message: 'Failed to pin executable workflow snapshot (missing or invalid pinned workflow).',
+                    suggestion: 'Retry start_workflow; if this persists, treat as invariant violation.',
+                });
+            }
+            const pinnedWorkflow = (0, workflow_js_1.createWorkflow)(pinned.definition, (0, workflow_source_js_1.createBundledSource)());
+            return (0, neverthrow_1.okAsync)({ workflow, firstStep, workflowHash, pinnedWorkflow });
+        });
+    })
+        .andThen(({ workflow, firstStep, workflowHash, pinnedWorkflow }) => {
+        const sessionId = (0, index_js_3.asSessionId)(`sess_${(0, crypto_1.randomUUID)()}`);
+        const runId = (0, index_js_3.asRunId)(`run_${(0, crypto_1.randomUUID)()}`);
+        const nodeId = (0, index_js_3.asNodeId)(`node_${(0, crypto_1.randomUUID)()}`);
+        const snapshot = {
+            v: 1,
+            kind: 'execution_snapshot',
+            enginePayload: {
+                v: 1,
+                engineState: {
+                    kind: 'running',
+                    completed: { kind: 'set', values: [] },
+                    loopStack: [],
+                    pending: { kind: 'some', step: { stepId: (0, step_instance_key_js_1.asDelimiterSafeIdV1)(firstStep.id), loopPath: [] } },
+                },
+            },
+        };
+        return snapshotStore.putExecutionSnapshotV1(snapshot)
+            .mapErr((cause) => ({ kind: 'snapshot_creation_failed', cause }))
+            .andThen((snapshotRef) => {
+            const evtSessionCreated = `evt_${(0, crypto_1.randomUUID)()}`;
+            const evtRunStarted = `evt_${(0, crypto_1.randomUUID)()}`;
+            const evtNodeCreated = `evt_${(0, crypto_1.randomUUID)()}`;
+            return gate.withHealthySessionLock(sessionId, (lock) => {
+                const eventsArray = [
+                    {
+                        v: 1,
+                        eventId: evtSessionCreated,
+                        eventIndex: 0,
+                        sessionId,
+                        kind: 'session_created',
+                        dedupeKey: `session_created:${sessionId}`,
+                        data: {},
+                    },
+                    {
+                        v: 1,
+                        eventId: evtRunStarted,
+                        eventIndex: 1,
+                        sessionId,
+                        kind: 'run_started',
+                        dedupeKey: `run_started:${sessionId}:${runId}`,
+                        scope: { runId },
+                        data: {
+                            workflowId: workflow.definition.id,
+                            workflowHash,
+                            workflowSourceKind: mapWorkflowSourceKind(workflow.source.kind),
+                            workflowSourceRef: workflow.source.kind === 'user' || workflow.source.kind === 'project' || workflow.source.kind === 'custom'
+                                ? workflow.source.directoryPath
+                                : workflow.source.kind === 'git'
+                                    ? `${workflow.source.repositoryUrl}#${workflow.source.branch}`
+                                    : workflow.source.kind === 'remote'
+                                        ? workflow.source.registryUrl
+                                        : workflow.source.kind === 'plugin'
+                                            ? `${workflow.source.pluginName}@${workflow.source.pluginVersion}`
+                                            : '(bundled)',
+                        },
+                    },
+                    {
+                        v: 1,
+                        eventId: evtNodeCreated,
+                        eventIndex: 2,
+                        sessionId,
+                        kind: 'node_created',
+                        dedupeKey: `node_created:${sessionId}:${runId}:${nodeId}`,
+                        scope: { runId, nodeId },
+                        data: {
+                            nodeKind: 'step',
+                            parentNodeId: null,
+                            workflowHash,
+                            snapshotRef,
+                        },
+                    },
+                ];
+                return sessionStore.append(lock, {
+                    events: eventsArray,
+                    snapshotPins: [{ snapshotRef, eventIndex: 2, createdByEventId: evtNodeCreated }],
+                });
+            })
+                .mapErr((cause) => ({ kind: 'session_append_failed', cause }))
+                .map(() => ({ workflow, firstStep, workflowHash, pinnedWorkflow, sessionId, runId, nodeId }));
+        });
+    })
+        .andThen(({ pinnedWorkflow, firstStep, workflowHash, sessionId, runId, nodeId }) => {
+        const statePayload = {
+            tokenVersion: 1,
+            tokenKind: 'state',
+            sessionId,
+            runId,
+            nodeId,
+            workflowHash,
+        };
+        const attemptId = newAttemptId();
+        const ackPayload = {
+            tokenVersion: 1,
+            tokenKind: 'ack',
+            sessionId,
+            runId,
+            nodeId,
+            attemptId,
+        };
+        const checkpointPayload = {
+            tokenVersion: 1,
+            tokenKind: 'checkpoint',
+            sessionId,
+            runId,
+            nodeId,
+            attemptId,
+        };
+        const stateToken = signTokenOrErr({ unsignedPrefix: 'st.v1.', payload: statePayload, keyring, hmac, base64url });
+        if (stateToken.isErr())
+            return (0, neverthrow_1.errAsync)({ kind: 'token_signing_failed', cause: stateToken.error });
+        const ackToken = signTokenOrErr({ unsignedPrefix: 'ack.v1.', payload: ackPayload, keyring, hmac, base64url });
+        if (ackToken.isErr())
+            return (0, neverthrow_1.errAsync)({ kind: 'token_signing_failed', cause: ackToken.error });
+        const checkpointToken = signTokenOrErr({ unsignedPrefix: 'chk.v1.', payload: checkpointPayload, keyring, hmac, base64url });
+        if (checkpointToken.isErr())
+            return (0, neverthrow_1.errAsync)({ kind: 'token_signing_failed', cause: checkpointToken.error });
+        const { stepId, title, prompt } = extractStepMetadata(pinnedWorkflow, firstStep.id);
+        const pending = { stepId, title, prompt };
+        return (0, neverthrow_1.okAsync)(output_schemas_js_1.V2StartWorkflowOutputSchema.parse({
+            stateToken: stateToken.value,
+            ackToken: ackToken.value,
+            checkpointToken: checkpointToken.value,
+            isComplete: false,
+            pending,
+        }));
+    });
+}
+async function handleV2ContinueWorkflow(input, ctx) {
+    return executeContinueWorkflow(input, ctx).match((payload) => (0, types_js_1.success)(payload), (e) => (0, v2_execution_helpers_js_1.mapContinueWorkflowErrorToToolError)(e));
+}
+function executeContinueWorkflow(input, ctx) {
+    if (!ctx.v2) {
+        return (0, neverthrow_1.errAsync)({ kind: 'precondition_failed', message: 'v2 tools disabled', suggestion: 'Enable v2Tools flag' });
+    }
+    const { gate, sessionStore, snapshotStore, pinnedStore, keyring, crypto, hmac, base64url } = ctx.v2;
+    const stateRes = parseStateTokenOrFail(input.stateToken, keyring, hmac, base64url);
+    if (!stateRes.ok)
+        return (0, neverthrow_1.errAsync)({ kind: 'validation_failed', failure: stateRes.failure });
+    const state = stateRes.token;
+    const ctxCheck = checkContextBudget({ tool: 'continue_workflow', context: input.context });
+    if (!ctxCheck.ok)
+        return (0, neverthrow_1.errAsync)({ kind: 'validation_failed', failure: ctxCheck.error });
+    const sessionId = (0, index_js_3.asSessionId)(state.payload.sessionId);
+    const runId = (0, index_js_3.asRunId)(state.payload.runId);
+    const nodeId = (0, index_js_3.asNodeId)(state.payload.nodeId);
+    const workflowHash = (0, index_js_3.asWorkflowHash)((0, index_js_3.asSha256Digest)(state.payload.workflowHash));
+    if (!input.ackToken) {
+        return sessionStore.load(sessionId)
+            .mapErr((cause) => ({ kind: 'session_load_failed', cause }))
+            .andThen((truth) => {
+            const runStarted = truth.events.find((e) => e.kind === 'run_started' && e.scope.runId === String(runId));
+            const workflowId = runStarted?.data.workflowId;
+            if (!runStarted || typeof workflowId !== 'string' || workflowId.trim() === '') {
+                return (0, neverthrow_1.errAsync)({
+                    kind: 'token_unknown_node',
+                    message: 'No durable run state was found for this stateToken (missing run_started).',
+                    suggestion: 'Use start_workflow to mint a new run, or use a stateToken returned by WorkRail for an existing run.',
+                });
+            }
+            if (String(runStarted.data.workflowHash) !== String(workflowHash)) {
+                return (0, neverthrow_1.errAsync)({ kind: 'precondition_failed', message: 'workflowHash mismatch for this run.', suggestion: 'Use the stateToken returned by WorkRail for this run.' });
+            }
+            const nodeCreated = truth.events.find((e) => e.kind === 'node_created' && e.scope.nodeId === String(nodeId) && e.scope.runId === String(runId));
+            if (!nodeCreated) {
+                return (0, neverthrow_1.errAsync)({
+                    kind: 'token_unknown_node',
+                    message: 'No durable node state was found for this stateToken (missing node_created).',
+                    suggestion: 'Use a stateToken returned by WorkRail for an existing node.',
+                });
+            }
+            if (String(nodeCreated.data.workflowHash) !== String(workflowHash)) {
+                return (0, neverthrow_1.errAsync)({ kind: 'precondition_failed', message: 'workflowHash mismatch for this node.', suggestion: 'Use the stateToken returned by WorkRail for this node.' });
+            }
+            return snapshotStore.getExecutionSnapshotV1(nodeCreated.data.snapshotRef)
+                .mapErr((cause) => ({ kind: 'snapshot_load_failed', cause }))
+                .andThen((snapshot) => {
+                if (!snapshot) {
+                    return (0, neverthrow_1.errAsync)({
+                        kind: 'token_unknown_node',
+                        message: 'No execution snapshot was found for this node.',
+                        suggestion: 'Use a stateToken returned by WorkRail for an existing node.',
+                    });
+                }
+                const engineState = snapshot.enginePayload.engineState;
+                const pending = (0, snapshot_state_js_1.derivePendingStep)(engineState);
+                const isComplete = (0, snapshot_state_js_1.deriveIsComplete)(engineState);
+                const attemptId = newAttemptId();
+                const ackTokenRes = signTokenOrErr({
+                    unsignedPrefix: 'ack.v1.',
+                    payload: { tokenVersion: 1, tokenKind: 'ack', sessionId, runId, nodeId, attemptId },
+                    keyring,
+                    hmac,
+                    base64url,
+                });
+                if (ackTokenRes.isErr())
+                    return (0, neverthrow_1.errAsync)({ kind: 'token_signing_failed', cause: ackTokenRes.error });
+                const checkpointTokenRes = signTokenOrErr({
+                    unsignedPrefix: 'chk.v1.',
+                    payload: { tokenVersion: 1, tokenKind: 'checkpoint', sessionId, runId, nodeId, attemptId },
+                    keyring,
+                    hmac,
+                    base64url,
+                });
+                if (checkpointTokenRes.isErr())
+                    return (0, neverthrow_1.errAsync)({ kind: 'token_signing_failed', cause: checkpointTokenRes.error });
+                if (!pending) {
+                    return (0, neverthrow_1.okAsync)(output_schemas_js_1.V2ContinueWorkflowOutputSchema.parse({
+                        kind: 'ok',
+                        stateToken: input.stateToken,
+                        ackToken: ackTokenRes.value,
+                        checkpointToken: checkpointTokenRes.value,
+                        isComplete,
+                        pending: null,
+                    }));
+                }
+                return pinnedStore.get(workflowHash)
+                    .mapErr((cause) => ({ kind: 'pinned_workflow_store_failed', cause }))
+                    .andThen((pinned) => {
+                    if (!pinned)
+                        return (0, neverthrow_1.errAsync)({ kind: 'pinned_workflow_missing', workflowHash: (0, index_js_3.asWorkflowHash)((0, index_js_3.asSha256Digest)(String(workflowHash))) });
+                    if (pinned.sourceKind !== 'v1_pinned')
+                        return (0, neverthrow_1.errAsync)({ kind: 'precondition_failed', message: 'Pinned workflow snapshot is read-only (v1_preview) and cannot be executed.' });
+                    if (!(0, workflow_definition_js_1.hasWorkflowDefinitionShape)(pinned.definition)) {
+                        return (0, neverthrow_1.errAsync)({
+                            kind: 'precondition_failed',
+                            message: 'Pinned workflow snapshot has an invalid workflow definition shape.',
+                            suggestion: 'Re-pin the workflow via start_workflow.',
+                        });
+                    }
+                    const wf = (0, workflow_js_1.createWorkflow)(pinned.definition, (0, workflow_source_js_1.createBundledSource)());
+                    const { stepId, title, prompt } = extractStepMetadata(wf, String(pending.stepId));
+                    return (0, neverthrow_1.okAsync)(output_schemas_js_1.V2ContinueWorkflowOutputSchema.parse({
+                        kind: 'ok',
+                        stateToken: input.stateToken,
+                        ackToken: ackTokenRes.value,
+                        checkpointToken: checkpointTokenRes.value,
+                        isComplete,
+                        pending: { stepId, title, prompt },
+                    }));
+                });
+            });
+        });
+    }
+    const ackRes = parseAckTokenOrFail(input.ackToken, keyring, hmac, base64url);
+    if (!ackRes.ok)
+        return (0, neverthrow_1.errAsync)({ kind: 'validation_failed', failure: ackRes.failure });
+    const ack = ackRes.token;
+    const scopeRes = (0, index_js_1.assertTokenScopeMatchesState)(state, ack);
+    if (scopeRes.isErr())
+        return (0, neverthrow_1.errAsync)({ kind: 'validation_failed', failure: (0, v2_execution_helpers_js_1.mapTokenDecodeErrorToToolError)(scopeRes.error) });
+    const attemptId = (0, index_js_1.asAttemptId)(ack.payload.attemptId);
+    const dedupeKey = `advance_recorded:${sessionId}:${nodeId}:${attemptId}`;
+    return sessionStore.load(sessionId)
+        .mapErr((cause) => ({ kind: 'session_load_failed', cause }))
+        .andThen((truth) => {
+        const existing = truth.events.find((e) => e.kind === 'advance_recorded' && e.dedupeKey === dedupeKey);
+        return pinnedStore.get(workflowHash)
+            .mapErr((cause) => ({ kind: 'pinned_workflow_store_failed', cause }))
+            .andThen((compiled) => {
+            if (!compiled)
+                return (0, neverthrow_1.errAsync)({ kind: 'pinned_workflow_missing', workflowHash });
+            if (compiled.sourceKind !== 'v1_pinned')
+                return (0, neverthrow_1.errAsync)({ kind: 'precondition_failed', message: 'Pinned workflow snapshot is read-only (v1_preview) and cannot be executed.' });
+            if (!(0, workflow_definition_js_1.hasWorkflowDefinitionShape)(compiled.definition)) {
+                return (0, neverthrow_1.errAsync)({
+                    kind: 'precondition_failed',
+                    message: 'Pinned workflow snapshot has an invalid workflow definition shape.',
+                    suggestion: 'Re-pin the workflow via start_workflow.',
+                });
+            }
+            const pinnedWorkflow = (0, workflow_js_1.createWorkflow)(compiled.definition, (0, workflow_source_js_1.createBundledSource)());
+            if (existing) {
+                return replayFromRecordedAdvance({
+                    recordedEvent: existing,
+                    truth,
+                    sessionId,
+                    runId,
+                    nodeId,
+                    workflowHash,
+                    attemptId,
+                    inputStateToken: input.stateToken,
+                    inputAckToken: input.ackToken,
+                    pinnedWorkflow,
+                    snapshotStore,
+                    keyring,
+                    hmac,
+                    base64url,
+                });
+            }
+            return gate
+                .withHealthySessionLock(sessionId, (lock) => sessionStore.load(sessionId).andThen((truthLocked) => {
+                const existingLocked = truthLocked.events.find((e) => e.kind === 'advance_recorded' && e.dedupeKey === dedupeKey);
+                if (existingLocked)
+                    return (0, neverthrow_1.okAsync)({ kind: 'replay', truth: truthLocked, recordedEvent: existingLocked });
+                return advanceAndRecord({
+                    truth: truthLocked,
+                    sessionId,
+                    runId,
+                    nodeId,
+                    attemptId,
+                    workflowHash,
+                    dedupeKey,
+                    inputContext: input.context,
+                    inputOutput: input.output,
+                    lock,
+                    pinnedWorkflow,
+                    snapshotStore,
+                    sessionStore,
+                }).andThen(() => sessionStore
+                    .load(sessionId)
+                    .map((truthAfter) => ({ kind: 'replay', truth: truthAfter, recordedEvent: null })));
+            }))
+                .mapErr((cause) => {
+                if (isInternalError(cause)) {
+                    return {
+                        kind: 'invariant_violation',
+                        message: `Advance failed due to internal invariant violation: ${cause.kind}`,
+                        suggestion: 'Retry; if this persists, treat as invariant violation.',
+                    };
+                }
+                if (typeof cause === 'object' && cause !== null && 'code' in cause) {
+                    const code = cause.code;
+                    if (code.startsWith('SNAPSHOT_STORE_')) {
+                        return { kind: 'snapshot_load_failed', cause: cause };
+                    }
+                    return { kind: 'advance_execution_failed', cause: cause };
+                }
+                return {
+                    kind: 'invariant_violation',
+                    message: 'Advance failed with an unknown error shape (invariant violation).',
+                    suggestion: 'Retry; if this persists, treat as invariant violation.',
+                };
+            })
+                .andThen((res) => {
+                const truth2 = res.truth;
+                const recordedEvent = res.recordedEvent ??
+                    truth2.events.find((e) => e.kind === 'advance_recorded' && e.dedupeKey === dedupeKey);
+                if (!recordedEvent) {
+                    return (0, neverthrow_1.errAsync)({
+                        kind: 'invariant_violation',
+                        message: 'Missing recorded advance outcome after successful append (invariant violation).',
+                        suggestion: 'Retry; if this persists, treat as invariant violation.',
+                    });
+                }
+                return replayFromRecordedAdvance({
+                    recordedEvent,
+                    truth: truth2,
+                    sessionId,
+                    runId,
+                    nodeId,
+                    workflowHash,
+                    attemptId,
+                    inputStateToken: input.stateToken,
+                    inputAckToken: input.ackToken,
+                    pinnedWorkflow,
+                    snapshotStore,
+                    keyring,
+                    hmac,
+                    base64url,
+                });
+            });
+        });
+    });
+}