@exaudeus/workrail 1.1.0 → 1.3.0

package/dist/mcp/tool-descriptions.js

@@ -64,48 +64,54 @@ Remember: inspecting is read-only. Call start_workflow when ready to begin.`,
 The workflow represents the user's plan for this task. Each step will tell you exactly what to do. Your job is to execute each step's instructions and report back.
 
 What you'll receive:
-- stateToken: Your session handle (save this - you'll need it for every continue_workflow call)
-- ackToken: Your completion acknowledgement token (include when advancing to next step)
-- pending: The first step's instructions (in pending.prompt)
-- nextIntent: What to do next (usually "perform_pending_then_continue")
+- pending.prompt: The first step's instructions — read this and do what it says
+- nextCall: A pre-built template for your next continue_workflow call (copy its params when done)
+- nextIntent: How to approach this step (usually "perform_pending_then_continue")
 - preferences: Execution mode settings (autonomy level, risk policy)
 
 What to do:
-1. Execute the pending step exactly as its prompt describes
-2. Call continue_workflow with stateToken + ackToken + your output
-3. Don't predict what comes next - the workflow will tell you
+1. Read pending.prompt and execute the step exactly as described
+2. When done, call continue_workflow using the params from nextCall (it has intent, stateToken, ackToken pre-filled)
+3. Optionally add output.notesMarkdown summarizing your work
+4. Don't predict what comes next - the workflow will tell you
 
 Context auto-loads: If you provide context at start, WorkRail remembers it. On future continue_workflow calls, only pass context if you have NEW information to add.`,
         continue_workflow: `Get the next step in the workflow (WorkRail v2, feature-flagged).
 
-This is an interactive conversation with state. Each call either:
-- Advances to the next step (when you include ackToken)
-- Recovers the current step (when you omit ackToken)
+QUICK START — How to call back after completing a step:
+Copy the params from the "nextCall" field of the previous response. It has intent, stateToken, and ackToken pre-filled. Just add your output if desired.
 
-How to use:
-- WITH ackToken: "I completed the pending step, here's my output. What's next?"
-  → WorkRail advances to next step and returns it
-  
-- WITHOUT ackToken: "Remind me what the current step is"
-  → WorkRail returns the same pending step (no advancement, useful after rewinds)
+Two modes — set intent explicitly:
+
+ADVANCE (intent: "advance"):
+- "I completed the current step; give me the next one"
+- Requires: intent + stateToken + ackToken (all provided in nextCall.params)
+- Optional: output (your work summary), context (if facts changed)
+- Result: WorkRail advances to next step and returns it
+
+REHYDRATE (intent: "rehydrate"):
+- "Remind me what the current step is" (after rewind or lost context)
+- Requires: intent + stateToken
+- Do NOT include ackToken or output
+- Result: Same pending step returned; no advancement; side-effect-free
 
-IMPORTANT - Don't predict next steps:
-After completing a step, don't ask "should we move to implementation?" or propose next steps.
-Just call continue_workflow - the workflow decides what's actually next (might be validation, review, or something you didn't expect).
+Reading the response:
+- pending.prompt: The step's instructions — what to do
+- nextCall: Pre-built template for your next call — how to proceed when done (null if workflow complete)
+- nextIntent: How to approach this step — execute it, confirm first, or continue working on it
 
-nextIntent tells you what to do:
-- "perform_pending_then_continue": Execute this step immediately, then call continue_workflow again
+nextIntent values:
+- "perform_pending_then_continue": Execute this step, then use nextCall to advance
 - "await_user_confirmation": Auto-confirm and proceed (you don't need to wait for user in agent mode)
-- "rehydrate_only": You just recovered state; continue working on the current step
-- "complete": Workflow finished; no more steps
+- "rehydrate_only": You just recovered state; continue working on the current step, then use nextCall
+- "complete": Workflow finished; nextCall is null
 
 Parameters:
-- stateToken (required): Your session handle from start_workflow or previous continue_workflow
-- ackToken (optional): Include to advance; omit to rehydrate
-- context (optional): NEW facts only (e.g., user provided a branch name). Omit if unchanged - WorkRail auto-loads previous context
-- output.notesMarkdown (optional): Fresh summary of THIS step only - never accumulated
-  Example WRONG: "Phase 0: planning. Phase 1: implementation."
-  Example RIGHT: "Implemented user authentication with OAuth2; added 3 endpoints."
+- intent (required): "advance" or "rehydrate"
+- stateToken (required): From nextCall.params or previous response
+- ackToken (required for advance): From nextCall.params or previous response
+- context (optional): NEW facts only. Omit if unchanged - WorkRail auto-loads previous context
+- output.notesMarkdown (optional, advance only): Fresh summary of THIS step only - never accumulated
 
 The workflow is the user's structured instructions. Follow each step exactly as described.`,
     },
