@exaudeus/workrail 1.4.0 → 1.5.1

package/dist/mcp/handlers/v2-advance-core/event-builders.d.ts

@@ -0,0 +1,37 @@
+import { ResultAsync as RA, type Result } from 'neverthrow';
+import type { DomainEventV1 } from '../../../v2/durable-core/schemas/session/index.js';
+import type { SessionId, RunId, NodeId, WorkflowHash } from '../../../v2/durable-core/ids/index.js';
+import type { AttemptId } from '../../../v2/durable-core/tokens/index.js';
+import type { LoadedSessionTruthV2 } from '../../../v2/ports/session-event-log-store.port.js';
+import type { SessionEventLogStoreError } from '../../../v2/ports/session-event-log-store.port.js';
+import type { WithHealthySessionLock } from '../../../v2/durable-core/ids/with-healthy-session-lock.js';
+import type { Sha256PortV2 } from '../../../v2/ports/sha256.port.js';
+import type { V2ContinueWorkflowInput } from '../../v2/tools.js';
+import { type OutputToAppend } from '../../../v2/durable-core/domain/outputs.js';
+import type { InternalError } from '../v2-error-mapping.js';
+import type { AdvanceCorePorts } from './index.js';
+type BuildAppendPlanArgs = {
+    readonly truth: LoadedSessionTruthV2;
+    readonly sessionId: SessionId;
+    readonly runId: RunId;
+    readonly currentNodeId: NodeId;
+    readonly attemptId: AttemptId;
+    readonly workflowHash: WorkflowHash;
+    readonly extraEventsToAppend: readonly Omit<DomainEventV1, 'eventIndex' | 'sessionId'>[];
+    readonly sessionStore: import('../../../v2/ports/session-event-log-store.port.js').SessionEventLogAppendStorePortV2;
+    readonly idFactory: AdvanceCorePorts['idFactory'];
+    readonly lock: WithHealthySessionLock;
+} & ({
+    readonly kind: 'blocked';
+    readonly blockers: import('../../../v2/durable-core/domain/reason-model.js').BlockerReportV1;
+    readonly snapshotRef: import('../../../v2/durable-core/ids/index.js').SnapshotRef;
+} | {
+    readonly kind: 'advanced';
+    readonly toNodeKind: 'step' | 'blocked_attempt' | undefined;
+    readonly snapshotRef: import('../../../v2/durable-core/ids/index.js').SnapshotRef;
+    readonly outputsToAppend: readonly OutputToAppend[];
+});
+export declare function buildAndAppendPlan(args: BuildAppendPlanArgs): RA<void, InternalError | SessionEventLogStoreError>;
+export declare function buildNotesOutputs(allowNotesAppend: boolean, attemptId: AttemptId, inputOutput: V2ContinueWorkflowInput['output']): readonly OutputToAppend[];
+export declare function buildArtifactOutputs(inputArtifacts: readonly unknown[], attemptId: AttemptId, sha256: Sha256PortV2): Result<readonly OutputToAppend[], InternalError>;
+export {};

package/dist/mcp/handlers/v2-advance-core/event-builders.js

