@relayflows/sdk 2.0.34 → 2.0.36

package/src/authored-flow-executor.ts

@@ -22,6 +22,7 @@ import {
 import { commitAuthoredVerdict } from './authored-completion-record.js';
 import {
   type AgentResult,
+  type DispatchResult,
   type LlmOptions,
   type CloudHelper,
   type CompletionReason as SurfaceCompletionReason,
@@ -38,9 +39,11 @@ import { observeStep, type ProgressEvent } from './progress.js';
 import { parseStepTimeout } from './compile.js';
 import { getAuthoredFlowDefinition } from './authored-flow.js';
 import type { GetFlowDefinition } from './authored-flow-loader.js';
+import type { LoadedAuthoredFlowNode } from './authored-flow-loader.js';
 import type { RunLifecycleOptions } from './cli/run.js';
 import {
   AuthoredFlowExecutionError,
+  type AuthoredFlowSuspension,
   AuthoredHumanParked,
   type AuthoredFlowExecutionErrorCode,
 } from './authored-flow-error.js';
@@ -52,6 +55,7 @@ import {
   verifyAuthoredOperations,
 } from './authored-flow-operation.js';
 import { AuthoredFlowLifecycle } from './authored-flow-lifecycle.js';
+import { AuthoredActivities } from './authored-activity.js';
 import { displayLabel, type AuthoredStepEdges } from './authored-step-index.js';
 import { JournalClient } from './journal-client.js';
 import { PluginError } from './plugin-manifest.js';
@@ -66,6 +70,8 @@ import type {
   CompletionReason as ProtocolCompletionReason,
   RunCompletionReason as ProtocolRunCompletionReason,
 } from './protocol.js';
+import type { AuthoredWorkerSlots } from './worker-slots.js';
+import { childLeaves, helperAuthority, parseDispatchReceipt, resolveDispatchChild } from './authored-dispatch.js';
 
 type Assert<T extends true> = T;
 type Equal<A, B> = [A] extends [B]
@@ -101,6 +107,7 @@ export interface AuthoredExecutionRuntime {
 }
 
 export interface AuthoredFlowExecutionResult {
+  readonly state?: undefined;
   readonly executionRuntime?: AuthoredExecutionRuntime;
   readonly rootRunId?: string;
   readonly name: string;
@@ -114,6 +121,14 @@ export interface AuthoredFlowExecutionResult {
   readonly journalSteps: readonly AuthoredFlowJournalStep[];
 }
 
+/** A body reached a durable event boundary and released its worker lease. */
+export interface AuthoredFlowSuspendedResult {
+  readonly state: 'suspended';
+  readonly name: string;
+  readonly suspension: AuthoredFlowSuspension;
+  readonly journalSteps: readonly AuthoredFlowJournalStep[];
+}
+
 // The authoring SURFACE stays wide: `done()` accepts every
 // `FlowCompletionReason` and refuses the kernel-owned ones at runtime with a
 // diagnostic that names the alternative. The RESULT is narrow, because `done()`
@@ -185,6 +200,20 @@ export interface ExecuteAuthoredFlowOptions {
    * from authored input: direct `/workflows/run` callers control that JSON.
    */
   readonly extensionDispatch?: HostedExtensionDispatch;
+  /** Pinned static `use:` graph available to `f.dispatch`. */
+  readonly flowGraph?: readonly LoadedAuthoredFlowNode[];
+  /** Internal namespace for descendant step/admission identities. */
+  readonly stepPrefix?: string;
+  /** Current child depth. Root is zero; dispatch is capped at three. */
+  readonly dispatchDepth?: number;
+  /** Parent predecessors inherited by the first operation in a child body. */
+  readonly entryAfter?: readonly string[];
+  /** Root-owned budget accumulator shared by every descendant. */
+  readonly sharedBudget?: AuthoredBudget;
+  /** Root-owned worker capacity shared by every descendant. */
+  readonly workerSlots?: AuthoredWorkerSlots;
+  /** Parent helper authority inherited by this dispatched child. */
+  readonly allowedHelperProviders?: ReadonlySet<string>;
 }
 
 export async function executeAuthoredFlow<Input = undefined>(
@@ -209,7 +238,7 @@ export async function executeAuthoredFlow<Input = undefined>(
   };
   const definition = getDefinition<Input>(handle);
   const hostedHandler = extensionHandlerForHostedDispatch(options.extensionDispatch, options.extensions ?? []);
-  const headerFields = Object.keys(definition.header).filter(key => key !== 'tools' && key !== 'budget' && key !== 'memory' && key !== 'version' && key !== 'hooks');
+  const headerFields = Object.keys(definition.header).filter(key => key !== 'tools' && key !== 'budget' && key !== 'memory' && key !== 'version' && key !== 'hooks' && key !== 'use');
   if (definition.header.tools && Object.keys(definition.header.tools).some(key => !['mcp', ...helperProviders.map(p => p.namespace)].includes(key))) headerFields.push('tools');
   if (definition.header.tools?.relayfile !== undefined) headerFields.push('tools.relayfile');
   const helperPreflight = checkSlackHelpers(definition);
@@ -242,7 +271,7 @@ export async function executeAuthoredFlow<Input = undefined>(
     );
   }
 
-  const budget = new AuthoredBudget(definition.header.budget);
+  const budget = options.sharedBudget ?? new AuthoredBudget(definition.header.budget);
   if (definition.header.memory?.agent === true) {
     throw new AuthoredFlowExecutionError('unsupported_header', 'memory.agent requires the follow-up identity-scoped agent memory adapter');
   }
@@ -255,15 +284,35 @@ export async function executeAuthoredFlow<Input = undefined>(
   const journalSteps: AuthoredFlowJournalStep[] = [];
   const authoredSteps: AuthoredFlowOperation<unknown>[] = [];
   const lifecycle = new AuthoredFlowLifecycle();
-  const stepEdges = (step: string): AuthoredStepEdges | undefined => lifecycle.stepEdges(step);
+  const activities = new AuthoredActivities(journal, options.rootRunId);
+  const edgeOverrides = new Map<string, AuthoredStepEdges>();
+  const stepEdges = (step: string): AuthoredStepEdges | undefined => {
+    const overridden = edgeOverrides.get(step);
+    if (overridden !== undefined) return overridden;
+    const local = lifecycle.stepEdges(step);
+    if (local === undefined || (local.after !== undefined && local.after.length > 0) || options.entryAfter === undefined
+      || options.entryAfter.length === 0) return local;
+    return { ...local, after: [...options.entryAfter] };
+  };
   let nextStep = 1;
   let requestedCompletion: LoweredCompletionReason | undefined;
   let requestedDetail: string | undefined;
+  const qualify = (id: string): string => `${options.stepPrefix ?? ''}${id}`;
+  const nextId = (kind: string): string => qualify(`${kind}-${nextStep++}`);
+  const assertHelperAllowed = (provider: string): void => {
+    if (options.allowedHelperProviders !== undefined && !options.allowedHelperProviders.has(provider)) {
+      throw new AuthoredFlowExecutionError(
+        'dispatch_invalid',
+        `child flow "${definition.name}" attempted helper provider "${provider}" outside its parent's granted integrations`,
+      );
+    }
+  };
 
   const lowerDeterministic = authoredDeterministicRunner(
     definition.name, journal, journalSteps, budget, {
       ...(options.rootRunId === undefined ? {} : { rootRunId: options.rootRunId }),
       ...(options.dataDir === undefined ? {} : { dataDir: options.dataDir }),
+      ...(options.signal === undefined ? {} : { signal: options.signal }),
       stepEdges,
     },
   );
@@ -271,6 +320,7 @@ export async function executeAuthoredFlow<Input = undefined>(
   const worker = authoredWorkerRunner(
     definition, journal, flowPath, journalSteps, waitOptions,
     localAgentStream, budget, definition.header.budget, options.rootRunId, options.workerCapacity, stepEdges,
+    options.workerSlots,
   );
 
   /**
@@ -373,7 +423,7 @@ export async function executeAuthoredFlow<Input = undefined>(
   function llmOperation(prompt: string, options: LlmOptions): Step<unknown>;
   function llmOperation(prompt: string | TemplateStringsArray, ...values: unknown[]): Step<unknown> {
     assertOperationAllowed('llm', definition.name, requestedCompletion);
-    const id = `llm-${nextStep++}`;
+    const id = nextId('llm');
     // Hoist the operation reference so the start closure can read the
     // caller's `.gate(config)` at spec-build time. AuthoredFlowOperation
     // begins after construction returns, so `llmOp` is defined by then.
@@ -420,7 +470,7 @@ export async function executeAuthoredFlow<Input = undefined>(
         `f.run options.onNonZero must be 'fail' or 'record' (got ${JSON.stringify(policy)}).`,
       );
     }
-    const id = `run-${nextStep++}`;
+    const id = nextId('run');
     if (policy === 'record') {
       let recordOp!: AuthoredFlowOperation<RunResult>;
       recordOp = new AuthoredFlowOperation<RunResult>(
@@ -451,8 +501,9 @@ export async function executeAuthoredFlow<Input = undefined>(
   const slackRun = options.rootRunId ?? randomUUID();
   function slackOperation<T>(call: SlackCall): Step<T> {
     assertOperationAllowed(`slack.${call.verb}`, definition.name, requestedCompletion);
+    assertHelperAllowed(call.provider);
     const snapshot = snapshotJsonValue(call, 'f.slack call') as unknown as SlackCall;
-    const id = `slack-${slackRun}-${nextStep++}`;
+    const id = qualify(`slack-${slackRun}-${nextStep++}`);
     return trackStep(authoredSteps, new AuthoredFlowOperation<T>(
       id, `slack.${call.verb}`,
       () => assertOperationAllowed(`slack.${call.verb}`, definition.name, requestedCompletion),
@@ -480,8 +531,9 @@ export async function executeAuthoredFlow<Input = undefined>(
     ...createHelpers(<T>(call: HelperCall): Step<T> => {
       const verb = `${call.provider}.${call.verb}`;
       assertOperationAllowed(verb, definition.name, requestedCompletion);
+      assertHelperAllowed(call.provider);
       const snapshot = snapshotJsonValue(call, `f.${verb} call`) as unknown as HelperCall;
-      const id = `${call.provider}-${slackRun}-${nextStep++}`;
+      const id = qualify(`${call.provider}-${slackRun}-${nextStep++}`);
       return trackStep(authoredSteps, new AuthoredFlowOperation<T>(id, verb,
         () => assertOperationAllowed(verb, definition.name, requestedCompletion),
         async () => await runHelperEffect(journal, definition.name, id, snapshot,
@@ -496,7 +548,7 @@ export async function executeAuthoredFlow<Input = undefined>(
     },
     mcp: buildMcpProxy(checkedMcp.inventory, (server, tool, args, known) => {
       assertOperationAllowed('mcp', definition.name, requestedCompletion);
-      const id = `mcp-${nextStep++}`;
+      const id = nextId('mcp');
       return trackStep(authoredSteps, new AuthoredFlowOperation(
         id, 'mcp',
         () => assertOperationAllowed('mcp', definition.name, requestedCompletion),
@@ -516,7 +568,7 @@ export async function executeAuthoredFlow<Input = undefined>(
       assertOperationAllowed('agent', definition.name, requestedCompletion);
       // Authored headers do not yet declare reusable named agents, so the name
       // identifies nothing to the kernel; it is the step's label in the DAG.
-      const id = `agent-${nextStep++}`;
+      const id = nextId('agent');
       let agentOp!: AuthoredFlowOperation<AgentResult>;
       agentOp = new AuthoredFlowOperation<AgentResult>(
         id,
@@ -528,6 +580,17 @@ export async function executeAuthoredFlow<Input = undefined>(
       );
       return trackStep(authoredSteps, agentOp);
     },
+    on(source, activityOptions) {
+      assertOperationAllowed('on', definition.name, requestedCompletion);
+      // Activity ids are root-scoped (`activity-N`); a child's own counter would collide.
+      if ((options.dispatchDepth ?? 0) > 0) {
+        throw new AuthoredFlowExecutionError(
+          'dispatch_invalid',
+          `child flow "${definition.name}" cannot call f.on in this release; activities are root-scoped`,
+        );
+      }
+      return activities.open(source, activityOptions);
+    },
     /**
      * `f.human` (docs/SURFACE.md §1, §7). The question is not a child run: it
      * is the ROOT attempt parking on the kernel's `wait.human`. The body
@@ -545,6 +608,12 @@ export async function executeAuthoredFlow<Input = undefined>(
      */
     human(question, humanOptions) {
       assertOperationAllowed('human', definition.name, requestedCompletion);
+      if ((options.dispatchDepth ?? 0) > 0) {
+        throw new AuthoredFlowExecutionError(
+          'dispatch_invalid',
+          `child flow "${definition.name}" cannot call f.human in this release; the parent owns approval authority`,
+        );
+      }
       if (typeof question !== 'string' || question.trim() === '') {
         throw new AuthoredFlowExecutionError('human_answer_invalid', 'f.human requires a non-empty question');
       }
@@ -558,7 +627,7 @@ export async function executeAuthoredFlow<Input = undefined>(
       if (!parsedTo.ok) {
         throw new AuthoredFlowExecutionError('human_to_invalid', `f.human to ${parsedTo.reason}`);
       }
-      const id = `human-${nextStep++}`;
+      const id = nextId('human');
       const to = humanOptions.to;
       // Hoisted like `llmOp`/`runOp`: the start closure reads the caller's
       // `.gate(config)` at spec-build time, so a named gate on the answer is
@@ -590,13 +659,79 @@ export async function executeAuthoredFlow<Input = undefined>(
       );
       return trackStep(authoredSteps, humanOp);
     },
-    dispatch<T>() {
+    dispatch(flowName, dispatchInput) {
       assertOperationAllowed('dispatch', definition.name, requestedCompletion);
-      throw unsupportedVerb('dispatch');
+      const depth = options.dispatchDepth ?? 0;
+      const child = resolveDispatchChild({
+        handle, definition, graph: options.flowGraph,
+        flowName, depth,
+      });
+      const childDefinition = child.getDefinition(child.handle);
+      const inputSnapshot = snapshotJsonValue(dispatchInput, `f.dispatch(${JSON.stringify(flowName)}) input`);
+      const id = nextId('dispatch');
+      let dispatchOp!: AuthoredFlowOperation<DispatchResult>;
+      dispatchOp = new AuthoredFlowOperation<DispatchResult>(
+        id,
+        'dispatch',
+        () => assertOperationAllowed('dispatch', definition.name, requestedCompletion),
+        async () => {
+          const inheritedAfter = stepEdges(id)?.after ?? [];
+          const currentHelperAuthority = helperAuthority(definition);
+          const allowedHelperProviders = options.allowedHelperProviders === undefined
+            ? currentHelperAuthority
+            : new Set([...currentHelperAuthority].filter(provider => options.allowedHelperProviders!.has(provider)));
+          const childResult = await executeAuthoredFlow(child.handle, journal, inputSnapshot, {
+            getDefinition: child.getDefinition,
+            dataDir: options.dataDir,
+            flowPath: child.path,
+            ...(localAgentStream === undefined ? {} : { localAgentStream }),
+            ...(options.workerCapacity === undefined ? {} : { workerCapacity: options.workerCapacity }),
+            ...(options.rootRunId === undefined ? {} : { rootRunId: options.rootRunId }),
+            flowGraph: options.flowGraph,
+            stepPrefix: `${id}--`,
+            dispatchDepth: depth + 1,
+            entryAfter: inheritedAfter,
+            sharedBudget: budget,
+            ...(worker.slots === undefined ? {} : { workerSlots: worker.slots }),
+            allowedHelperProviders,
+            ...(options.extensions === undefined ? {} : { extensions: options.extensions }),
+            onProgress,
+            ...(options.onWait === undefined ? {} : { onWait: options.onWait }),
+            ...(options.signal === undefined ? {} : { signal: options.signal }),
+          });
+          if (childResult.completionReason !== 'success') {
+            throw new AuthoredFlowExecutionError(
+              'step_failed',
+              `child flow "${childResult.name}" completed with ${childResult.completionReason}`
+                + (childResult.completionDetail === undefined ? '' : `: ${childResult.completionDetail}`),
+              childResult.completionReason === 'step_failed' ? 'step_failed' : undefined,
+            );
+          }
+          const leaves = childLeaves(childResult.journalSteps);
+          edgeOverrides.set(id, {
+            ...displayLabel(childResult.name),
+            ...(leaves.length > 0 ? { after: leaves } : inheritedAfter.length === 0
+              ? {} : { after: inheritedAfter }),
+          });
+          const receipt: DispatchResult = {
+            name: childResult.name,
+            completionReason: 'success',
+            ...(childResult.completionDetail === undefined ? {} : { completionDetail: childResult.completionDetail }),
+          };
+          const literal = `'${JSON.stringify(receipt).replaceAll("'", "'\\''")}'`;
+          const recorded = await lowerDeterministic(
+            id, `printf '%s' ${literal}`, false, undefined, dispatchOp.namedGate,
+          );
+          return parseDispatchReceipt(recorded, id);
+        },
+        lifecycle,
+        displayLabel(flowName),
+      );
+      return trackStep(authoredSteps, dispatchOp);
     },
     hook(name, input) {
       assertOperationAllowed('hook', definition.name, requestedCompletion);
-      const id = `hook-${nextStep++}`;
+      const id = nextId('hook');
       const snapshot = snapshotJsonValue(input, 'f.hook input');
       return trackStep(authoredSteps, new AuthoredFlowOperation<boolean>(
         id, 'hook',
@@ -661,7 +796,7 @@ export async function executeAuthoredFlow<Input = undefined>(
   Object.assign(context, pluginHelpers(checkedMcp.plugins ?? [], (plugin, verb, args) => {
     const label = `${verb.namespace}.${verb.method}`;
     assertOperationAllowed(label, definition.name, requestedCompletion);
-    const id = `plugin-${nextStep++}`;
+    const id = nextId('plugin');
     return trackStep(authoredSteps, new AuthoredFlowOperation(
       id, label, () => assertOperationAllowed(label, definition.name, requestedCompletion),
       () => runPluginEffect(journal, definition.name, id, plugin, verb, args,
@@ -683,6 +818,11 @@ export async function executeAuthoredFlow<Input = undefined>(
     try {
       worker.stop(bodyFailure);
       await stopAuthoredOperations(authoredSteps, bodyFailure);
+      // A durable wait hands execution back to the control plane. Its
+      // subscriptions must keep receiving events while no body is running.
+      const parked = bodyFailure instanceof AuthoredFlowExecutionError
+        && (bodyFailure.code === 'subscription_suspended' || bodyFailure.code === 'human_parked');
+      if (!parked) await activities.closeAll('canceled');
     } finally {
       lifecycle.close();
     }
@@ -710,6 +850,7 @@ export async function executeAuthoredFlow<Input = undefined>(
     try {
       worker.stop(missingCompletion);
       await stopAuthoredOperations(authoredSteps, missingCompletion);
+      await activities.closeAll('canceled');
     } finally {
       lifecycle.close();
     }
@@ -717,6 +858,16 @@ export async function executeAuthoredFlow<Input = undefined>(
   }
   try {
     await verifyAuthoredOperations(definition.name, authoredSteps, lifecycle);
+  } catch (error) {
+    try {
+      await activities.closeAll('canceled');
+    } finally {
+      lifecycle.close();
+    }
+    throw error;
+  }
+  try {
+    await activities.closeAll('run_completed');
   } finally {
     lifecycle.close();
   }
@@ -735,7 +886,7 @@ export async function executeAuthoredFlow<Input = undefined>(
   // explanation the root had already journaled to `run_admission_conflict`.
   // With no detail there is no environment in the command and nothing to
   // commit, so that path is untouched.
-  const terminalId = `complete-${nextStep}`;
+  const terminalId = qualify(`complete-${nextStep}`);
   const verdict = await commitAuthoredVerdict(journal, options.rootRunId, terminalId, {
     reason: requestedCompletion,
     ...(requestedDetail === undefined ? {} : { detail: requestedDetail }),

package/src/authored-flow-loader.ts

@@ -100,6 +100,18 @@ export async function loadAuthoredFlow(path: string, options: LoadAuthoredFlowOp
         }
         dependencies.push(child.path);
       }
+      const childNames = new Set<string>();
+      for (const path of dependencies) {
+        const child = loaded.get(path)!;
+        const name = child.getDefinition(child.handle).name;
+        if (childNames.has(name)) {
+          throw new AuthoredFlowLoadError(
+            `Flow "${absolutePath}" declares two direct use children named "${name}".`,
+            'use_invalid',
+          );
+        }
+        childNames.add(name);
+      }
       const node = Object.freeze({ path: absolutePath, handle, getDefinition, surfaceAuthority, use: Object.freeze(dependencies) });
       loaded.set(absolutePath, node);
       return node;

package/src/authored-mcp.ts

@@ -140,13 +140,13 @@ export async function runMcpEffect(
     childRunId = outcome.run_id;
     if (outcome.status !== 'completed') await completed;
     if (diagnostic !== undefined) {
-      try { await readCompletedStepOutput(journal, outcome.run_id, id, journalSteps); }
+      try { await readCompletedStepOutput(journal, outcome.run_id, id, journalSteps, {}, outcome.status); }
       catch (error) {
         if (!(error instanceof AuthoredFlowExecutionError) || error.code !== 'step_failed') throw error;
         throw new McpStepError(diagnostic, outcome.run_id);
       }
     }
-    const receipt = await readCompletedStepOutput(journal, outcome.run_id, id, journalSteps) as { output: unknown };
+    const receipt = await readCompletedStepOutput(journal, outcome.run_id, id, journalSteps, {}, outcome.status) as { output: unknown };
     return receipt.output;
   } finally {
     clearTimeout(timer);

package/src/authored-node-entry.ts

@@ -75,6 +75,7 @@ try {
       getDefinition: loaded.getDefinition, dataDir: request.dataDir,
       flowPath: request.metadata.flowPath, rootRunId: request.rootRunId,
       extensions: loaded.extensions,
+      flowGraph: loaded.graph,
       localAgentStream: request.localAgentStream, signal: controller.signal,
       ...(request.workerCapacity === undefined ? {} : { workerCapacity: request.workerCapacity }),
       onProgress: event => send({ type: 'progress', event }),
@@ -93,7 +94,9 @@ try {
     // the only one that saw the child's classification.
     ...(error instanceof AuthoredFlowExecutionError ? { code: error.code,
       completionReason: error.completionReason, runId: error.runId,
-      details: error.details, parkCause: error.parkCause } : {}),
+      details: error.details,
+      parkCause: error.parkCause,
+      ...(error.suspension === undefined ? {} : { suspension: error.suspension }) } : {}),
     ...(error instanceof AuthoredHumanParked ? { wait: error.wait } : {}) });
   process.exitCode = 1;
 } finally {

package/src/authored-node-runner.ts

@@ -18,6 +18,7 @@ import type {
 } from './failure-kinds.js';
 import { HUMAN_WAIT_ID } from './authored-human.js';
 import { assertAuthoredPromiseHooks } from './authored-runtime-capability.js';
+import { settlingCompletion } from './step-settling.js';
 
 let embeddedSource: string | undefined;
 /** Installed by the standalone build; never fetched or resolved from a workspace. */
@@ -144,7 +145,8 @@ export async function runAuthoredInNode(
               } else if (typeof message.code === 'string') {
                 const authored = new AuthoredFlowExecutionError(message.code as AuthoredFlowExecutionErrorCode,
                   message.message, message.completionReason, message.runId,
-                  stepFailedFrame(message.details));
+                  stepFailedFrame(message.details),
+                  isSuspension(message.suspension) ? message.suspension : undefined);
                 // Validated, not trusted, like `details`: an unrecognised cause
                 // is dropped so the boundary says nothing about workers rather
                 // than acting on a value this frame could have invented.
@@ -172,6 +174,35 @@ export async function runAuthoredInNode(
   } finally { await rm(directory, { recursive: true, force: true }); }
 }
 
+function isSuspension(value: unknown): value is import('./authored-flow-error.js').AuthoredFlowSuspension {
+  if (typeof value !== 'object' || value === null || Array.isArray(value)) return false;
+  const record = value as Record<string, unknown>;
+  const common = typeof record['subscriptionId'] === 'string' && record['subscriptionId'].length > 0
+    && typeof record['stream'] === 'string' && record['stream'].length > 0
+    && Number.isSafeInteger(record['deadlineAtMs']) && (record['deadlineAtMs'] as number) >= 0;
+  if (!common) return false;
+  if (record['kind'] === 'event_wait') return true;
+  return record['kind'] === 'activation'
+    && Array.isArray(record['eventTypes']) && record['eventTypes'].length > 0
+    && record['eventTypes'].every(type => typeof type === 'string' && type.length > 0)
+    && (record['pattern'] === undefined || isJsonRecord(record['pattern']))
+    && Number.isSafeInteger(record['settleMs']) && (record['settleMs'] as number) >= 0
+    && Number.isSafeInteger(record['idleMs']) && (record['idleMs'] as number) > 0
+    && typeof record['includeSelf'] === 'boolean';
+}
+
+function isJsonRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === 'object' && value !== null && !Array.isArray(value)
+    && Object.values(value).every(isJsonValue);
+}
+
+function isJsonValue(value: unknown): boolean {
+  return value === null || typeof value === 'boolean' || typeof value === 'string'
+    || (typeof value === 'number' && Number.isFinite(value))
+    || (Array.isArray(value) && value.every(isJsonValue))
+    || isJsonRecord(value);
+}
+
 /** A park signal from the child names the question the parent must journal. */
 function isHumanWaitFrame(value: unknown): value is AuthoredHumanWait {
   const wait = value as Partial<AuthoredHumanWait> | null;
@@ -342,15 +373,17 @@ export async function verifyAuthoredNodeResult(
       // step a child spec may carry, and it must have completed too.
       const lowered = spec?.steps ?? [];
       const specShape = lowered.length === 1 || (lowered.length === 2 && lowered[1]?.id === `${claimed.id}.gate`);
-      const completed = entries.filter(entry => entry.entry_type === 'step.completed' && entry.step_id === claimed.id);
-      const gateCompleted = lowered.length === 2
-        ? entries.filter(entry => entry.entry_type === 'step.completed' && entry.step_id === `${claimed.id}.gate`) : [];
+      // Judged against the step's SETTLING completion, the same one the
+      // authored reader returned: a retried attempt (`disposition: retry`,
+      // e.g. crash recovery's `crashed`) journals a completion of its own
+      // ahead of it, so neither a count nor the first entry is the verdict.
+      const completed = settlingCompletion(entries, claimed.id);
+      const gateCompleted = lowered.length === 2 ? settlingCompletion(entries, `${claimed.id}.gate`) : undefined;
       const terminalFacts = entries.filter(entry => entry.entry_type === 'run.completed');
       if (spec?.name !== `${metadata.flowName}/${claimed.id}` || !specShape
-        || step?.id !== claimed.id || completed.length !== 1
-        || completed[0]?.payload?.completionReason !== 'success'
-        || (lowered.length === 2 && (gateCompleted.length !== 1 || gateCompleted[0]?.payload?.completionReason !== 'success'))
-        || terminalFacts.length !== 1 || terminalFacts[0]?.payload?.completionReason !== 'success') invalid(`evidence ${claimed.id} spec=${spec?.name} step=${step?.id} completed=${completed.length}`);
+        || step?.id !== claimed.id || completed?.payload?.completionReason !== 'success'
+        || (lowered.length === 2 && gateCompleted?.payload?.completionReason !== 'success')
+        || terminalFacts.length !== 1 || terminalFacts[0]?.payload?.completionReason !== 'success') invalid(`evidence ${claimed.id} spec=${spec?.name} step=${step?.id} completed=${completed?.payload?.completionReason}`);
       if (claimed === terminal) {
         // The claimed verdict must match the marker the journal actually
         // recorded, so an IPC frame cannot claim `success` over a run whose

package/src/authored-plugin-effect.ts

@@ -125,13 +125,13 @@ export async function runPluginEffect(
       if (dispatchExpired) await cancelChildRun();
       if (outcome.status !== 'completed') await completed;
       if (diagnostic !== undefined) {
-        try { await readCompletedStepOutput(journal, outcome.run_id, id, journalSteps); }
+        try { await readCompletedStepOutput(journal, outcome.run_id, id, journalSteps, {}, outcome.status); }
         catch (error) {
           if (!(error instanceof AuthoredFlowExecutionError) || error.code !== 'step_failed') throw error;
           throw new PluginStepError(diagnostic, outcome.run_id);
         }
       }
-      const receipt = await readCompletedStepOutput(journal, outcome.run_id, id, journalSteps) as { output: unknown };
+      const receipt = await readCompletedStepOutput(journal, outcome.run_id, id, journalSteps, {}, outcome.status) as { output: unknown };
       return receipt.output;
     }, admissionKey), deadline]);
   } finally {

package/src/authored-root.ts

@@ -4,7 +4,7 @@ import { createHash, randomUUID } from 'node:crypto';
 import { readFile } from 'node:fs/promises';
 import { canonicalize } from './canonical.js';
 import { compileSpec, toKernelSpec } from './compile.js';
-import { executeAuthoredFlow, type AuthoredFlowExecutionResult } from './authored-flow-executor.js';
+import { executeAuthoredFlow, type AuthoredFlowExecutionResult, type AuthoredFlowSuspendedResult } from './authored-flow-executor.js';
 import { isDurableCompletionDetail, isLoweredCompletion } from './authored-completion.js';
 import { AUTHORED_ROOT_KIND } from './authored-verdict.js';
 import {
@@ -20,6 +20,11 @@ import { withWorkerLease } from './worker-lease.js';
 import { AuthoredFlowExecutionError, AuthoredHumanParked } from './authored-flow-error.js';
 import { readOpenHumanWaits } from './authored-human.js';
 import { isSurfaceCompletionReason } from './authored-step-output.js';
+import { readSubscriptionPark } from './authored-subscription-park.js';
+
+export type DurableAuthoredFlowResult =
+  | (AuthoredFlowExecutionResult & { readonly rootRunId: string })
+  | (AuthoredFlowSuspendedResult & { readonly rootRunId: string });
 
 /**
  * Taken from the projection module rather than spelled twice: `flows status`
@@ -55,6 +60,8 @@ export interface AuthoredRootSourceAuthority {
 }
 
 export interface DurableAuthoredOptions {
+  /** Preserve root authority even if a child later fails or parks. */
+  readonly onAdmitted?: (runId: string) => void;
   readonly dataDir: string;
   readonly admissionKey?: string;
   readonly localAgentStream?: string;
@@ -69,7 +76,7 @@ export async function executeDurableAuthoredFlow(
   journal: JournalClient,
   input: unknown,
   options: DurableAuthoredOptions,
-): Promise<AuthoredFlowExecutionResult & { readonly rootRunId: string }> {
+): Promise<DurableAuthoredFlowResult> {
   assertAuthoredRuntimeAvailable();
   const source = await readFile(loaded.sourcePath);
   const sources = await Promise.all(loaded.graph.map(async node => Object.freeze({
@@ -106,6 +113,7 @@ export async function executeDurableAuthoredFlow(
       workspace: [], streams: [{ stream, read_offset: 0 }],
     });
     const outcome = await journal.runStart(spec, undefined, admissionKey);
+    options.onAdmitted?.(outcome.run_id);
     if (outcome.status === 'completed') {
       dispatchWait.cancel();
       return await completedRootResult(journal, outcome.run_id);
@@ -119,6 +127,9 @@ export async function executeDurableAuthoredFlow(
     // redelivers only when the former worker connection is gone.
     const resumed = await journal.runResume(outcome.run_id);
     await assertNoOpenHumanWait(journal, resumed);
+    const parked = await readSubscriptionPark(journal, outcome.run_id);
+    if (parked !== undefined) return { state: 'suspended', name: metadata.flowName,
+      suspension: parked, journalSteps: [], rootRunId: outcome.run_id };
     const dispatch = await dispatchWait.promise;
     return await driveRoot(loaded, metadata, journal, peer, dispatch, options);
   } finally {
@@ -132,7 +143,7 @@ export async function resumeDurableAuthoredFlow(
   rootRunId: string,
   journal: JournalClient,
   options: Omit<DurableAuthoredOptions, 'admissionKey'>,
-): Promise<(AuthoredFlowExecutionResult & { readonly rootRunId: string }) | undefined> {
+): Promise<DurableAuthoredFlowResult | undefined> {
   const metadata = await readAuthoredRootMetadata(journal, rootRunId);
   if (metadata === undefined) return undefined;
   assertAuthoredRuntimeAvailable();
@@ -159,6 +170,9 @@ export async function resumeDurableAuthoredFlow(
     assertRootCanDispatch(outcome);
     await assertNoOpenHumanWait(journal, outcome);
     options.lifecycle?.onRunStarted?.({ runId: rootRunId, flow: metadata.flowName, resumed: true });
+    const parked = await readSubscriptionPark(journal, rootRunId);
+    if (parked !== undefined) return { state: 'suspended', name: metadata.flowName,
+      suspension: parked, journalSteps: [], rootRunId };
     const dispatch = await dispatchWait.promise;
     return await driveRoot(loaded, metadata, journal, peer, dispatch, options);
   } finally {
@@ -204,7 +218,7 @@ async function driveRoot(
   peer: JournalClient,
   dispatch: StepDispatchEvent,
   options: Omit<DurableAuthoredOptions, 'admissionKey'>,
-): Promise<AuthoredFlowExecutionResult & { readonly rootRunId: string }> {
+): Promise<DurableAuthoredFlowResult> {
   try {
     const result = await withWorkerLease(peer, dispatch, async rootSignal => {
       const callerSignal = options.lifecycle?.signal;
@@ -228,6 +242,7 @@ async function driveRoot(
           ...(options.workerCapacity === undefined ? {} : { workerCapacity: options.workerCapacity }),
           rootRunId: dispatch.run_id,
           extensions: loaded.extensions,
+          flowGraph: loaded.graph,
           ...options.lifecycle,
           signal: callerSignal === undefined
             ? rootSignal
@@ -247,6 +262,15 @@ async function driveRoot(
     );
     return Object.freeze({ ...result, rootRunId: dispatch.run_id });
   } catch (error) {
+    if (error instanceof AuthoredFlowExecutionError
+      && error.code === 'subscription_suspended'
+      && error.suspension !== undefined) {
+      await peer.subscriptionPark({ run_id: dispatch.run_id, step_id: dispatch.step_id,
+        attempt: dispatch.attempt, idempotency_key: dispatch.idempotency_key,
+        subscription_id: error.suspension.subscriptionId, phase: error.suspension.kind });
+      return Object.freeze({ state: 'suspended' as const, name: metadata.flowName,
+        suspension: error.suspension, journalSteps: Object.freeze([]), rootRunId: dispatch.run_id });
+    }
     if (error instanceof AuthoredHumanParked) {
       // Not a failure: the body reached a question nobody has answered. Park
       // THIS attempt on the kernel's `wait.human` under the body's own wait