@@ -183,17 +189,17 @@ This is read-only. Call start_workflow when ready to commit to following the wor
 The workflow is the USER'S VOICE expressing their plan for this task. Each step is a DIRECT INSTRUCTION from the user (or workflow author representing user intent). You MUST execute each step exactly as specified.
 
 What you receive:
-- stateToken: Your session identifier - round-trip this UNCHANGED in every continue_workflow call
-- ackToken: Your step completion token - include when advancing to next step
-- pending.prompt: The user's first instruction for you
-- nextIntent: Prescriptive directive for what to do next
+- pending.prompt: The user's first instruction — execute this EXACTLY as described
+- nextCall: Pre-built template for your next continue_workflow call — copy its params when done
+- nextIntent: How to approach this step (execute, confirm, etc.)
 - preferences: User's execution mode preferences (autonomy, risk tolerance)
 
 REQUIRED BEHAVIOR:
 1. Execute the pending step EXACTLY as the prompt describes
-2. Call continue_workflow after completing each step (don't predict or skip ahead)
-3. Round-trip tokens UNCHANGED (don't decode, inspect, or modify them)
-4. Follow the workflow to completion - don't improvise alternative approaches
+2. When done, call continue_workflow using the params from nextCall (intent, stateToken, ackToken are pre-filled)
+3. Optionally add output.notesMarkdown summarizing your work
+4. Round-trip tokens UNCHANGED (don't decode, inspect, or modify them)
+5. Follow the workflow to completion - don't improvise alternative approaches
 
 Context handling:
 - Pass context at start to establish baseline facts
@@ -203,38 +209,48 @@ Context handling:
 
 The workflow represents the USER'S PLAN. The pending step returned is a DIRECT INSTRUCTION you MUST follow.
 
-Two modes of operation:
+HOW TO CALL — Copy nextCall.params from the previous response. It has intent, stateToken, and ackToken pre-filled. Add output if desired.
 
-ADVANCEMENT (with ackToken):
+Two modes — set intent explicitly:
+
+ADVANCE (intent: "advance"):
 - Purpose: "I completed the current step; give me the next instruction"
-- Include: stateToken + ackToken + output
+- Requires: intent + stateToken + ackToken (all in nextCall.params from previous response)
+- Optional: output (your work summary), context (if facts changed)
 - Result: WorkRail advances to next step
 - Idempotent: Safe to retry with same tokens if unsure
 
-REHYDRATION (without ackToken):
+REHYDRATE (intent: "rehydrate"):
 - Purpose: "Remind me what the current step is" (after rewind/lost context)
-- Include: stateToken only (no ackToken, no output)
+- Requires: intent + stateToken only
+- Do NOT include ackToken or output
 - Result: Same pending step returned; no advancement
 - Side-effect-free: No durable writes; pure state recovery
 
 REQUIRED BEHAVIOR:
 1. Execute the step EXACTLY as specified in pending.prompt
-2. Do NOT predict what comes next - call continue_workflow and the workflow will tell you
-3. Do NOT skip steps, combine steps, or improvise your own approach
-4. Do NOT ask "should we move to implementation?" - just call continue_workflow
+2. When done, call continue_workflow using nextCall.params — do NOT construct params manually
+3. Do NOT predict what comes next - call continue_workflow and the workflow will tell you
+4. Do NOT skip steps, combine steps, or improvise your own approach
+
+Reading the response:
+- pending.prompt: The step's instructions — WHAT to do
+- nextCall: Pre-built call template — HOW to proceed when done (null if complete)
+- nextIntent: Step disposition — HOW to approach this step
 
 nextIntent is PRESCRIPTIVE (not advisory):
-- "perform_pending_then_continue": Execute this step, then call continue_workflow immediately
+- "perform_pending_then_continue": Execute this step, then use nextCall to advance
 - "await_user_confirmation": Auto-confirm and proceed (workflow represents user's intent)
-- "rehydrate_only": State recovery occurred; continue working on current step
-- "complete": Workflow finished; no further calls needed
+- "rehydrate_only": State recovery occurred; continue working on current step, then use nextCall
+- "complete": Workflow finished; nextCall is null
 
 Parameters:
-- stateToken (required): Round-trip unchanged from previous response
-- ackToken (optional): Include to ADVANCE, omit to REHYDRATE
+- intent (required): "advance" or "rehydrate"
+- stateToken (required): From nextCall.params or previous response
+- ackToken (required for advance): From nextCall.params or previous response
 - context (optional): NEW facts only (auto-merges with previous). Omit if unchanged
-- output.notesMarkdown (optional): Summary of THIS step only (fresh, never accumulated)
+- output.notesMarkdown (optional, advance only): Summary of THIS step only (fresh, never accumulated)
   
-The workflow is the user's structured will. Follow it exactly - it may validate, loop, or branch in ways you don't predict.`,
+The workflow is the user's structured will. Follow it exactly — it may validate, loop, or branch in ways you don't predict.`,
     },
 };

package/dist/mcp/types.d.ts

@@ -12,6 +12,7 @@ import type { CryptoPortV2 } from '../v2/durable-core/canonical/hashing.js';
 import type { IdFactoryV2 } from '../v2/infra/local/id-factory/index.js';
 import type { JsonValue } from './output-schemas.js';
 import type { TokenCodecPorts } from '../v2/durable-core/tokens/token-codec-ports.js';
+import type { WorkspaceAnchorPortV2 } from '../v2/ports/workspace-anchor.port.js';
 export interface SessionHealthDetails {
     readonly health: SessionHealthV2;
 }
@@ -51,6 +52,7 @@ export interface V2Dependencies {
     readonly crypto: CryptoPortV2;
     readonly idFactory: IdFactoryV2;
     readonly tokenCodecPorts: TokenCodecPorts;
+    readonly workspaceAnchor?: WorkspaceAnchorPortV2;
 }
 export interface ToolContext {
     readonly workflowService: WorkflowService;

package/dist/mcp/v2/tools.d.ts

@@ -24,7 +24,8 @@ export declare const V2StartWorkflowInput: z.ZodObject<{
     context?: Record<string, unknown> | undefined;
 }>;
 export type V2StartWorkflowInput = z.infer<typeof V2StartWorkflowInput>;
-export declare const V2ContinueWorkflowInput: z.ZodObject<{
+export declare const V2ContinueWorkflowInput: z.ZodEffects<z.ZodObject<{
+    intent: z.ZodEnum<["advance", "rehydrate"]>;
     stateToken: z.ZodString;
     ackToken: z.ZodOptional<z.ZodString>;
     context: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
@@ -38,7 +39,26 @@ export declare const V2ContinueWorkflowInput: z.ZodObject<{
         notesMarkdown?: string | undefined;
         artifacts?: unknown[] | undefined;
     }>>;
-}, "strip", z.ZodTypeAny, {
+}, "strict", z.ZodTypeAny, {
+    intent: "advance" | "rehydrate";
+    stateToken: string;
+    context?: Record<string, unknown> | undefined;
+    output?: {
+        notesMarkdown?: string | undefined;
+        artifacts?: unknown[] | undefined;
+    } | undefined;
+    ackToken?: string | undefined;
+}, {
+    intent: "advance" | "rehydrate";
+    stateToken: string;
+    context?: Record<string, unknown> | undefined;
+    output?: {
+        notesMarkdown?: string | undefined;
+        artifacts?: unknown[] | undefined;
+    } | undefined;
+    ackToken?: string | undefined;
+}>, {
+    intent: "advance" | "rehydrate";
     stateToken: string;
     context?: Record<string, unknown> | undefined;
     output?: {
@@ -47,6 +67,7 @@ export declare const V2ContinueWorkflowInput: z.ZodObject<{
     } | undefined;
     ackToken?: string | undefined;
 }, {
+    intent: "advance" | "rehydrate";
     stateToken: string;
     context?: Record<string, unknown> | undefined;
     output?: {

package/dist/mcp/v2/tools.js

@@ -12,16 +12,47 @@ exports.V2StartWorkflowInput = zod_1.z.object({
     context: zod_1.z.record(zod_1.z.unknown()).optional().describe('External facts influencing execution (ticketId, branch, constraints). Pass once at start to establish baseline. WorkRail auto-loads context on subsequent continue_workflow calls. Only pass context again if facts have CHANGED (e.g., user provided new information). Do NOT re-pass unchanged values.'),
 });
 exports.V2ContinueWorkflowInput = zod_1.z.object({
-    stateToken: zod_1.z.string().min(1).describe('Your session handle from start_workflow or previous continue_workflow. Pass this in EVERY continue_workflow call to identify your session. Round-trip exactly as received - never decode, inspect, or modify it. This is different from ackToken (which is your completion receipt).'),
-    ackToken: zod_1.z.string().min(1).optional().describe('Your step completion receipt. Include this to ADVANCE to the next step. OMIT this entirely to REHYDRATE (recover current step after rewind/lost context). Pattern: stateToken identifies WHERE you are; ackToken says "I finished here, next step please."'),
+    intent: zod_1.z.enum(['advance', 'rehydrate']).describe('What you want to do. ' +
+        '"advance": I completed the current step — requires ackToken. ' +
+        '"rehydrate": Remind me what the current step is (state recovery after rewind/lost context) — do NOT include ackToken or output.'),
+    stateToken: zod_1.z.string().min(1).describe('Your session handle from start_workflow or previous continue_workflow. Pass this in EVERY continue_workflow call to identify your session. Round-trip exactly as received — never decode, inspect, or modify it.'),
+    ackToken: zod_1.z.string().min(1).optional().describe('Your step completion receipt. Required when intent is "advance". Must be omitted when intent is "rehydrate".'),
     context: zod_1.z.record(zod_1.z.unknown()).optional().describe('External facts (only if CHANGED since last call). Omit this entirely if no facts changed. WorkRail auto-merges with previous context. Example: if context={branch:"main"} at start, do NOT re-pass it unless branch changed. Pass only NEW or OVERRIDDEN values.'),
     output: zod_1.z
         .object({
-        notesMarkdown: zod_1.z.string().min(1).optional().describe('Summary of work completed in THIS step only - fresh and specific to this step. Do NOT append previous step notes. WorkRail concatenates notes across steps automatically. WRONG: "Phase 0: planning. Phase 1: implemented." RIGHT: "Implemented OAuth2 with 3 endpoints; added token validation middleware." Aim for ≤10 lines.'),
+        notesMarkdown: zod_1.z.string().min(1).optional().describe('Summary of work completed in THIS step only — fresh and specific to this step. Do NOT append previous step notes. WorkRail concatenates notes across steps automatically. WRONG: "Phase 0: planning. Phase 1: implemented." RIGHT: "Implemented OAuth2 with 3 endpoints; added token validation middleware." Aim for ≤10 lines.'),
         artifacts: zod_1.z.array(zod_1.z.unknown()).optional().describe('Optional structured artifacts (schema is workflow/contract-defined)'),
     })
         .optional()
-        .describe('Optional durable output to attach to the current node'),
+        .describe('Durable output to attach to the current node. Only valid when intent is "advance".'),
+}).strict().superRefine((data, ctx) => {
+    if (data.intent === 'advance' && !data.ackToken) {
+        ctx.addIssue({
+            code: zod_1.z.ZodIssueCode.custom,
+            path: ['ackToken'],
+            message: 'intent is "advance" but ackToken is missing. ' +
+                'To advance to the next step, include the ackToken from the previous start_workflow or continue_workflow response. ' +
+                'If you don\'t have an ackToken, set intent to "rehydrate" to recover the current step.',
+        });
+    }
+    if (data.intent === 'rehydrate' && data.ackToken) {
+        ctx.addIssue({
+            code: zod_1.z.ZodIssueCode.custom,
+            path: ['ackToken'],
+            message: 'intent is "rehydrate" but ackToken was provided. ' +
+                'Rehydration recovers the current step without advancing — it does not accept ackToken. ' +
+                'To advance, set intent to "advance". To rehydrate, remove ackToken.',
+        });
+    }
+    if (data.intent === 'rehydrate' && data.output) {
+        ctx.addIssue({
+            code: zod_1.z.ZodIssueCode.custom,
+            path: ['output'],
+            message: 'intent is "rehydrate" but output was provided. ' +
+                'Rehydration is read-only state recovery — it does not accept output. ' +
+                'To submit output and advance, set intent to "advance" and include ackToken.',
+        });
+    }
 });
 exports.V2_TOOL_TITLES = {
     list_workflows: 'List Workflows (v2)',

package/dist/types/workflow-definition.d.ts

@@ -1,4 +1,8 @@
 import { ValidationCriteria } from './validation';
+export interface OutputContract {
+    readonly contractRef: string;
+    readonly required?: boolean;
+}
 export interface WorkflowStepDefinition {
     readonly id: string;
     readonly title: string;
@@ -9,6 +13,7 @@ export interface WorkflowStepDefinition {
     readonly requireConfirmation?: boolean;
     readonly runCondition?: Readonly<Record<string, unknown>>;
     readonly validationCriteria?: ValidationCriteria;
+    readonly outputContract?: OutputContract;
     readonly functionDefinitions?: readonly FunctionDefinition[];
     readonly functionCalls?: readonly FunctionCall[];
     readonly functionReferences?: readonly string[];
@@ -18,9 +23,18 @@ export interface LoopStepDefinition extends WorkflowStepDefinition {
     readonly loop: LoopConfigDefinition;
     readonly body: string | readonly WorkflowStepDefinition[];
 }
+export type LoopConditionSource = {
+    readonly kind: 'artifact_contract';
+    readonly contractRef: string;
+    readonly loopId: string;
+} | {
+    readonly kind: 'context_variable';
+    readonly condition: Readonly<Record<string, unknown>>;
+};
 export interface LoopConfigDefinition {
     readonly type: 'while' | 'until' | 'for' | 'forEach';
     readonly condition?: Readonly<Record<string, unknown>>;
+    readonly conditionSource?: LoopConditionSource;
     readonly items?: string;
     readonly count?: number | string;
     readonly maxIterations: number;
@@ -46,6 +60,10 @@ export interface FunctionCall {
     readonly name: string;
     readonly args: Readonly<Record<string, unknown>>;
 }
+export interface WorkflowRecommendedPreferences {
+    readonly recommendedAutonomy?: 'guided' | 'full_auto_stop_on_user_deps' | 'full_auto_never_stop';
+    readonly recommendedRiskPolicy?: 'conservative' | 'balanced' | 'aggressive';
+}
 export interface WorkflowDefinition {
     readonly id: string;
     readonly name: string;
@@ -56,6 +74,7 @@ export interface WorkflowDefinition {
     readonly clarificationPrompts?: readonly string[];
     readonly metaGuidance?: readonly string[];
     readonly functionDefinitions?: readonly FunctionDefinition[];
+    readonly recommendedPreferences?: WorkflowRecommendedPreferences;
 }
 export declare function isLoopStepDefinition(step: WorkflowStepDefinition | LoopStepDefinition): step is LoopStepDefinition;
 export declare function isWorkflowStepDefinition(step: WorkflowStepDefinition | LoopStepDefinition): step is WorkflowStepDefinition;

package/dist/v2/durable-core/constants.d.ts

@@ -5,6 +5,8 @@ export declare const MAX_DECISION_TRACE_ENTRIES = 25;
 export declare const MAX_DECISION_TRACE_ENTRY_SUMMARY_BYTES = 512;
 export declare const MAX_DECISION_TRACE_TOTAL_BYTES = 8192;
 export declare const MAX_OUTPUT_NOTES_MARKDOWN_BYTES = 4096;
+export declare const MAX_VALIDATION_ISSUES_BYTES = 4096;
+export declare const MAX_VALIDATION_SUGGESTIONS_BYTES = 4096;
 export declare const MAX_CONTEXT_BYTES: number;
 export declare const MAX_CONTEXT_DEPTH = 64;
 export declare const MAX_OBSERVATION_SHORT_STRING_LENGTH = 80;

package/dist/v2/durable-core/constants.js

@@ -1,6 +1,6 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.DELIMITER_SAFE_ID_PATTERN = exports.SHA256_DIGEST_PATTERN = exports.RECOVERY_BUDGET_BYTES = exports.TRUNCATION_MARKER = exports.DEFAULT_RETRY_AFTER_MS = exports.SESSION_LOCK_RETRY_AFTER_MS = exports.MAX_OBSERVATION_SHORT_STRING_LENGTH = exports.MAX_CONTEXT_DEPTH = exports.MAX_CONTEXT_BYTES = exports.MAX_OUTPUT_NOTES_MARKDOWN_BYTES = exports.MAX_DECISION_TRACE_TOTAL_BYTES = exports.MAX_DECISION_TRACE_ENTRY_SUMMARY_BYTES = exports.MAX_DECISION_TRACE_ENTRIES = exports.MAX_BLOCKER_SUGGESTED_FIX_BYTES = exports.MAX_BLOCKER_MESSAGE_BYTES = exports.MAX_BLOCKERS = void 0;
+exports.DELIMITER_SAFE_ID_PATTERN = exports.SHA256_DIGEST_PATTERN = exports.RECOVERY_BUDGET_BYTES = exports.TRUNCATION_MARKER = exports.DEFAULT_RETRY_AFTER_MS = exports.SESSION_LOCK_RETRY_AFTER_MS = exports.MAX_OBSERVATION_SHORT_STRING_LENGTH = exports.MAX_CONTEXT_DEPTH = exports.MAX_CONTEXT_BYTES = exports.MAX_VALIDATION_SUGGESTIONS_BYTES = exports.MAX_VALIDATION_ISSUES_BYTES = exports.MAX_OUTPUT_NOTES_MARKDOWN_BYTES = exports.MAX_DECISION_TRACE_TOTAL_BYTES = exports.MAX_DECISION_TRACE_ENTRY_SUMMARY_BYTES = exports.MAX_DECISION_TRACE_ENTRIES = exports.MAX_BLOCKER_SUGGESTED_FIX_BYTES = exports.MAX_BLOCKER_MESSAGE_BYTES = exports.MAX_BLOCKERS = void 0;
 exports.MAX_BLOCKERS = 10;
 exports.MAX_BLOCKER_MESSAGE_BYTES = 512;
 exports.MAX_BLOCKER_SUGGESTED_FIX_BYTES = 1024;
@@ -8,6 +8,8 @@ exports.MAX_DECISION_TRACE_ENTRIES = 25;
 exports.MAX_DECISION_TRACE_ENTRY_SUMMARY_BYTES = 512;
 exports.MAX_DECISION_TRACE_TOTAL_BYTES = 8192;
 exports.MAX_OUTPUT_NOTES_MARKDOWN_BYTES = 4096;
+exports.MAX_VALIDATION_ISSUES_BYTES = 4096;
+exports.MAX_VALIDATION_SUGGESTIONS_BYTES = 4096;
 exports.MAX_CONTEXT_BYTES = 256 * 1024;
 exports.MAX_CONTEXT_DEPTH = 64;
 exports.MAX_OBSERVATION_SHORT_STRING_LENGTH = 80;

package/dist/v2/durable-core/domain/ack-advance-append-plan.d.ts

@@ -16,6 +16,7 @@ export declare function buildAckAdvanceAppendPlanV1(args: {
     readonly outcome?: AdvanceOutcomeV1;
     readonly extraEventsToAppend?: readonly EventToAppendV1[];
     readonly toNodeId?: string;
+    readonly toNodeKind?: 'step' | 'blocked_attempt';
     readonly snapshotRef?: SnapshotRef;
     readonly causeKind?: 'intentional_fork' | 'non_tip_advance';
     readonly minted: {

package/dist/v2/durable-core/domain/ack-advance-append-plan.js

@@ -46,6 +46,12 @@ function buildAckAdvanceAppendPlanV1(args) {
     }
     const nextIndexAfterExtra = nextEventIndex + 1 + extra.length;
     if (outcome.kind === 'blocked') {
+        if (typeof console !== 'undefined' && console.warn) {
+            console.warn('[DEPRECATED] Creating advance_recorded with blocked outcome. ' +
+                'Use blocked_attempt nodes instead (see ADR 008). ' +
+                'This path will be removed in 2 releases. ' +
+                'Set USE_BLOCKED_NODES=true to use the new model.');
+        }
         if (outputsToAppend && outputsToAppend.length > 0) {
             return (0, neverthrow_1.err)({
                 code: 'INVARIANT_VIOLATION',
@@ -72,8 +78,12 @@ function buildAckAdvanceAppendPlanV1(args) {
     const toNodeId = args.toNodeId;
     const snapshotRef = args.snapshotRef;
     const causeKind = args.causeKind;
+    const toNodeKind = args.toNodeKind ?? 'step';
     const nodeCreatedEventIndex = nextIndexAfterExtra;
     const edgeCreatedEventIndex = nextIndexAfterExtra + 1;
+    if (toNodeKind !== 'step' && toNodeKind !== 'blocked_attempt') {
+        return (0, neverthrow_1.err)({ code: 'INVARIANT_VIOLATION', message: 'toNodeKind must be step|blocked_attempt' });
+    }
     const advancedEvents = [
         {
             v: 1,
@@ -84,7 +94,7 @@ function buildAckAdvanceAppendPlanV1(args) {
             dedupeKey: `node_created:${sessionId}:${runId}:${toNodeId}`,
             scope: { runId, nodeId: toNodeId },
             data: {
-                nodeKind: 'step',
+                nodeKind: toNodeKind,
                 parentNodeId: fromNodeId,
                 workflowHash,
                 snapshotRef,

package/dist/v2/durable-core/domain/artifact-contract-validator.d.ts

@@ -0,0 +1,31 @@
+import type { Result } from 'neverthrow';
+import type { OutputContract } from '../../../types/workflow-definition.js';
+export type ArtifactContractValidationError = {
+    readonly code: 'MISSING_REQUIRED_ARTIFACT';
+    readonly contractRef: string;
+    readonly message: string;
+} | {
+    readonly code: 'INVALID_ARTIFACT_SCHEMA';
+    readonly contractRef: string;
+    readonly message: string;
+    readonly issues: readonly string[];
+} | {
+    readonly code: 'UNKNOWN_CONTRACT_REF';
+    readonly contractRef: string;
+    readonly message: string;
+};
+export type ArtifactContractValidationResult = {
+    readonly valid: true;
+    readonly artifact: unknown;
+} | {
+    readonly valid: false;
+    readonly error: ArtifactContractValidationError;
+};
+export declare function validateArtifactContract(artifacts: readonly unknown[], contract: OutputContract): ArtifactContractValidationResult;
+export declare function requiresArtifactValidation(outputContract: OutputContract | undefined): boolean;
+export declare function formatArtifactValidationError(error: ArtifactContractValidationError): {
+    readonly code: string;
+    readonly message: string;
+    readonly suggestedFix?: string;
+};
+export declare function extractValidatedArtifact(artifacts: readonly unknown[], contract: OutputContract): Result<unknown, ArtifactContractValidationError>;

package/dist/v2/durable-core/domain/artifact-contract-validator.js

@@ -0,0 +1,98 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.validateArtifactContract = validateArtifactContract;
+exports.requiresArtifactValidation = requiresArtifactValidation;
+exports.formatArtifactValidationError = formatArtifactValidationError;
+exports.extractValidatedArtifact = extractValidatedArtifact;
+const neverthrow_1 = require("neverthrow");
+const index_js_1 = require("../schemas/artifacts/index.js");
+function validateArtifactContract(artifacts, contract) {
+    const { contractRef, required = true } = contract;
+    if (!(0, index_js_1.isValidContractRef)(contractRef)) {
+        return {
+            valid: false,
+            error: {
+                code: 'UNKNOWN_CONTRACT_REF',
+                contractRef,
+                message: `Unknown artifact contract reference: ${contractRef}`,
+            },
+        };
+    }
+    switch (contractRef) {
+        case index_js_1.LOOP_CONTROL_CONTRACT_REF:
+            return validateLoopControlContract(artifacts, contractRef, required);
+        default:
+            return {
+                valid: false,
+                error: {
+                    code: 'UNKNOWN_CONTRACT_REF',
+                    contractRef,
+                    message: `No validator implemented for contract: ${contractRef}`,
+                },
+            };
+    }
+}
+function validateLoopControlContract(artifacts, contractRef, required) {
+    const loopControlArtifacts = artifacts.filter(index_js_1.isLoopControlArtifact);
+    if (loopControlArtifacts.length === 0) {
+        if (required) {
+            return {
+                valid: false,
+                error: {
+                    code: 'MISSING_REQUIRED_ARTIFACT',
+                    contractRef,
+                    message: `Required artifact missing: ${contractRef}. Agent must provide an artifact with kind='wr.loop_control'.`,
+                },
+            };
+        }
+        return { valid: true, artifact: null };
+    }
+    const artifact = loopControlArtifacts[0];
+    const parseResult = index_js_1.LoopControlArtifactV1Schema.safeParse(artifact);
+    if (!parseResult.success) {
+        const issues = parseResult.error.issues.map(issue => `${issue.path.join('.')}: ${issue.message}`);
+        return {
+            valid: false,
+            error: {
+                code: 'INVALID_ARTIFACT_SCHEMA',
+                contractRef,
+                message: `Artifact schema validation failed for ${contractRef}`,
+                issues,
+            },
+        };
+    }
+    return { valid: true, artifact: parseResult.data };
+}
+function requiresArtifactValidation(outputContract) {
+    if (!outputContract)
+        return false;
+    return outputContract.required !== false;
+}
+function formatArtifactValidationError(error) {
+    switch (error.code) {
+        case 'MISSING_REQUIRED_ARTIFACT':
+            return {
+                code: 'MISSING_REQUIRED_OUTPUT',
+                message: error.message,
+                suggestedFix: `Provide an artifact with kind matching the contract: ${error.contractRef}`,
+            };
+        case 'INVALID_ARTIFACT_SCHEMA':
+            return {
+                code: 'INVALID_REQUIRED_OUTPUT',
+                message: `${error.message}: ${error.issues.join('; ')}`,
+                suggestedFix: `Fix the artifact schema errors and retry`,
+            };
+        case 'UNKNOWN_CONTRACT_REF':
+            return {
+                code: 'INVARIANT_VIOLATION',
+                message: error.message,
+            };
+    }
+}
+function extractValidatedArtifact(artifacts, contract) {
+    const result = validateArtifactContract(artifacts, contract);
+    if (result.valid) {
+        return (0, neverthrow_1.ok)(result.artifact);
+    }
+    return (0, neverthrow_1.err)(result.error);
+}

package/dist/v2/durable-core/domain/blocked-node-builder.d.ts

@@ -0,0 +1,20 @@
+import { type Result } from 'neverthrow';
+import type { Sha256PortV2 } from '../../ports/sha256.port.js';
+import type { AttemptId } from '../ids/index.js';
+import type { ExecutionSnapshotFileV1 } from '../schemas/execution-snapshot/index.js';
+import type { BlockerReportV1, ReasonV1 } from './reason-model.js';
+export type BlockedNodeBuildError = {
+    readonly code: 'BLOCKED_NODE_INVARIANT_VIOLATION';
+    readonly message: string;
+} | {
+    readonly code: 'BLOCKED_NODE_UNSUPPORTED_STATE';
+    readonly message: string;
+};
+export declare function buildBlockedNodeSnapshot(args: {
+    readonly priorSnapshot: ExecutionSnapshotFileV1;
+    readonly primaryReason: ReasonV1;
+    readonly attemptId: AttemptId;
+    readonly validationRef: string;
+    readonly blockers: BlockerReportV1;
+    readonly sha256: Sha256PortV2;
+}): Result<ExecutionSnapshotFileV1, BlockedNodeBuildError>;