@@ -0,0 +1,114 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.buildAndAppendPlan = buildAndAppendPlan;
+exports.buildNotesOutputs = buildNotesOutputs;
+exports.buildArtifactOutputs = buildArtifactOutputs;
+const neverthrow_1 = require("neverthrow");
+const index_js_1 = require("../../../v2/durable-core/tokens/index.js");
+const jcs_js_1 = require("../../../v2/durable-core/canonical/jcs.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 constants_js_1 = require("../../../v2/durable-core/constants.js");
+function buildAndAppendPlan(args) {
+    const { truth, sessionId, runId, currentNodeId, attemptId, workflowHash, extraEventsToAppend, sessionStore, idFactory, lock } = args;
+    const nextEventIndex = truth.events.length === 0 ? 0 : truth.events[truth.events.length - 1].eventIndex + 1;
+    const evtAdvanceRecorded = idFactory.mintEventId();
+    if (args.kind === 'blocked') {
+        const toNodeId = String(idFactory.mintNodeId());
+        const evtNodeCreated = idFactory.mintEventId();
+        const evtEdgeCreated = idFactory.mintEventId();
+        const hasChildren = truth.events.some((e) => e.kind === constants_js_1.EVENT_KIND.EDGE_CREATED && e.data.fromNodeId === String(currentNodeId));
+        const causeKind = hasChildren ? constants_js_1.EDGE_CAUSE.NON_TIP_ADVANCE : constants_js_1.EDGE_CAUSE.INTENTIONAL_FORK;
+        const planRes = (0, ack_advance_append_plan_js_1.buildAckAdvanceAppendPlanV1)({
+            sessionId: String(sessionId),
+            runId: String(runId),
+            fromNodeId: String(currentNodeId),
+            workflowHash,
+            attemptId: String(attemptId),
+            nextEventIndex,
+            extraEventsToAppend,
+            outcome: { kind: 'advanced', toNodeId },
+            toNodeKind: 'blocked_attempt',
+            toNodeId,
+            snapshotRef: args.snapshotRef,
+            causeKind,
+            minted: {
+                advanceRecordedEventId: evtAdvanceRecorded,
+                nodeCreatedEventId: evtNodeCreated,
+                edgeCreatedEventId: evtEdgeCreated,
+                outputEventIds: [],
+            },
+            outputsToAppend: [],
+        });
+        if (planRes.isErr())
+            return (0, neverthrow_1.errAsync)({ kind: 'invariant_violation', message: planRes.error.message });
+        return sessionStore.append(lock, planRes.value);
+    }
+    const toNodeId = String(idFactory.mintNodeId());
+    const evtNodeCreated = idFactory.mintEventId();
+    const evtEdgeCreated = idFactory.mintEventId();
+    const hasChildren = truth.events.some((e) => e.kind === constants_js_1.EVENT_KIND.EDGE_CREATED && e.data.fromNodeId === String(currentNodeId));
+    const causeKind = hasChildren ? constants_js_1.EDGE_CAUSE.NON_TIP_ADVANCE : constants_js_1.EDGE_CAUSE.INTENTIONAL_FORK;
+    const normalizedOutputs = (0, outputs_js_1.normalizeOutputsForAppend)(args.outputsToAppend);
+    const outputEventIds = normalizedOutputs.map(() => idFactory.mintEventId());
+    const planRes = (0, ack_advance_append_plan_js_1.buildAckAdvanceAppendPlanV1)({
+        sessionId: String(sessionId),
+        runId: String(runId),
+        fromNodeId: String(currentNodeId),
+        workflowHash,
+        attemptId: String(attemptId),
+        nextEventIndex,
+        extraEventsToAppend,
+        outcome: { kind: 'advanced', toNodeId },
+        toNodeKind: args.toNodeKind ?? 'step',
+        toNodeId,
+        snapshotRef: args.snapshotRef,
+        causeKind,
+        minted: {
+            advanceRecordedEventId: evtAdvanceRecorded,
+            nodeCreatedEventId: evtNodeCreated,
+            edgeCreatedEventId: evtEdgeCreated,
+            outputEventIds,
+        },
+        outputsToAppend: [...args.outputsToAppend],
+    });
+    if (planRes.isErr())
+        return (0, neverthrow_1.errAsync)({ kind: 'invariant_violation', message: planRes.error.message });
+    return sessionStore.append(lock, planRes.value);
+}
+function buildNotesOutputs(allowNotesAppend, attemptId, inputOutput) {
+    if (!allowNotesAppend || !inputOutput?.notesMarkdown)
+        return [];
+    return [{
+            outputId: String((0, index_js_1.asOutputId)(`out_recap_${String(attemptId)}`)),
+            outputChannel: constants_js_1.OUTPUT_CHANNEL.RECAP,
+            payload: {
+                payloadKind: 'notes',
+                notesMarkdown: (0, notes_markdown_js_1.toNotesMarkdownV1)(inputOutput.notesMarkdown),
+            },
+        }];
+}
+function buildArtifactOutputs(inputArtifacts, attemptId, sha256) {
+    const outputs = [];
+    for (let idx = 0; idx < inputArtifacts.length; idx++) {
+        const artifact = inputArtifacts[idx];
+        const canonicalBytesRes = (0, jcs_js_1.toCanonicalBytes)(artifact);
+        if (canonicalBytesRes.isErr()) {
+            return (0, neverthrow_1.err)({ kind: 'invariant_violation', message: `Artifact canonicalization failed at index ${idx}: ${canonicalBytesRes.error.message}` });
+        }
+        const canonicalBytes = canonicalBytesRes.value;
+        outputs.push({
+            outputId: (0, index_js_1.asOutputId)(`out_artifact_${String(attemptId)}_${idx}`),
+            outputChannel: constants_js_1.OUTPUT_CHANNEL.ARTIFACT,
+            payload: {
+                payloadKind: 'artifact_ref',
+                sha256: sha256.sha256(canonicalBytes),
+                contentType: 'application/json',
+                byteLength: canonicalBytes.length,
+                content: artifact,
+            },
+        });
+    }
+    return (0, neverthrow_1.ok)(outputs);
+}

package/dist/mcp/handlers/v2-advance-core/index.d.ts

@@ -0,0 +1,67 @@
+import { ResultAsync as RA } from 'neverthrow';
+import type { ExecutionSnapshotFileV1, EngineStateV1 } from '../../../v2/durable-core/schemas/execution-snapshot/index.js';
+import type { SessionId, RunId, NodeId, WorkflowHash } from '../../../v2/durable-core/ids/index.js';
+import type { AttemptId } from '../../../v2/durable-core/tokens/index.js';
+import type { LoadedSessionTruthV2 } from '../../../v2/ports/session-event-log-store.port.js';
+import type { SessionEventLogStoreError } from '../../../v2/ports/session-event-log-store.port.js';
+import type { SnapshotStoreError } from '../../../v2/ports/snapshot-store.port.js';
+import type { WithHealthySessionLock } from '../../../v2/durable-core/ids/with-healthy-session-lock.js';
+import type { Sha256PortV2 } from '../../../v2/ports/sha256.port.js';
+import type { JsonValue } from '../../../v2/durable-core/canonical/json-types.js';
+import type { V2ContinueWorkflowInput } from '../../v2/tools.js';
+import type { ValidationResult } from '../../../types/validation.js';
+import { createWorkflow } from '../../../types/workflow.js';
+import { type ReasonV1 } from '../../../v2/durable-core/domain/reason-model.js';
+import { getOutputRequirementStatusWithArtifactsV1 } from '../../../v2/durable-core/domain/validation-criteria-validator.js';
+import type { InternalError } from '../v2-error-mapping.js';
+import { type ValidatedAdvanceInputs } from './input-validation.js';
+export type AdvanceMode = {
+    readonly kind: 'fresh';
+    readonly sourceNodeId: NodeId;
+    readonly snapshot: ExecutionSnapshotFileV1;
+} | {
+    readonly kind: 'retry';
+    readonly blockedNodeId: NodeId;
+    readonly blockedSnapshot: ExecutionSnapshotFileV1;
+};
+export interface AdvanceCorePorts {
+    readonly snapshotStore: import('../../../v2/ports/snapshot-store.port.js').SnapshotStorePortV2;
+    readonly sessionStore: import('../../../v2/ports/session-event-log-store.port.js').SessionEventLogAppendStorePortV2;
+    readonly sha256: Sha256PortV2;
+    readonly idFactory: {
+        readonly mintNodeId: () => NodeId;
+        readonly mintEventId: () => string;
+    };
+}
+export interface AdvanceContext {
+    readonly truth: LoadedSessionTruthV2;
+    readonly sessionId: SessionId;
+    readonly runId: RunId;
+    readonly currentNodeId: NodeId;
+    readonly attemptId: AttemptId;
+    readonly workflowHash: WorkflowHash;
+    readonly inputOutput: V2ContinueWorkflowInput['output'];
+    readonly pinnedWorkflow: ReturnType<typeof createWorkflow>;
+    readonly engineState: EngineStateV1;
+    readonly pendingStep: ValidatedAdvanceInputs['pendingStep'];
+}
+export interface ComputedAdvanceResults {
+    readonly reasons: readonly ReasonV1[];
+    readonly effectiveReasons: readonly ReasonV1[];
+    readonly outputRequirement: ReturnType<typeof getOutputRequirementStatusWithArtifactsV1>;
+    readonly validation: ValidationResult | undefined;
+}
+export declare function executeAdvanceCore(args: {
+    readonly mode: AdvanceMode;
+    readonly truth: LoadedSessionTruthV2;
+    readonly sessionId: SessionId;
+    readonly runId: RunId;
+    readonly attemptId: AttemptId;
+    readonly workflowHash: WorkflowHash;
+    readonly dedupeKey: string;
+    readonly inputContext: JsonValue | undefined;
+    readonly inputOutput: V2ContinueWorkflowInput['output'];
+    readonly lock: WithHealthySessionLock;
+    readonly pinnedWorkflow: ReturnType<typeof createWorkflow>;
+    readonly ports: AdvanceCorePorts;
+}): RA<void, InternalError | SessionEventLogStoreError | SnapshotStoreError>;

package/dist/mcp/handlers/v2-advance-core/index.js

@@ -0,0 +1,100 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.executeAdvanceCore = executeAdvanceCore;
+const neverthrow_1 = require("neverthrow");
+const snapshot_state_js_1 = require("../../../v2/durable-core/projections/snapshot-state.js");
+const reason_model_js_1 = require("../../../v2/durable-core/domain/reason-model.js");
+const risk_policy_guardrails_js_1 = require("../../../v2/durable-core/domain/risk-policy-guardrails.js");
+const blocking_decision_js_1 = require("../../../v2/durable-core/domain/blocking-decision.js");
+const validation_criteria_validator_js_1 = require("../../../v2/durable-core/domain/validation-criteria-validator.js");
+const validation_engine_js_1 = require("../../../application/services/validation-engine.js");
+const enhanced_loop_validator_js_1 = require("../../../application/services/enhanced-loop-validator.js");
+const v2_state_conversion_js_1 = require("../v2-state-conversion.js");
+const with_timeout_js_1 = require("../shared/with-timeout.js");
+const input_validation_js_1 = require("./input-validation.js");
+const outcome_blocked_js_1 = require("./outcome-blocked.js");
+const outcome_success_js_1 = require("./outcome-success.js");
+function nodeIdOf(mode) {
+    switch (mode.kind) {
+        case 'fresh': return mode.sourceNodeId;
+        case 'retry': return mode.blockedNodeId;
+    }
+}
+function snapshotOf(mode) {
+    switch (mode.kind) {
+        case 'fresh': return mode.snapshot;
+        case 'retry': return mode.blockedSnapshot;
+    }
+}
+function executeAdvanceCore(args) {
+    const { mode, truth, sessionId, runId, attemptId, workflowHash, inputContext, inputOutput, lock, pinnedWorkflow, ports } = args;
+    const { snapshotStore, sessionStore, sha256, idFactory } = ports;
+    const currentNodeId = nodeIdOf(mode);
+    const snap = snapshotOf(mode);
+    const engineState = snap.enginePayload.engineState;
+    const pendingStep = derivePendingStepForMode(mode, engineState);
+    if (!pendingStep) {
+        return errAsync({ kind: 'no_pending_step' });
+    }
+    const validatedRes = (0, input_validation_js_1.validateAdvanceInputs)({
+        truth, runId, currentNodeId, inputContext, inputOutput, pinnedWorkflow, pendingStep,
+    });
+    if (validatedRes.isErr())
+        return errAsync(validatedRes.error);
+    const v = validatedRes.value;
+    const validator = v.validationCriteria ? new validation_engine_js_1.ValidationEngine(new enhanced_loop_validator_js_1.EnhancedLoopValidator()) : null;
+    const validationRes = validator && v.notesMarkdown
+        ? neverthrow_1.ResultAsync.fromPromise((0, with_timeout_js_1.withTimeout)(validator.validate(v.notesMarkdown, v.validationCriteria, v.mergedContext), 30000, 'ValidationEngine.validate'), (cause) => ({ kind: 'advance_apply_failed', message: String(cause) })).andThen((res) => {
+            if (res.isErr()) {
+                return (0, neverthrow_1.errAsync)({
+                    kind: 'advance_apply_failed',
+                    message: `ValidationEngineError: ${res.error.kind} (${res.error.message})`,
+                });
+            }
+            return (0, neverthrow_1.okAsync)(res.value);
+        })
+        : (0, neverthrow_1.okAsync)(undefined);
+    return validationRes.andThen((validation) => {
+        const outputRequirement = (0, validation_criteria_validator_js_1.getOutputRequirementStatusWithArtifactsV1)({
+            outputContract: v.outputContract,
+            artifacts: v.artifacts,
+            validationCriteria: v.validationCriteria,
+            notesMarkdown: v.notesMarkdown,
+            validation,
+        });
+        const reasonsRes = (0, blocking_decision_js_1.detectBlockingReasonsV1)({ outputRequirement });
+        if (reasonsRes.isErr()) {
+            return errAsync({ kind: 'invariant_violation', message: reasonsRes.error.message });
+        }
+        const reasons = reasonsRes.value;
+        const { blocking: effectiveReasons } = (0, risk_policy_guardrails_js_1.applyGuardrails)(v.riskPolicy, reasons);
+        const shouldBlockNow = effectiveReasons.length > 0 && (0, reason_model_js_1.shouldBlock)(v.autonomy, effectiveReasons);
+        const ctx = { truth, sessionId, runId, currentNodeId, attemptId, workflowHash, inputOutput, pinnedWorkflow, engineState, pendingStep };
+        const computed = { reasons, effectiveReasons, outputRequirement, validation };
+        const ports = { snapshotStore, sessionStore, sha256, idFactory };
+        if (shouldBlockNow) {
+            return (0, outcome_blocked_js_1.buildBlockedOutcome)({ mode, snap, ctx, computed, lock, ports });
+        }
+        return (0, outcome_success_js_1.buildSuccessOutcome)({ mode, ctx, computed, v, lock, ports });
+    });
+}
+function derivePendingStepForMode(mode, engineState) {
+    switch (mode.kind) {
+        case 'fresh': {
+            const currentState = (0, v2_state_conversion_js_1.toV1ExecutionState)(engineState);
+            return (currentState.kind === 'running' && currentState.pendingStep) ? currentState.pendingStep : null;
+        }
+        case 'retry': {
+            if (engineState.kind !== 'blocked')
+                return null;
+            const pending = (0, snapshot_state_js_1.derivePendingStep)(engineState);
+            return pending ? {
+                stepId: String(pending.stepId),
+                loopPath: pending.loopPath.map(f => ({ loopId: String(f.loopId), iteration: f.iteration })),
+            } : null;
+        }
+    }
+}
+function errAsync(e) {
+    return (0, neverthrow_1.errAsync)(e);
+}

package/dist/mcp/handlers/v2-advance-core/input-validation.d.ts

@@ -0,0 +1,44 @@
+import { type Result } from 'neverthrow';
+import type { RunId, NodeId } from '../../../v2/durable-core/ids/index.js';
+import type { LoadedSessionTruthV2 } from '../../../v2/ports/session-event-log-store.port.js';
+import type { JsonValue, JsonObject } from '../../../v2/durable-core/canonical/json-types.js';
+import type { V2ContinueWorkflowInput } from '../../v2/tools.js';
+import type { OutputContract } from '../../../types/workflow-definition.js';
+import type { ValidationCriteria } from '../../../types/validation.js';
+import type { InternalError } from '../v2-error-mapping.js';
+export interface ValidatedAdvanceInputs {
+    readonly pendingStep: {
+        readonly stepId: string;
+        readonly loopPath: readonly {
+            readonly loopId: string;
+            readonly iteration: number;
+        }[];
+    };
+    readonly mergedContext: Record<string, unknown>;
+    readonly inputContextObj: JsonObject | undefined;
+    readonly validationCriteria: ValidationCriteria | undefined;
+    readonly outputContract: OutputContract | undefined;
+    readonly notesMarkdown: string | undefined;
+    readonly artifacts: readonly unknown[];
+    readonly autonomy: 'guided' | 'full_auto_stop_on_user_deps' | 'full_auto_never_stop';
+    readonly riskPolicy: 'conservative' | 'balanced' | 'aggressive';
+    readonly effectivePrefs: {
+        readonly autonomy: string;
+        readonly riskPolicy: string;
+    } | undefined;
+}
+export declare function validateAdvanceInputs(args: {
+    readonly truth: LoadedSessionTruthV2;
+    readonly runId: RunId;
+    readonly currentNodeId: NodeId;
+    readonly inputContext: JsonValue | undefined;
+    readonly inputOutput: V2ContinueWorkflowInput['output'];
+    readonly pinnedWorkflow: ReturnType<typeof import('../../../types/workflow.js').createWorkflow>;
+    readonly pendingStep: {
+        readonly stepId: string;
+        readonly loopPath: readonly {
+            readonly loopId: string;
+            readonly iteration: number;
+        }[];
+    };
+}): Result<ValidatedAdvanceInputs, InternalError>;

package/dist/mcp/handlers/v2-advance-core/input-validation.js

@@ -0,0 +1,58 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.validateAdvanceInputs = validateAdvanceInputs;
+const neverthrow_1 = require("neverthrow");
+const workflow_js_1 = require("../../../types/workflow.js");
+const run_context_js_1 = require("../../../v2/projections/run-context.js");
+const preferences_js_1 = require("../../../v2/projections/preferences.js");
+const context_merge_js_1 = require("../../../v2/durable-core/domain/context-merge.js");
+const constants_js_1 = require("../../../v2/durable-core/constants.js");
+function validateAdvanceInputs(args) {
+    const { truth, runId, currentNodeId, inputContext, inputOutput, pinnedWorkflow, pendingStep } = args;
+    const storedContextRes = (0, run_context_js_1.projectRunContextV2)(truth.events);
+    const storedContext = storedContextRes.isOk() ? storedContextRes.value.byRunId[String(runId)]?.context : undefined;
+    const inputContextObj = inputContext && typeof inputContext === 'object' && inputContext !== null && !Array.isArray(inputContext)
+        ? inputContext
+        : undefined;
+    const mergedContextRes = (0, context_merge_js_1.mergeContext)(storedContext, inputContextObj);
+    if (mergedContextRes.isErr()) {
+        return (0, neverthrow_1.err)({ kind: 'invariant_violation', message: `Context merge failed: ${mergedContextRes.error.message}` });
+    }
+    const step = (0, workflow_js_1.getStepById)(pinnedWorkflow, pendingStep.stepId);
+    const validationCriteria = step?.validationCriteria;
+    const outputContract = step?.outputContract;
+    const parentByNodeId = {};
+    for (const e of truth.events) {
+        if (e.kind !== constants_js_1.EVENT_KIND.NODE_CREATED)
+            continue;
+        if (e.scope?.runId !== String(runId))
+            continue;
+        parentByNodeId[String(e.scope.nodeId)] = e.data.parentNodeId;
+    }
+    const prefs = (0, preferences_js_1.projectPreferencesV2)(truth.events, parentByNodeId);
+    const effectivePrefs = prefs.isOk() ? prefs.value.byNodeId[String(currentNodeId)]?.effective : undefined;
+    const rawAutonomy = effectivePrefs?.autonomy ?? 'guided';
+    const rawRiskPolicy = effectivePrefs?.riskPolicy ?? 'conservative';
+    const VALID_AUTONOMY = ['guided', 'full_auto_stop_on_user_deps', 'full_auto_never_stop'];
+    const VALID_RISK_POLICY = ['conservative', 'balanced', 'aggressive'];
+    if (!VALID_AUTONOMY.includes(rawAutonomy)) {
+        return (0, neverthrow_1.err)({ kind: 'invariant_violation', message: `Unknown autonomy mode: ${rawAutonomy}` });
+    }
+    if (!VALID_RISK_POLICY.includes(rawRiskPolicy)) {
+        return (0, neverthrow_1.err)({ kind: 'invariant_violation', message: `Unknown risk policy: ${rawRiskPolicy}` });
+    }
+    const autonomy = rawAutonomy;
+    const riskPolicy = rawRiskPolicy;
+    return (0, neverthrow_1.ok)({
+        pendingStep,
+        mergedContext: mergedContextRes.value,
+        inputContextObj,
+        validationCriteria,
+        outputContract,
+        notesMarkdown: inputOutput?.notesMarkdown,
+        artifacts: inputOutput?.artifacts ?? [],
+        autonomy,
+        riskPolicy,
+        effectivePrefs,
+    });
+}

package/dist/mcp/handlers/v2-advance-core/outcome-blocked.d.ts

@@ -0,0 +1,16 @@
+import { ResultAsync as RA } from 'neverthrow';
+import type { ExecutionSnapshotFileV1 } from '../../../v2/durable-core/schemas/execution-snapshot/index.js';
+import type { SessionEventLogStoreError } from '../../../v2/ports/session-event-log-store.port.js';
+import type { SnapshotStoreError } from '../../../v2/ports/snapshot-store.port.js';
+import type { WithHealthySessionLock } from '../../../v2/durable-core/ids/with-healthy-session-lock.js';
+import type { InternalError } from '../v2-error-mapping.js';
+import type { AdvanceMode } from './index.js';
+import type { AdvanceContext, ComputedAdvanceResults, AdvanceCorePorts } from './index.js';
+export declare function buildBlockedOutcome(args: {
+    readonly mode: AdvanceMode;
+    readonly snap: ExecutionSnapshotFileV1;
+    readonly ctx: AdvanceContext;
+    readonly computed: ComputedAdvanceResults;
+    readonly lock: WithHealthySessionLock;
+    readonly ports: AdvanceCorePorts;
+}): RA<void, InternalError | SessionEventLogStoreError | SnapshotStoreError>;

package/dist/mcp/handlers/v2-advance-core/outcome-blocked.js

@@ -0,0 +1,64 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.buildBlockedOutcome = buildBlockedOutcome;
+const neverthrow_1 = require("neverthrow");
+const reason_model_js_1 = require("../../../v2/durable-core/domain/reason-model.js");
+const validation_event_builder_js_1 = require("../../../v2/durable-core/domain/validation-event-builder.js");
+const blocked_node_builder_js_1 = require("../../../v2/durable-core/domain/blocked-node-builder.js");
+const event_builders_js_1 = require("./event-builders.js");
+function buildBlockedOutcome(args) {
+    const { mode, snap, lock, ports } = args;
+    const { truth, sessionId, runId, currentNodeId, attemptId, workflowHash } = args.ctx;
+    const { reasons, effectiveReasons, outputRequirement, validation } = args.computed;
+    const { snapshotStore, sessionStore, sha256, idFactory } = ports;
+    const blockersRes = (0, reason_model_js_1.buildBlockerReport)(effectiveReasons);
+    if (blockersRes.isErr()) {
+        return errAsync({ kind: 'invariant_violation', message: blockersRes.error.message });
+    }
+    const validationEventId = idFactory.mintEventId();
+    const validationId = `validation_${String(attemptId)}`;
+    const contractRefForEvent = (outputRequirement.kind !== 'not_required' && outputRequirement.kind !== 'satisfied') ? outputRequirement.contractRef : 'none';
+    const validationForEvent = validation ??
+        (outputRequirement.kind === 'missing'
+            ? { valid: false, issues: [`Missing required output for contractRef=${contractRefForEvent}`], suggestions: [], warnings: undefined }
+            : { valid: false, issues: ['Validation result missing'], suggestions: [], warnings: undefined });
+    const validationEventRes = (0, validation_event_builder_js_1.buildValidationPerformedEvent)({
+        sessionId: String(sessionId),
+        validationId,
+        attemptId: String(attemptId),
+        contractRef: contractRefForEvent,
+        scope: { runId: String(runId), nodeId: String(currentNodeId) },
+        minted: { eventId: validationEventId },
+        result: validationForEvent,
+    });
+    if (validationEventRes.isErr()) {
+        return errAsync({ kind: 'invariant_violation', message: validationEventRes.error.message });
+    }
+    const extraEventsToAppend = [validationEventRes.value];
+    const primaryReason = reasons[0];
+    if (!primaryReason) {
+        return errAsync({ kind: 'invariant_violation', message: 'shouldBlockNow=true requires at least one reason' });
+    }
+    const blockedSnapshotRes = (0, blocked_node_builder_js_1.buildBlockedNodeSnapshot)({
+        priorSnapshot: snap,
+        primaryReason,
+        attemptId,
+        validationRef: validationId,
+        blockers: blockersRes.value,
+        sha256,
+    });
+    if (blockedSnapshotRes.isErr()) {
+        return errAsync({ kind: 'invariant_violation', message: blockedSnapshotRes.error.message });
+    }
+    return snapshotStore.putExecutionSnapshotV1(blockedSnapshotRes.value).andThen((blockedSnapshotRef) => {
+        return (0, event_builders_js_1.buildAndAppendPlan)({
+            kind: 'blocked',
+            truth, sessionId, runId, currentNodeId, attemptId, workflowHash,
+            extraEventsToAppend, blockers: blockersRes.value, snapshotRef: blockedSnapshotRef,
+            sessionStore, idFactory, lock,
+        });
+    });
+}
+function errAsync(e) {
+    return (0, neverthrow_1.errAsync)(e);
+}

package/dist/mcp/handlers/v2-advance-core/outcome-success.d.ts

@@ -0,0 +1,15 @@
+import { ResultAsync as RA } from 'neverthrow';
+import type { SessionEventLogStoreError } from '../../../v2/ports/session-event-log-store.port.js';
+import type { SnapshotStoreError } from '../../../v2/ports/snapshot-store.port.js';
+import type { WithHealthySessionLock } from '../../../v2/durable-core/ids/with-healthy-session-lock.js';
+import type { InternalError } from '../v2-error-mapping.js';
+import type { AdvanceMode, AdvanceContext, ComputedAdvanceResults, AdvanceCorePorts } from './index.js';
+import type { ValidatedAdvanceInputs } from './input-validation.js';
+export declare function buildSuccessOutcome(args: {
+    readonly mode: AdvanceMode;
+    readonly ctx: AdvanceContext;
+    readonly computed: ComputedAdvanceResults;
+    readonly v: ValidatedAdvanceInputs;
+    readonly lock: WithHealthySessionLock;
+    readonly ports: AdvanceCorePorts;
+}): RA<void, InternalError | SessionEventLogStoreError | SnapshotStoreError>;

package/dist/mcp/handlers/v2-advance-core/outcome-success.js

@@ -0,0 +1,136 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.buildSuccessOutcome = buildSuccessOutcome;
+const neverthrow_1 = require("neverthrow");
+const workflow_compiler_js_1 = require("../../../application/services/workflow-compiler.js");
+const workflow_interpreter_js_1 = require("../../../application/services/workflow-interpreter.js");
+const recommendation_warnings_js_1 = require("../../../v2/durable-core/domain/recommendation-warnings.js");
+const v2_state_conversion_js_1 = require("../v2-state-conversion.js");
+const v2_context_budget_js_1 = require("../v2-context-budget.js");
+const v2_advance_events_js_1 = require("../v2-advance-events.js");
+const event_builders_js_1 = require("./event-builders.js");
+function successNodeKind(mode) {
+    switch (mode.kind) {
+        case 'fresh': return undefined;
+        case 'retry': return 'step';
+    }
+}
+function buildSuccessOutcome(args) {
+    const { mode, v, lock, ports } = args;
+    const { truth, sessionId, runId, currentNodeId, attemptId, workflowHash, inputOutput, pinnedWorkflow, engineState, pendingStep } = args.ctx;
+    const { effectiveReasons, outputRequirement, validation } = args.computed;
+    const { snapshotStore, sessionStore, sha256, idFactory } = ports;
+    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 currentState = (0, v2_state_conversion_js_1.toV1ExecutionState)(engineState);
+    const event = {
+        kind: 'step_completed',
+        stepInstanceId: {
+            stepId: pendingStep.stepId,
+            loopPath: pendingStep.loopPath.map(f => ({ loopId: f.loopId, iteration: f.iteration })),
+        },
+    };
+    const advanced = interpreter.applyEvent(currentState, event);
+    if (advanced.isErr()) {
+        return errAsync({ kind: 'advance_apply_failed', message: advanced.error.message });
+    }
+    const artifactsForEval = (0, v2_context_budget_js_1.collectArtifactsForEvaluation)({
+        truthEvents: truth.events,
+        inputArtifacts: inputOutput?.artifacts ?? [],
+    });
+    const nextRes = interpreter.next(compiledWf.value, advanced.value, v.mergedContext, artifactsForEval);
+    if (nextRes.isErr()) {
+        return errAsync({ kind: 'advance_next_failed', message: nextRes.error.message });
+    }
+    const out = nextRes.value;
+    const extraEventsToAppend = [];
+    if (v.autonomy === 'full_auto_never_stop' && effectiveReasons.length > 0) {
+        extraEventsToAppend.push(...(0, v2_advance_events_js_1.buildGapEvents)({
+            gaps: effectiveReasons,
+            sessionId: String(sessionId),
+            runId,
+            nodeId: currentNodeId,
+            attemptId,
+            idFactory,
+        }));
+    }
+    const workflowRecommendations = pinnedWorkflow.definition.recommendedPreferences;
+    if (workflowRecommendations && v.effectivePrefs) {
+        const warnings = (0, recommendation_warnings_js_1.checkRecommendationExceedance)({ autonomy: v.autonomy, riskPolicy: v.riskPolicy }, workflowRecommendations);
+        extraEventsToAppend.push(...(0, v2_advance_events_js_1.buildRecommendationWarningEvents)({
+            recommendations: warnings,
+            sessionId: String(sessionId),
+            runId,
+            nodeId: currentNodeId,
+            idFactory,
+        }));
+    }
+    if (v.inputContextObj) {
+        const contextEvent = (0, v2_advance_events_js_1.buildContextSetEvent)({
+            mergedContext: v.mergedContext,
+            sessionId: String(sessionId),
+            runId,
+            idFactory,
+        });
+        if (contextEvent) {
+            extraEventsToAppend.push(contextEvent);
+        }
+    }
+    const validationEvent = (0, v2_advance_events_js_1.buildSuccessValidationEvent)({
+        mode,
+        outputRequirement,
+        validation,
+        attemptId,
+        sessionId: String(sessionId),
+        runId,
+        nodeId: currentNodeId,
+        idFactory,
+    });
+    if (validationEvent) {
+        extraEventsToAppend.push(validationEvent);
+    }
+    const traceEventRes = (0, v2_advance_events_js_1.buildDecisionTraceEvent)({
+        decisions: out.trace,
+        sessionId: String(sessionId),
+        runId,
+        nodeId: currentNodeId,
+        idFactory,
+    });
+    if (traceEventRes.isErr()) {
+        return errAsync(traceEventRes.error);
+    }
+    if (traceEventRes.value) {
+        extraEventsToAppend.push(traceEventRes.value);
+    }
+    const newEngineState = (0, v2_state_conversion_js_1.fromV1ExecutionState)(out.state);
+    const snapshotFile = {
+        v: 1,
+        kind: 'execution_snapshot',
+        enginePayload: { v: 1, engineState: newEngineState },
+    };
+    return snapshotStore.putExecutionSnapshotV1(snapshotFile).andThen((newSnapshotRef) => {
+        const allowNotesAppend = v.validationCriteria
+            ? Boolean(v.notesMarkdown && validation && validation.valid)
+            : Boolean(v.notesMarkdown);
+        const notesOutputs = (0, event_builders_js_1.buildNotesOutputs)(allowNotesAppend, attemptId, inputOutput);
+        const artifactOutputsRes = (0, event_builders_js_1.buildArtifactOutputs)(inputOutput?.artifacts ?? [], attemptId, sha256);
+        if (artifactOutputsRes.isErr()) {
+            return errAsync(artifactOutputsRes.error);
+        }
+        const outputsToAppend = [...notesOutputs, ...artifactOutputsRes.value];
+        return (0, event_builders_js_1.buildAndAppendPlan)({
+            kind: 'advanced',
+            truth, sessionId, runId, currentNodeId, attemptId, workflowHash,
+            extraEventsToAppend, toNodeKind: successNodeKind(mode),
+            snapshotRef: newSnapshotRef, outputsToAppend,
+            sessionStore, idFactory, lock,
+        });
+    });
+}
+function errAsync(e) {
+    return (0, neverthrow_1.errAsync)(e);
+}