@intx/workflow-host 0.2.2 → 0.3.0

package/dist/adapters/step-invoker.js

@@ -53,6 +53,7 @@
 // Multi-step steps pass no cache and keep instantiate-send-teardown.
 import { createAgent, } from "@intx/agent";
 import { getLogger } from "@intx/log";
+import { createInboundMessage } from "@intx/mime";
 const logger = getLogger(["workflow-host", "step-invoker"]);
 /**
  * Construct the production `WorkflowRuntimeEnv.StepInvoker` adapter.
@@ -101,8 +102,7 @@ async function invokeColdStep(opts, agentFactory, req) {
     // flow through by default.
     const eventForward = subscribeAgentEvents(agent, opts.onEvent);
     try {
-        const sendResult = await sendWithAbort(agent, req, { closeOnAbort: true });
-        return { output: { reply: sendResult.reply, turn: sendResult.turn } };
+        return stepResultFromSend(await sendWithAbort(agent, req, { closeOnAbort: true }));
     }
     finally {
         // `close` is idempotent: a second call after the send already
@@ -177,8 +177,7 @@ async function invokeWarmStep(opts, warmCache, agentFactory, req) {
         warmCache.setEventSink(key, opts.onEvent);
     }
     try {
-        const sendResult = await sendWithAbort(agent, req, { closeOnAbort: false });
-        return { output: { reply: sendResult.reply, turn: sendResult.turn } };
+        return stepResultFromSend(await sendWithAbort(agent, req, { closeOnAbort: false }));
     }
     finally {
         // Do NOT close the agent or drain its forwarder: both span
@@ -213,6 +212,18 @@ async function buildStepAgent(opts, agentFactory, req) {
 /**
  * Drive one `agent.send`, racing it against the step's abort signal.
  *
+ * The message sent depends on `req.resume` and its kind. A first invocation
+ * sends the synthesized `req.input` content. An `"approval"` resume sends the
+ * full correlated `InboundMessage` built from `req.resume`, whose
+ * `headers.interchangeCorrelationId` routes through the reactor's
+ * `tryCorrelate` to match the rehydrated gate and resume the parked cycle --
+ * no second inference cycle. An `"input"` resume sends the decision as plain
+ * synthesized content, exactly like a first invocation: it is the step's next
+ * turn, with no gate to correlate. Because every path goes through
+ * `agent.send`, the returned `SendResult` carries the reactor's full settle
+ * arm set: a cycle that parks on a gate settles as `"suspended"` regardless
+ * of how the turn was delivered.
+ *
  * `closeOnAbort` selects the abort semantics:
  *   - `true` (cold path): the in-flight send is left to settle via
  *     `agent.close()` in the caller's `finally`, which aborts the
@@ -253,16 +264,41 @@ async function sendWithAbort(agent, req, cfg) {
             };
             abortListener = onAbort;
             req.signal.addEventListener("abort", onAbort, { once: true });
-            let synthesized;
+            let message;
             try {
-                synthesized = synthesizeInputContent(req.input);
+                // How the resumed input is delivered depends on the park kind:
+                //
+                // - `"approval"`: the reactor is parked mid-turn on a tool/authz gate.
+                //   Build the full `InboundMessage` stamped with `resume.correlationId`
+                //   so the header reaches the reactor's `tryCorrelate` and matches the
+                //   rehydrated gate. The object form is load-bearing -- a plain string
+                //   would drop the correlation id and the resumed cycle would never
+                //   match.
+                // - `"input"`: the step re-armed between turns; the decision is simply
+                //   the next user turn, with NO gate to correlate. Deliver it as the
+                //   plain synthesized content, exactly as a first invocation does.
+                //
+                // A first invocation (no resume) sends the plain synthesized input;
+                // `agent.send` stamps its own synthetic addressing.
+                message =
+                    req.resume === undefined
+                        ? synthesizeInputContent(req.input)
+                        : req.resume.kind === "input"
+                            ? synthesizeInputContent(req.resume.decision)
+                            : createInboundMessage({
+                                from: "signal@local",
+                                to: "agent@local",
+                                content: synthesizeInputContent(req.resume.decision),
+                                interchangeType: "conversation.message",
+                                correlationId: req.resume.correlationId,
+                            });
             }
             catch (cause) {
                 reject(cause instanceof Error ? cause : new Error(String(cause)));
                 return;
             }
             const sendOpts = cfg.closeOnAbort ? undefined : { signal: req.signal };
-            agent.send(synthesized, sendOpts).then(resolve, (cause) => {
+            agent.send(message, sendOpts).then(resolve, (cause) => {
                 reject(cause instanceof Error ? cause : new Error(String(cause)));
             });
         });
@@ -323,6 +359,47 @@ function subscribeAgentEvents(agent, onEvent) {
 function wrapAuthorize(workflowAuthorize, authzContext) {
     return async (resource, action) => workflowAuthorize(resource, action, authzContext);
 }
+/**
+ * Translate a settled `SendResult` into the step's `StepInvokeResult`.
+ *
+ * A `"reply"` outcome carries the assistant's reply and full-fidelity
+ * turn, which become the step output so downstream consumers can read
+ * either shape.
+ *
+ * A `"suspended"` outcome hands the workflow runtime the parked reactor's
+ * `correlationId`: the reactor parked on a gate awaiting an external
+ * decision. The runtime parks the step on the reserved signal channel for
+ * that correlation and, when the decision is delivered, re-invokes with
+ * `resume` so `sendWithAbort` sends the correlated inbound and drives the
+ * resumed reactor to a real reply -- or, when the resumed cycle re-parks
+ * on a second gate, to another `"suspended"` outcome that flows back
+ * through here unchanged.
+ */
+function stepResultFromSend(result) {
+    if (result.type === "suspended") {
+        // The reactor parks only on a tool/authz gate -- an APPROVAL. It never
+        // parks awaiting the next mail (that "input" park is the workflow-host's
+        // decision to re-arm a conversational step, not a reactor outcome), so a
+        // suspended `SendResult` is always an approval and MUST carry a snapshot.
+        // A snapshot-less suspend (e.g. a director `caps.suspend` wired with no
+        // tool definitions) is not a supported approval; classify the failure here
+        // at the producer rather than emitting an ambiguous suspend that the
+        // runtime would have to reject three hops downstream.
+        if (result.approvalSnapshot === undefined) {
+            throw new Error(`reactor suspended on correlation ${result.correlationId} with no ` +
+                `approval snapshot; a snapshot-less suspend is not a supported ` +
+                `approval park`);
+        }
+        return {
+            suspend: {
+                correlationId: result.correlationId,
+                kind: "approval",
+                approvalSnapshot: result.approvalSnapshot,
+            },
+        };
+    }
+    return { output: { reply: result.reply, turn: result.turn } };
+}
 /**
  * Encode the step's resolved `input` as the synthetic inbound message
  * content. The workflow runtime resolves `input` from the step's input

package/dist/child/env-bootstrap.d.ts

@@ -13,9 +13,11 @@
 export declare const REQUIRED_SPAWN_ENV_KEYS: readonly ["IPC_CHANNEL_ID", "IPC_HMAC_KEY", "HOST_PUBKEY", "DEPLOYMENT_ID", "DEFINITION_HASH", "MAILBOX_ADDRESS", "STEP_COUNT"];
 export type RequiredSpawnEnvKey = (typeof REQUIRED_SPAWN_ENV_KEYS)[number];
 /**
- * Parsed and validated spawn-time env. The hex-encoded trust anchors
- * decode to their raw byte representations so the IPC channel
- * constructors can consume them without re-validating the hex shape.
+ * The parsed spawn-time env. The hex-encoded trust anchors decode to their raw
+ * byte representations so the IPC channel constructors can consume them without
+ * re-validating the hex shape. Source-ref is the only deploy lineage, so every
+ * child evaluates the pinned code closure at `closurePackageDir`; the field is
+ * always present.
  */
 export interface SpawnTimeEnv {
     /** Channel identifier minted by the supervisor for this spawn. */
@@ -24,9 +26,15 @@ export interface SpawnTimeEnv {
     hmacKey: Uint8Array;
     /** Supervisor's 32-byte Ed25519 public key for control-frame verification. */
     hostPublicKey: Uint8Array;
-    /** Deployment identity the supervisor manages. */
-    deploymentId: string;
-    /** Content hash of the deployed `WorkflowDefinition`. */
+    /** Anchor run id the supervisor manages. */
+    anchorRunId: string;
+    /**
+     * Content hash of the deployed `WorkflowDefinition`. This is the
+     * hub-approved wire hash the deploy frame carried
+     * (`AgentDeployWorkflow.approvedWireHash`), not a sidecar recompute -- the
+     * hub is the authority, so the child re-verifies its own recompute against
+     * this value.
+     */
     definitionHash: string;
     /** Mail address the deployment registered on the bus. */
     mailboxAddress: string;
@@ -44,6 +52,12 @@ export interface SpawnTimeEnv {
      * cache when set and keeps cold instantiate-send-teardown otherwise.
      */
     warmKeep: boolean;
+    /**
+     * Sidecar-local dir of the materialized workflow-definition closure the child
+     * evaluates to a live definition and re-verifies by project-then-hash.
+     * Source-ref is the only deploy lineage, so it is always present.
+     */
+    closurePackageDir: string;
 }
 /**
  * Parse and validate `process.env`-shaped input into the typed

package/dist/child/env-bootstrap.js

@@ -64,6 +64,13 @@ const SpawnTimeEnvShape = type({
     // so the warm-keep decision is deterministic and a multi-step agent is
     // never warm-kept by a silent default.
     "WARM_KEEP?": "string",
+    // Sidecar-local directory of the materialized workflow-definition closure the
+    // deployment evaluates. Source-ref is the only deploy lineage, so the child
+    // always evaluates a pinned code closure to a LIVE definition and re-verifies
+    // it by project-then-hash; there is nothing to evaluate without this dir, so
+    // it is required. The sidecar computes it when it applies the frozen closure
+    // and threads it here; it never travels on the hub deploy frame.
+    CLOSURE_PACKAGE_DIR: "string > 0",
 }).onUndeclaredKey("ignore");
 /**
  * Parse and validate `process.env`-shaped input into the typed
@@ -108,7 +115,7 @@ export function parseSpawnTimeEnv(rawEnv) {
         channelId: validated.IPC_CHANNEL_ID,
         hmacKey,
         hostPublicKey,
-        deploymentId: validated.DEPLOYMENT_ID,
+        anchorRunId: validated.DEPLOYMENT_ID,
         definitionHash: validated.DEFINITION_HASH,
         mailboxAddress: validated.MAILBOX_ADDRESS,
         stepCount,
@@ -116,5 +123,6 @@ export function parseSpawnTimeEnv(rawEnv) {
         // absence) reads false. Warm-keep is opt-in and deterministic; a
         // typo'd or partial value must not silently enable it.
         warmKeep: validated.WARM_KEEP === "true",
+        closurePackageDir: validated.CLOSURE_PACKAGE_DIR,
     };
 }

package/dist/child/index.d.ts

@@ -1,9 +1,10 @@
-export { createCredentialsBackedAuthorize, hashGrants, runWorkflowChild, type ChildStepInvoker, type CredentialsSnapshotRef, type DrainController, type GrantEvaluator, type RunWorkflowChildBindings, type RunWorkflowChildOpts, type RunWorkflowChildResult, type SourcesSnapshotRef, type SubstrateWriteResponseSink, } from "./run-child.js";
+export { createCredentialsBackedAuthorize, hashGrants, runWorkflowChild, type ChildStepInvoker, type CredentialsSnapshotRef, type CredentialWiring, type DrainController, type GrantEvaluator, type RunWorkflowChildBindings, type RunWorkflowChildOpts, type RunWorkflowChildResult, type SourcesSnapshotRef, type SubstrateWriteResponseSink, } from "./run-child.js";
 export { createChildSubstrateWriteBridge, type ChildSubstrateWriteBridge, type CreateChildSubstrateWriteBridgeOpts, type SubstrateWriteRequest, } from "./substrate-write-bridge.js";
 export { createChildOutboundMailBridge, type ChildOutboundMailBridge, type CreateChildOutboundMailBridgeOpts, } from "./outbound-mail-bridge.js";
 export { createSupervisorBackedTransport } from "./supervisor-backed-transport.js";
 export { createProxyWorkflowRunRepoStore, type CreateProxyWorkflowRunRepoStoreOpts, } from "./proxy-repo-store.js";
 export { parseSpawnTimeEnv, type SpawnTimeEnv } from "./env-bootstrap.js";
 export { discoverInFlightRuns, type DiscoverRunsOpts, type DiscoveredRun, } from "./self-discovery.js";
+export type { LoadParkedApproval } from "./parked-correlations.js";
 export { createWarmAgentCache, type WarmAgentCache, type WarmEventSinkRef, } from "./warm-agent-cache.js";
 export { EVENT_CHANNEL_FD, runWorkflowChildFromProcessEnv, type RunWorkflowChildFromProcessEnvOpts, type SubstrateFactory, type SubstrateFactoryEnv, } from "./from-process-env.js";

package/dist/child/parked-correlations.d.ts

@@ -0,0 +1,42 @@
+import type { RepoId, RepoStore as SubstrateRepoStore } from "@intx/hub-sessions/substrate";
+import { type RepoStore as RuntimeRepoStore } from "@intx/workflow";
+import type { ApprovalSnapshot, ControlParkKind } from "@intx/types/runtime";
+/**
+ * Recover the durable approval snapshot for one parked control-plane
+ * correlation. The child owns enumeration; the host owns the per-step
+ * on-disk layout (cold vs warm), so the snapshot read is a host binding.
+ * Returns `undefined` when no pending operation for the correlation carries
+ * a snapshot.
+ */
+export type LoadParkedApproval = (args: {
+    runId: string;
+    stepId: string;
+    attempt: number;
+    correlationId: string;
+}) => Promise<ApprovalSnapshot | undefined>;
+/**
+ * One parked control-plane correlation: the child-supplied half of a
+ * suspension registration. `parkKind` discriminates approval parks
+ * (which carry a snapshot) from input parks (which do not).
+ */
+export interface ParkedApprovalCorrelation {
+    runId: string;
+    correlationId: string;
+    parkKind: ControlParkKind;
+    snapshot?: ApprovalSnapshot;
+}
+export interface CollectParkedApprovalCorrelationsOpts {
+    substrate: SubstrateRepoStore;
+    repoId: RepoId;
+    runtimeRepoStore: RuntimeRepoStore;
+    loadParkedApproval?: LoadParkedApproval;
+}
+/**
+ * Enumerate every in-flight run's reduced state and return one entry per step
+ * parked on a control-plane approval channel. Throws when a park is found but
+ * no `loadParkedApproval` binding is wired to recover its snapshot, or when
+ * the binding returns no snapshot for an enumerated park -- both are
+ * disagreements between the reduced state and the durable store that must not
+ * silently drop a correlation the hub is waiting to register.
+ */
+export declare function collectParkedApprovalCorrelations(opts: CollectParkedApprovalCorrelationsOpts): Promise<ParkedApprovalCorrelation[]>;

package/dist/child/parked-correlations.js

@@ -0,0 +1,80 @@
+// Enumerate a child's currently-parked approval correlations from durable
+// state, so the child can answer a supervisor `parked-correlations.request`.
+//
+// Enumeration keys on REDUCED step state, never on raw `SignalAwaited` log
+// events. `parkOnSignal` commits `SignalAwaited` to the durable log before it
+// checks for the approval snapshot, so a snapshot-less correlated suspend (a
+// director `caps.suspend`, an unwired authz gate) leaves a control-plane
+// `SignalAwaited` in the log yet reduces to `phase === "failed"` -- never
+// `awaiting-signal`, and never a hub row. Filtering on the reduced
+// `awaiting-signal` phase therefore surfaces only the parks that carry a
+// durable snapshot by construction; a snapshot-less enumerated step is a
+// disagreement between the log and the step store, which this module surfaces
+// loudly rather than dropping.
+import { controlParkKindOf, } from "@intx/workflow";
+import { correlationIdFromSignalName } from "@intx/types";
+import { discoverInFlightRuns } from "./self-discovery.js";
+/**
+ * Enumerate every in-flight run's reduced state and return one entry per step
+ * parked on a control-plane approval channel. Throws when a park is found but
+ * no `loadParkedApproval` binding is wired to recover its snapshot, or when
+ * the binding returns no snapshot for an enumerated park -- both are
+ * disagreements between the reduced state and the durable store that must not
+ * silently drop a correlation the hub is waiting to register.
+ */
+export async function collectParkedApprovalCorrelations(opts) {
+    const discovered = await discoverInFlightRuns({
+        substrate: opts.substrate,
+        repoId: opts.repoId,
+        runtimeRepoStore: opts.runtimeRepoStore,
+    });
+    const out = [];
+    for (const run of discovered) {
+        for (const step of run.resumedState.steps.values()) {
+            if (step.phase !== "awaiting-signal")
+                continue;
+            const awaited = step.awaitingSignal;
+            if (awaited === undefined)
+                continue;
+            const correlationId = correlationIdFromSignalName(awaited.name);
+            if (correlationId === undefined)
+                continue;
+            // An `"input"` park (a long-lived run awaiting its next mail) reduces to
+            // the same `awaiting-signal` on a reserved channel as an approval, but it
+            // carries NO snapshot and is never hub-registered -- the run's owner
+            // delivers the input directly. Skip it: enumerating it would call
+            // loadParkedApproval, get no snapshot, and throw below, taking the whole
+            // deployment's approval re-registration down on every reconnect.
+            // `controlParkKindOf` is the single point that reads a reserved-channel
+            // park's kind; an absent kind is a legacy approval, not an input park.
+            const parkKind = controlParkKindOf(awaited);
+            if (parkKind === "input") {
+                out.push({
+                    runId: run.runId,
+                    correlationId,
+                    parkKind: "input",
+                });
+                continue;
+            }
+            if (opts.loadParkedApproval === undefined) {
+                throw new Error(`workflow-child parked-correlations: run ${run.runId} step ${step.stepId} is parked on control-plane correlation ${correlationId}, but no loadParkedApproval binding is wired to recover its snapshot`);
+            }
+            const snapshot = await opts.loadParkedApproval({
+                runId: run.runId,
+                stepId: step.stepId,
+                attempt: step.currentAttempt,
+                correlationId,
+            });
+            if (snapshot === undefined) {
+                throw new Error(`workflow-child parked-correlations: reduced state shows run ${run.runId} step ${step.stepId} awaiting control-plane correlation ${correlationId} (attempt ${String(step.currentAttempt)}), but durable storage carries no approval snapshot for it; the run log and the step store disagree`);
+            }
+            out.push({
+                runId: run.runId,
+                correlationId,
+                parkKind: "approval",
+                snapshot,
+            });
+        }
+    }
+    return out;
+}

package/dist/child/proxy-repo-store.d.ts

@@ -5,8 +5,9 @@ export interface CreateProxyWorkflowRunRepoStoreOpts {
      * Bare substrate handle the child opens against the shared on-disk
      * data dir. Used for the read-only methods that consult the
      * substrate's local state -- `getRepoDir` (path computation, no
-     * I/O), `resolveRef`, `listRefs`, `resolveHead`, `createPack`. The
-     * bare store is never used as a writer here; its
+     * I/O), `resolveRef`, `listRefs`, `resolveHead`, `openCommittedReads`,
+     * `openCommittedReadsAtCommit`, `createPack`. The bare store is never
+     * used as a writer here; its
      * `writeTreePreservingPrefix` / `writeTree` / `receivePack` are not
      * reachable through this proxy.
      */

package/dist/child/proxy-repo-store.js

@@ -117,6 +117,8 @@ export function createProxyWorkflowRunRepoStore(opts) {
         listRefs: bareStore.listRefs.bind(bareStore),
         resolveHead: bareStore.resolveHead.bind(bareStore),
         getRepoDir: bareStore.getRepoDir.bind(bareStore),
+        openCommittedReads: bareStore.openCommittedReads.bind(bareStore),
+        openCommittedReadsAtCommit: bareStore.openCommittedReadsAtCommit.bind(bareStore),
         subscribe(_principal, repoId, ref, subOpts) {
             // Synthesizing the subscribe surface in the proxy: the bare
             // store's `subscribe` would only fire from its own writes, but

package/dist/child/run-child.d.ts

@@ -1,13 +1,15 @@
 import type { Principal, RepoId, RepoStore as SubstrateRepoStore } from "@intx/hub-sessions/substrate";
-import type { DirectorRegistry } from "@intx/agent";
 import type { AuthzCallResult } from "@intx/inference";
-import type { RunResult, Scheduler, StepInvokeRequest, StepInvokeResult, SpawnChildWorkflow, WorkflowAuthorizeFn } from "@intx/workflow";
+import type { RunResult, Scheduler, ReadParkedApprovalOps, StepInvokeRequest, StepInvokeResult, SpawnChildWorkflow, WorkflowAuthorizeFn, WorkflowPark } from "@intx/workflow";
 import { type WorkflowHostDrainController } from "../drain-controller.js";
 import type { InferenceSource } from "@intx/types/runtime";
+import type { CredentialDelivery } from "@intx/types/sidecar";
+import type { RunSuspendableChild, RunChildWorkflow } from "../adapters/spawn-child.js";
 import { type ControlChannelSender, type ControlPayload, type EventPayload, type FrameWriter, type NdjsonReader, type NdjsonWriter } from "../ipc/index.js";
 import type { CredentialsSnapshot } from "../supervisor/credentials.js";
 import { hashGrants } from "../supervisor/credentials.js";
 import type { SpawnTimeEnv } from "./env-bootstrap.js";
+import { type LoadParkedApproval } from "./parked-correlations.js";
 import type { ChildOutboundMailBridge } from "./outbound-mail-bridge.js";
 import { type WarmAgentCache } from "./warm-agent-cache.js";
 /**
@@ -27,6 +29,16 @@ import { type WarmAgentCache } from "./warm-agent-cache.js";
 export type CredentialsSnapshotRef = {
     current: CredentialsSnapshot | null;
 };
+/**
+ * The deployment's decrypted credential material and per-handle descriptors,
+ * held through a mutable reference and swapped wholesale on a rotation push (a
+ * revoked credential arrives by omission, so the swap evicts it). The secret
+ * lives ONLY here -- read at tool-invoke time through the gated capability --
+ * and is never copied into a snapshot, event, or state.
+ */
+export type CredentialMaterialRef = {
+    current: CredentialDelivery | null;
+};
 /**
  * Per-step inference-source table the build path reads through a mutable
  * reference, keyed by stepId. Each value is the step's ordered failover
@@ -92,7 +104,24 @@ export type DrainController = WorkflowHostDrainController;
  * by the run-loop (`runWorkflowChild`), not the binding: the binding
  * only reads it through to the adapter.
  */
-export type ChildStepInvoker = (req: StepInvokeRequest, onEvent: (event: EventPayload) => void, authorize: WorkflowAuthorizeFn, warmCache: WarmAgentCache | undefined, sourcesRef: SourcesSnapshotRef) => Promise<StepInvokeResult>;
+/**
+ * Per-run credential inputs the top-level step invoker carries to the
+ * substrate: the live material cell the control channel writes each delivery
+ * into, and a resolver for a step's grants (which the substrate gates
+ * credential use against). The substrate combines these with its own static
+ * provider registry to assemble each tool bundle's `credentials` capability.
+ *
+ * Grants are typed `readonly unknown[]` here: this package owns no grant
+ * grammar (the credentials snapshot's grants are `unknown[]` throughout), so
+ * the substrate casts to its `GrantRule` shape at its own boundary, exactly
+ * as the grant evaluator does. The cell is read live per use, so a rotation or
+ * a revoking re-push reaches an already-shaped handle without a rebuild.
+ */
+export interface CredentialWiring {
+    readonly materialRef: CredentialMaterialRef;
+    readonly resolveStepGrants: (stepId: string) => readonly unknown[];
+}
+export type ChildStepInvoker = (req: StepInvokeRequest, onEvent: (event: EventPayload) => void, authorize: WorkflowAuthorizeFn, warmCache: WarmAgentCache | undefined, sourcesRef: SourcesSnapshotRef, credentialWiring: CredentialWiring) => Promise<StepInvokeResult>;
 /**
  * Bindings the binary owns: per-deployment substrate identity,
  * principal credentials, the runtime-supplied callbacks the
@@ -114,10 +143,6 @@ export interface RunWorkflowChildBindings {
      * the host's substrate accepts for `runs/<runId>/` writes.
      */
     principal: Principal;
-    /** Workflow-asset repo identity (used to load `workflow.json`). */
-    workflowDefinitionRepoId: RepoId;
-    /** Workflow-asset ref the deploy orchestrator wrote to. */
-    workflowDefinitionRef: string;
     /**
      * Step-invoker callback the runtime body invokes per step. The
      * shape is the workflow-runtime `StepInvoker` widened with an
@@ -128,11 +153,33 @@ export interface RunWorkflowChildBindings {
      */
     invokeStep: ChildStepInvoker;
     /**
-     * Child-spawn callback the runtime body invokes for `childWorkflow`
-     * primitives. The production binary wires this against
-     * `createWorkflowSpawnChild`; tests inject a stub.
+     * Terminal child-spawn callback the runtime body invokes for a
+     * `childWorkflow` primitive when the deployment embeds NO inline child
+     * import (the map `run-child` lifts is empty). Optional and, in practice,
+     * only a test seam: a production deployment that carries a childWorkflow
+     * always has a non-empty lifted-body map and routes through the in-memory
+     * resolver built from `runChild` below, and one that carries none never
+     * invokes this. A workflow that reaches a childWorkflow with neither this
+     * nor `runChild` wired fails loud at spawn.
+     */
+    spawnChild?: SpawnChildWorkflow;
+    /**
+     * Raw in-process terminal child executor. `run-child` builds the in-memory
+     * childWorkflow resolver from this executor plus the lifted-body map it
+     * extracts after loading the definition -- the parent's own re-verified
+     * closure -- so an owned inline child resolves with NO on-disk read. Parallel
+     * to `runSuspendableChild` for onTrigger bodies. Optional for the same
+     * reason: a child that embeds no childWorkflow import omits it.
+     */
+    runChild?: RunChildWorkflow;
+    /**
+     * Raw in-process suspendable-child executor. `run-child` builds the in-memory
+     * onTrigger-body resolver from this executor plus the bodies map it extracts
+     * AFTER re-evaluating the closure -- the substrate factory cannot build that
+     * resolver because the bodies map does not exist pre-eval. Optional: a child
+     * that runs no onTrigger section omits it.
      */
-    spawnChild: SpawnChildWorkflow;
+    runSuspendableChild?: RunSuspendableChild;
     /** Host-process scheduler singleton. The child consumes the same instance. */
     scheduler: Scheduler;
     /** Grant evaluator wired against the host's grant-rule grammar. */
@@ -152,8 +199,32 @@ export interface RunWorkflowChildBindings {
      * adapter (which roots no per-run scratch of its own) can omit it.
      */
     cleanupRunStorage?: (runId: string) => Promise<void>;
-    /** Optional director registry; defaults to the canonical built-ins. */
-    directors?: DirectorRegistry;
+    /**
+     * Recover the durable approval snapshot for a parked control-plane
+     * correlation, so the child can answer a supervisor
+     * `parked-correlations.request` (the supervisor's re-registration path
+     * after a re-establishment). The child owns enumeration -- it walks its
+     * own reduced run state for `awaiting-signal` steps on control-plane
+     * channels -- but the snapshot lives in per-step durable storage whose
+     * on-disk layout (cold vs warm) the host owns, so the read is a host
+     * binding next to `cleanupRunStorage`. Optional so tests inject a stub and
+     * the recursive child-workflow adapter (which roots no per-step approval
+     * storage) can omit it; a production child that enumerates a parked
+     * control-plane step with no binding wired throws rather than silently
+     * dropping the correlation the hub is waiting to register.
+     */
+    loadParkedApproval?: LoadParkedApproval;
+    /**
+     * Enumerate the durable pending approval operations a crashed-mid-invocation
+     * step left behind, so the resume classifier can recover a step that crashed
+     * across the park boundary (durable `StepStarted`, unflushed `SignalAwaited`)
+     * as `awaiting-signal` rather than failing the run. Reads the same per-step
+     * durable storage as `loadParkedApproval` (cold isogit / warm substrate), so
+     * it is a host binding for the same reason. Optional so tests inject a stub
+     * and the recursive child-workflow adapter can omit it; absent, a crashed
+     * invocation step settles as a terminal failure, the pre-recovery behavior.
+     */
+    readParkedApprovalOps?: ReadParkedApprovalOps;
     /** Optional clock override; production wires `() => new Date()`. */
     clock?: () => Date;
     /** Optional id generator override; production wires a monotonic one. */
@@ -173,6 +244,14 @@ export interface RunWorkflowChildBindings {
      * rather than resolving a default.
      */
     initialSources?: Record<string, InferenceSource[]>;
+    /**
+     * Bootstrap credential material for the deployment's tools, decrypted
+     * hub-side and delivered on the deploy frame so it is resident before any
+     * step runs. Seeds the mutable `credentialMaterialRef` the gated capability
+     * reads. Absent when the deployment binds no credentials; a later
+     * `credentials-updated` control frame refreshes it on rotation.
+     */
+    initialCredentialMaterial?: CredentialDelivery;
     /**
      * Optional override for the child's Ed25519 keypair factory. The
      * child mints a fresh keypair at startup, holds the private half
@@ -286,6 +365,21 @@ export interface RunWorkflowChildResult {
  * exits cleanly).
  */
 export declare function runWorkflowChild(opts: RunWorkflowChildOpts): Promise<RunWorkflowChildResult>;
+/**
+ * Forward a control-plane suspension to the supervisor over the upstream
+ * control channel. Fired from `env.onPark` each time a workflow agent step
+ * parks on a reserved `signalName(correlationId)` channel. The supervisor's
+ * `park.notify` arm stamps the deployment identity it owns and sends a
+ * `signal.correlation.register` frame to the hub.
+ *
+ * Best-effort like `emitTerminalEvent`'s send: a transport failure is logged,
+ * not rethrown. A lost frame means the correlation is not registered and the
+ * parked run cannot be resumed until it is re-registered; the failure surfaces
+ * structurally as a run that never resumes rather than a silent lifecycle
+ * corruption. The register at the hub is idempotent, so a re-park resume's
+ * re-emit is safe.
+ */
+export declare function emitParkNotify(upstreamSender: ControlChannelSender, park: WorkflowPark): Promise<void>;
 /**
  * Mirror a run's terminal status back to the supervisor over the
  * upstream control channel. Fired once per run from the resume and