@intx/workflow-host 0.3.0 → 0.4.0

package/dist/child/run-child.js

@@ -50,23 +50,24 @@
 // respawn) and does not require a child-side control frame.
 import { getLogger } from "@intx/log";
 import { generateKeyPair } from "@intx/crypto";
-import { base64Decode, hexEncode } from "@intx/types";
-import { readProcessingEntry } from "@intx/hub-sessions/substrate";
-import { rewriteInlineOnTriggerBodies, rewriteInlineChildWorkflowBodies, } from "@intx/workflow";
-import { baseStepId, emptyState, runtimeRun } from "@intx/workflow";
+import { hexEncode } from "@intx/types";
+import { rewriteInlineOnTriggerBodies, rewriteInlineChildWorkflowBodies, enumerateInlineLoopBodies, eagerlyResolveLoopFns, } from "@intx/workflow";
+import { baseStepId, createDefaultActionInvoker, createInMemoryEffectLedger, createLoopIterationHandle, emptyState, runtimeRun, } from "@intx/workflow";
 import { createWorkflowHostDrainController, } from "../drain-controller.js";
 import { createWorkflowRunRepoStore } from "../adapters/repo-store.js";
 import { createWorkflowRunBlobSubstrate } from "../adapters/blob-substrate.js";
+import { createMailPartReader } from "../adapters/mail-part-store.js";
 import { createInMemorySpawnSuspendableChild, createInMemorySpawnChild, } from "../adapters/spawn-child.js";
 import { createControlChannelSender, createEventChannelSender, receiveControlChannel, } from "../ipc/index.js";
+import { runBodyThenCleanup } from "../run-body-then-cleanup.js";
 import { createWorkflowHostSignalChannel } from "../seams/signal-channel.js";
-import { extractConversationText } from "../conversation-text.js";
 import { hashGrants } from "../supervisor/credentials.js";
 import { loadVerifiedWorkflowDefinitionFromClosure } from "./verified-definition-loader.js";
-import { loadWorkflowDirectorRegistryFromClosure } from "../workflow-definition-loader.js";
+import { loadWorkflowActionHandlersFromClosure, loadWorkflowDirectorRegistryFromClosure, loadWorkflowLoopFnsFromClosure, } from "../workflow-definition-loader.js";
 import { discoverInFlightRuns } from "./self-discovery.js";
 import { collectParkedApprovalCorrelations, } from "./parked-correlations.js";
 import { createWarmAgentCache } from "./warm-agent-cache.js";
+import { mergeCredentialDelivery } from "./credential-cell.js";
 const logger = getLogger(["workflow-host", "child"]);
 export function createCredentialsBackedAuthorize(ref, evaluate) {
     return async (resource, action, ctx) => {
@@ -186,6 +187,36 @@ export async function runWorkflowChild(opts) {
     const childRewrite = rewriteInlineChildWorkflowBodies(definition);
     definition = childRewrite.workflow;
     const childBodiesMap = new Map(childRewrite.bodies.map((b) => [b.ref, b.definition]));
+    // A loop iteration runs its body as a suspendable child through the same seam
+    // an onTrigger body uses, so register each top-level loop body in `bodiesMap`
+    // under its `<workflowId>__<stepId>` ref. Unlike an onTrigger or childWorkflow
+    // body, a loop keeps its body INLINE on the primitive -- both hash layers
+    // project the body inline, so rewriting the primitive would change every
+    // existing loop's hash. `enumerateInlineLoopBodies` mints a ref-keyed COPY and
+    // leaves the primitive untouched, and a given step is exactly one primitive
+    // kind, so a loop ref never collides with an onTrigger or childWorkflow ref.
+    //
+    // A loop body may itself contain a `childWorkflow` grandchild: rewrite the
+    // COPY's inline children to `{ ref }` (the primitive, and thus the hash, is
+    // untouched) and fold the extracted grandchildren into `childBodiesMap` HERE
+    // -- before the eager loop-fn/handler resolution and the terminal-childWorkflow
+    // host selection below, both of which read `childBodiesMap`. Merging later
+    // would resolve a grandchild's refs mid-run instead of at establish, and would
+    // leave `childBodiesMap` empty for a deployment whose only child is a
+    // loop-body grandchild, so its spawn would find no wired terminal host.
+    // Keep each loop body's PRE-rewrite form (its childWorkflow grandchild still
+    // inline) keyed by ref: the grants cap for a loop iteration re-walks it, and
+    // capping the rewritten `{ ref }` form would skip -- and so under-authorize --
+    // the grandchild's declared resources.
+    const loopBodyPreRewrite = new Map();
+    for (const loopBody of enumerateInlineLoopBodies(definition)) {
+        loopBodyPreRewrite.set(loopBody.ref, loopBody.definition);
+        const bodyRewrite = rewriteInlineChildWorkflowBodies(loopBody.definition);
+        bodiesMap.set(loopBody.ref, bodyRewrite.workflow);
+        for (const grandchild of bodyRewrite.bodies) {
+            childBodiesMap.set(grandchild.ref, grandchild.definition);
+        }
+    }
     // Directors resolve from the pinned closure so a custom director authored in
     // the workflow's own package runs. Loading directors OUTSIDE the
     // definition-hash re-verify is safe: the approved hash pins each director's
@@ -196,21 +227,44 @@ export async function runWorkflowChild(opts) {
     const directors = await loadWorkflowDirectorRegistryFromClosure({
         packageDir: opts.env.closurePackageDir,
     });
-    // Suspendable-child (onTrigger body) resolver, selected ONCE per deployment:
-    // the bodies map is immutable and the per-run `onEvent` is injected later in
-    // `buildRuntimeEnv`. Resolve each body from the parent's in-memory closure
-    // (already re-verified above) via the raw executor binding. A deployment that
-    // carries bodies but whose host wired no executor is a misconfiguration --
-    // fail loud at startup rather than silently falling back to a disk read (the
-    // exact behaviour this arm exists to avoid). A deployment with no onTrigger
-    // body leaves the host undefined; its suspendable-child slot is never invoked.
+    // Loop `while`/`carry` functions resolve from the pinned closure's
+    // `interchange.loops` module, loaded alongside the directors and OUTSIDE the
+    // definition-hash re-verify for the same reason: the approved hash pins each
+    // ref string and the closure's SRI pins the module bytes. Resolve every loop
+    // ref reachable from the definition (its own loop bodies, and the lifted
+    // onTrigger/childWorkflow bodies, which share this same registry at runtime)
+    // eagerly here, so a deployment that declares a loop whose fn the closure
+    // does not export fails at establish rather than mid-run.
+    const loopFns = await loadWorkflowLoopFnsFromClosure({
+        packageDir: opts.env.closurePackageDir,
+    });
+    eagerlyResolveLoopFns([definition, ...bodiesMap.values(), ...childBodiesMap.values()], loopFns);
+    // Action handlers resolve from the pinned closure's `interchange.actions`
+    // module, on the same terms as loop fns. Resolve every action handler ref
+    // reachable from the definition eagerly here (recursing into loop bodies,
+    // where an action body is the common case), so a deployment that declares an
+    // action whose handler the closure does not export fails at establish rather
+    // than mid-run.
+    const actionResolver = await loadWorkflowActionHandlersFromClosure({
+        packageDir: opts.env.closurePackageDir,
+    });
+    eagerlyResolveActionHandlers([definition, ...bodiesMap.values(), ...childBodiesMap.values()], actionResolver);
+    // Suspendable-child resolver (onTrigger section bodies and loop bodies),
+    // selected ONCE per deployment: the bodies map is immutable and the per-run
+    // `onEvent` is injected later in `buildRuntimeEnv`. Resolve each body from the
+    // parent's in-memory closure (already re-verified above) via the raw executor
+    // binding. A deployment that carries bodies but whose host wired no executor is
+    // a misconfiguration -- fail loud at startup rather than silently falling back
+    // to a disk read (the exact behaviour this arm exists to avoid). A deployment
+    // with no suspendable body leaves the host undefined; its slot is never
+    // invoked.
     let suspendableChildHost;
     if (bodiesMap.size > 0) {
         const executor = opts.bindings.runSuspendableChild;
         if (executor === undefined) {
-            throw new Error("workflow-child: source-ref deployment carries onTrigger bodies but " +
-                "the host wired no runSuspendableChild executor; cannot resolve " +
-                "bodies in-memory");
+            throw new Error("workflow-child: source-ref deployment carries suspendable bodies " +
+                "(onTrigger sections or loop bodies) but the host wired no " +
+                "runSuspendableChild executor; cannot resolve bodies in-memory");
         }
         suspendableChildHost = createInMemorySpawnSuspendableChild({
             bodies: bodiesMap,
@@ -225,6 +279,9 @@ export async function runWorkflowChild(opts) {
     // a misconfiguration and fails loud at startup rather than falling back to a
     // disk read. A definition with no inline child keeps the injected binding (a
     // test seam); its childWorkflow slot is never invoked.
+    // `HostSpawnChild` (a call-arg `onEvent`) like the suspendable host: the
+    // resolver is deployment-scoped but each run injects its own event sink in
+    // `buildRuntimeEnv`. The two fallback arms ignore the sink.
     let spawnChild;
     if (childBodiesMap.size > 0) {
         const executor = opts.bindings.runChild;
@@ -238,13 +295,14 @@ export async function runWorkflowChild(opts) {
         });
     }
     else if (opts.bindings.spawnChild !== undefined) {
-        spawnChild = opts.bindings.spawnChild;
+        const injected = opts.bindings.spawnChild;
+        spawnChild = (input, _onEvent) => injected(input);
     }
     else {
         // No inline child and no injected binding: a workflow that nonetheless
         // reaches a childWorkflow spawn fails loud here rather than silently
         // completing against a child that never ran.
-        spawnChild = async ({ definitionRef }) => {
+        spawnChild = async ({ definitionRef }, _onEvent) => {
             throw new Error(`workflow-child: childWorkflow ${definitionRef} reached the runtime ` +
                 `but no child executor is wired`);
         };
@@ -303,7 +361,11 @@ export async function runWorkflowChild(opts) {
             authorize,
             directors,
             suspendableChildHost,
+            bodiesMap,
+            loopBodyPreRewrite,
             spawnChild,
+            loopFns,
+            actionResolver,
             clock,
             newId,
             drainController,
@@ -380,7 +442,14 @@ export async function runWorkflowChild(opts) {
             logger.error `workflow-child control channel crash: ${reason}`;
         },
     });
-    try {
+    // Resolve the mailbox watch registry the control loop routes `mailbox.notify`
+    // frames to. Production wires it on the bindings (the substrate factory builds
+    // one instance and shares it with the warm agent's supervisor-backed
+    // transport); a test may inject one directly through the opts, which wins.
+    // Both absent leaves inbound `mailbox.notify` frames logged and dropped -- a
+    // deploy with no wired mail surface.
+    const mailboxWatchRegistry = opts.mailboxWatchRegistry ?? opts.bindings.mailboxWatchRegistry;
+    const runControlLoop = async () => {
         for await (const payload of iter) {
             if (await handleControlPayload(payload, {
                 env: opts.env,
@@ -391,7 +460,11 @@ export async function runWorkflowChild(opts) {
                 authorize,
                 directors,
                 suspendableChildHost,
+                bodiesMap,
+                loopBodyPreRewrite,
                 spawnChild,
+                loopFns,
+                actionResolver,
                 clock,
                 newId,
                 eventSender,
@@ -409,14 +482,20 @@ export async function runWorkflowChild(opts) {
                 ...(opts.outboundMailBridge !== undefined
                     ? { outboundMailBridge: opts.outboundMailBridge }
                     : {}),
+                ...(opts.mailboxMutationBridge !== undefined
+                    ? { mailboxMutationBridge: opts.mailboxMutationBridge }
+                    : {}),
+                ...(mailboxWatchRegistry !== undefined
+                    ? { mailboxWatchRegistry }
+                    : {}),
             })) {
                 // shutdown received; the shutdown case already cancelled any
                 // pending substrate writes before returning true.
                 break;
             }
         }
-    }
-    finally {
+    };
+    const cleanupControlLoop = async () => {
         // Any exit path -- clean (iterator end), dirty (thrown error),
         // shutdown (already cancelled, repeat is a no-op on an empty map)
         // -- cancels every still-pending substrate write so the runtime
@@ -433,6 +512,13 @@ export async function runWorkflowChild(opts) {
         if (opts.outboundMailBridge !== undefined) {
             opts.outboundMailBridge.cancelAll("workflow-child control loop exited");
         }
+        // Same contract for mailbox mutations: a step agent's flag or
+        // `expunge` still awaiting the supervisor's `mailbox.mutate.response`
+        // when the control loop exits must surface a structured rejection
+        // rather than hang on a torn-down channel.
+        if (opts.mailboxMutationBridge !== undefined) {
+            opts.mailboxMutationBridge.cancelAll("workflow-child control loop exited");
+        }
         // Evict the warm-agent cache (design §3b) on every exit path:
         // graceful (shutdown frame -> iterator end), dirty (thrown error),
         // or the control channel closing. Eviction runs the wrapped
@@ -444,7 +530,12 @@ export async function runWorkflowChild(opts) {
         if (warmCache !== undefined) {
             await warmCache.evictAll("workflow-child control loop exited");
         }
-    }
+    };
+    // Run the control loop, then always run the cleanup above. A failing
+    // eviction (the wrapped agent close rejects when a plugin/LSP disposer
+    // fails) surfaces on a clean exit, but must not mask a control-loop
+    // error already unwinding -- so it is logged, not rethrown, in that case.
+    await runBodyThenCleanup(runControlLoop, cleanupControlLoop, (cause) => logger.error `workflow-child: warm-agent eviction failed while unwinding a control-loop error; surfacing the control-loop error, eviction failure: ${cause instanceof Error ? cause.message : String(cause)}`);
     return {
         resumedRunIds,
         triggeredRunIds,
@@ -478,23 +569,15 @@ async function handleControlPayload(payload, ctx) {
                 ctx.triggeredRunIds.push(payload.data.runId);
                 return false;
             }
-            // Resolve the inbound mail bytes for this messageId from the
-            // claim-check processing entry the supervisor created when it
-            // dequeued the message. The bytes become the run's trigger
-            // payload; the one-step workflow's first step defaults its input
-            // selector to `trigger.payload` (defineWorkflow's default-input
-            // convention), so the step input resolves to the inbound message
-            // and `agent.send` receives it. A missing or unreadable entry
-            // surfaces loudly -- the run cannot proceed without its input,
-            // and silently running the agent with empty input would mask a
-            // real mailbox-ownership failure.
-            const triggerPayload = await resolveTriggerPayload({
-                substrate: ctx.bindings.substrate,
-                principal: ctx.bindings.principal,
-                workflowRunRepoId: ctx.bindings.workflowRunRepoId,
-                mailboxAddress: ctx.env.mailboxAddress,
-                messageId: payload.data.messageId,
-            });
+            // The supervisor resolved the inbound mail to the run's input (the
+            // conversation text plus references to attachment bytes it committed to
+            // the workflow-run substrate) and shipped it in the frame. It becomes
+            // the run's trigger payload; the one-step workflow's first step defaults
+            // its input selector to `trigger.payload` (defineWorkflow's default-input
+            // convention), so the step input resolves to the inbound message and
+            // `agent.send` receives it once its attachment references are resolved to
+            // bytes at send time.
+            const triggerPayload = payload.data.payload;
             const env = buildRuntimeEnv({
                 runId: payload.data.runId,
                 bindings: ctx.bindings,
@@ -502,7 +585,11 @@ async function handleControlPayload(payload, ctx) {
                 authorize: ctx.authorize,
                 directors: ctx.directors,
                 suspendableChildHost: ctx.suspendableChildHost,
+                bodiesMap: ctx.bodiesMap,
+                loopBodyPreRewrite: ctx.loopBodyPreRewrite,
                 spawnChild: ctx.spawnChild,
+                loopFns: ctx.loopFns,
+                actionResolver: ctx.actionResolver,
                 clock: ctx.clock,
                 newId: ctx.newId,
                 drainController: ctx.drainController,
@@ -577,12 +664,16 @@ async function handleControlPayload(payload, ctx) {
             return false;
         }
         case "credentials-updated": {
-            // Replace the in-memory credential material wholesale. A revoked
-            // credential arrives by omission -- its material entry is absent from
-            // the delivery -- so the swap evicts it. Atomic whole-object assignment,
-            // so a concurrent reader never observes a torn cell. The secret stays on
-            // this ref only; nothing here copies it into a snapshot, event, or state.
-            ctx.credentialMaterialRef.current = payload.data.delivery;
+            // Merge the delivery into the live cell (see `mergeCredentialDelivery`):
+            // materials upsert by credentialId, bindings by (consumer, handle), and
+            // `revoke` drops named credentialIds plus any binding referencing them.
+            // Merge rather than wholesale-replace because the cell has several
+            // independently-scoped producers, so a swap would evict another
+            // producer's credentials. The result is assigned in one atomic
+            // whole-object swap, so a concurrent reader never observes a torn cell.
+            // The secret stays on this ref only; nothing here copies it into a
+            // snapshot, event, or state.
+            ctx.credentialMaterialRef.current = mergeCredentialDelivery(ctx.credentialMaterialRef.current, payload.data.delivery, payload.data.revoke);
             return false;
         }
         case "signal.deliver": {
@@ -755,6 +846,43 @@ async function handleControlPayload(payload, ctx) {
             ctx.outboundMailBridge.handleResult(payload.data);
             return false;
         }
+        case "mailbox.notify": {
+            // Route the supervisor's new-mail notification to the child's watch
+            // registry so a step agent's `watch`/`mail_wait` observes the arrival.
+            // A notify that lands without a registry means no watcher on the child
+            // side asked for inbound events; log and drop rather than throwing so
+            // the runtime keeps progressing (mirrors the `outbound.result` arm).
+            if (ctx.mailboxWatchRegistry === undefined) {
+                logger.warn `workflow-child mailbox.notify received without a watch registry wired; mailbox=${payload.data.mailbox} uid=${String(payload.data.uid)} dropped`;
+                return false;
+            }
+            ctx.mailboxWatchRegistry.fire(payload.data.mailbox, {
+                type: "exists",
+                uid: payload.data.uid,
+                headers: payload.data.headers,
+            });
+            return false;
+        }
+        case "mailbox.mutate.request": {
+            // `mailbox.mutate.request` is the child->supervisor mailbox-mutation
+            // request frame; receiving one on the child's downstream side is a
+            // protocol violation in the same shape as a downstream
+            // `outbound.message`.
+            throw new Error("workflow-child received a `mailbox.mutate.request` frame on its inbound control channel; this is a child-only upstream payload");
+        }
+        case "mailbox.mutate.response": {
+            // Route the supervisor's applied-mutation result to the
+            // mailbox-mutation bridge if one is wired. A response that lands
+            // without an active bridge means a stale supervisor frame for which
+            // no awaiter exists; log and drop rather than throwing so the
+            // runtime keeps progressing (mirrors the `outbound.result` arm).
+            if (ctx.mailboxMutationBridge === undefined) {
+                logger.warn `workflow-child mailbox.mutate.response received without a bridge wired; requestId=${payload.data.requestId} dropped`;
+                return false;
+            }
+            ctx.mailboxMutationBridge.handleResult(payload.data);
+            return false;
+        }
         case "substrate.merge.request": {
             // Route the request to the substrate-write bridge if one is
             // wired. A request that lands without an active bridge means a
@@ -823,6 +951,28 @@ async function handleControlPayload(payload, ctx) {
  * shape; the substrate handle and per-deployment `RepoStore` adapter
  * are shared across runs.
  */
+/**
+ * Force-resolve every `action` handler ref reachable from these definitions
+ * against the resolver, so a missing action handler surfaces at establish
+ * rather than when the action is first invoked mid-run. Recurses into loop
+ * bodies (an action body is the common loop shape). The caller passes the
+ * lifted onTrigger/childWorkflow bodies separately, as with loop fns.
+ */
+function eagerlyResolveActionHandlers(definitions, actionResolver) {
+    const visit = (def) => {
+        for (const step of Object.values(def.steps)) {
+            if (step.kind === "action") {
+                // Throws (fail closed) if the handler names no export, or a non-function.
+                actionResolver(step.handler);
+            }
+            else if (step.kind === "loop") {
+                visit(step.body);
+            }
+        }
+    };
+    for (const def of definitions)
+        visit(def);
+}
 function buildRuntimeEnv(args) {
     const signalChannel = createWorkflowHostSignalChannel({
         repoStore: args.bindings.substrate,
@@ -841,6 +991,17 @@ function buildRuntimeEnv(args) {
         runId: args.runId,
         ref: args.bindings.workflowRunRef,
     });
+    // Reader for inbound-mail parts, a sibling of `blobs` over the same
+    // workflow-run repo. The step invoker resolves a `Mail` part's `ref` to its
+    // bytes through it at `agent.send` time; the supervisor committed the bytes
+    // before the trigger. Deployment-scoped (the ref encodes the owning run), so
+    // one reader resolves any run's parts.
+    const mailPartReader = createMailPartReader({
+        substrate: args.bindings.substrate,
+        repoId: args.bindings.workflowRunRepoId,
+        principal: args.bindings.principal,
+        ref: args.bindings.workflowRunRef,
+    });
     // Wrap the step invoker so every `InferenceEvent` the harness emits
     // funnels through the per-run `onEvent` closure, which forwards
     // the event up the HMAC-authenticated event channel. The wrap is
@@ -849,19 +1010,27 @@ function buildRuntimeEnv(args) {
     // `ChildStepInvoker` shape (carries onEvent), so the workflow-
     // runtime never has to know an event firehose exists.
     const invokeStep = async (req) => {
-        return args.bindings.invokeStep(req, args.onEvent, args.authorize, args.warmCache, args.sourcesRef, args.credentialWiring);
+        return args.bindings.invokeStep(req, args.onEvent, args.authorize, args.warmCache, args.sourcesRef, args.credentialWiring, mailPartReader);
     };
     // Adapt the host binding (which takes the run's `onEvent` sink) down to the
     // runtime's narrow `SpawnSuspendableChild` by injecting THIS run's event
     // funnel -- the same closure `invokeStep` forwards -- so a body's live
     // inference events ride the parent run's event channel to the hub stream
     // (and inherit its loud-on-failure logging), while the runtime env keeps the
-    // narrow contract with no event slot.
+    // narrow contract with no event slot. The run's live credential-material cell
+    // rides the same seam so the body's inference resolves its source secret
+    // against the parent's current delivery, reached live on a rotation.
     const hostSuspendable = args.suspendableChildHost;
     const spawnSuspendableChild = hostSuspendable === undefined
         ? undefined
-        : (spawnInput) => hostSuspendable(spawnInput, args.onEvent);
-    return {
+        : (spawnInput) => hostSuspendable(spawnInput, args.onEvent, args.credentialWiring.materialRef);
+    // Same adaptation for the terminal childWorkflow seam: inject THIS run's event
+    // funnel so a child's live inference events ride the parent run's channel, and
+    // the live credential-material cell so the child's inference resolves its
+    // source secret against the parent's current delivery, while the runtime env
+    // keeps the narrow `SpawnChildWorkflow` (no event slot).
+    const spawnChild = (spawnInput) => args.spawnChild(spawnInput, args.onEvent, args.credentialWiring.materialRef);
+    const env = {
         repoStore: args.runtimeRepoStore,
         scheduler: args.bindings.scheduler,
         signalChannel,
@@ -869,7 +1038,15 @@ function buildRuntimeEnv(args) {
         directors: args.directors,
         authorize: args.authorize,
         invokeStep,
-        spawnChild: args.spawnChild,
+        spawnChild,
+        // The deployment's addressable run. Its parks are registered with the hub
+        // through the notify sink below, and a resolved decision is delivered back
+        // onto this run's own channel.
+        hasUpstreamSignalResolver: true,
+        // Resolve a loop's `while`/`carry` refs against the closure's loop module.
+        // Every ref was force-resolved at establish, so a lookup here cannot fail
+        // for a definition that passed startup.
+        loopFns: args.loopFns,
         // Wire the suspendable-child seam only when the host supplied it; a child
         // that never runs an onTrigger section omits the binding, and the runtime
         // body fails loud if a workflow reaches a section the env did not wire.
@@ -892,6 +1069,85 @@ function buildRuntimeEnv(args) {
             ? { readParkedApprovalOps: args.bindings.readParkedApprovalOps }
             : {}),
     };
+    // The suspendable-loop executor runs each iteration's body under THIS run's
+    // inherited env (its real tool-bearing invokeStep, invokeAction, credentials
+    // authorize, effect ledger, and durable shared repoStore/blobs), giving the
+    // body only its own substrate-backed signal channel -- the inherited-env
+    // iteration model plus park capability, distinct from an onTrigger body's
+    // fresh capped env. Resolved from the bodies map by ref (loop
+    // bodies were registered there at establish) and wrapped with this run's
+    // event funnel. Assigned AFTER env construction because it closes over `env`.
+    const loopIterationHost = createInMemorySpawnSuspendableChild({
+        bodies: args.bodiesMap,
+        runSuspendableChild: async (loopInput, _onEvent) => {
+            // Materialize this iteration's own grants file BEFORE the body runs (i.e.
+            // before `createLoopIterationHandle` drives the iteration's first event
+            // append), so a `childWorkflow` grandchild spawned from the body reads it
+            // as authority (the sidecar's runChild fails closed on a missing parent
+            // grants file). This ordering is LOAD-BEARING: the grants write is
+            // write-once and its shallow-prefix rebuild is safe only while the
+            // iteration run's subtree is still empty -- see `capAndPersistChildGrants`.
+            // The cap must walk the PRE-rewrite loop body (grandchild still inline);
+            // the rewritten body in `bodiesMap` would skip the grandchild's resources.
+            // Every loop body is registered in `loopBodyPreRewrite` at establish under
+            // the same ref the runtime dispatches, so a miss is a defect -- fail loud
+            // rather than silently skip, which would re-open the fail-closed
+            // grandchild spawn. The BINDING is a separate sidecar-only seam: `runLocal`
+            // keeps no per-run grants file (its grandchild spawn never fails closed),
+            // so it omits the binding, and an absent binding leaves the iteration's
+            // grants unmaterialized -- matching the in-process model with no disk
+            // authority.
+            const preRewriteBody = args.loopBodyPreRewrite.get(loopInput.definitionRef);
+            if (preRewriteBody === undefined) {
+                throw new Error(`workflow-child: loop iteration ${loopInput.childRunId} has no ` +
+                    `pre-rewrite body registered for ref ${loopInput.definitionRef}`);
+            }
+            await args.bindings.materializeLoopIterationGrants?.({
+                parentRunId: loopInput.parentRunId,
+                childRunId: loopInput.childRunId,
+                definition: preRewriteBody,
+            });
+            const childSignalChannel = createWorkflowHostSignalChannel({
+                repoStore: args.bindings.substrate,
+                principal: args.bindings.principal,
+                repoId: args.bindings.workflowRunRepoId,
+                ref: args.bindings.workflowRunRef,
+                runId: loopInput.childRunId,
+                readState: () => emptyState(loopInput.childRunId),
+                newId: () => args.newId("sig"),
+                clock: args.clock,
+            });
+            return createLoopIterationHandle(env, {
+                definition: loopInput.definition,
+                childRunId: loopInput.childRunId,
+                input: loopInput.input,
+                depth: loopInput.depth,
+                maxChildSpawnDepth: loopInput.maxChildSpawnDepth,
+                ...(loopInput.resumeFromEvents !== undefined
+                    ? { resumeFromEvents: loopInput.resumeFromEvents }
+                    : {}),
+                signal: loopInput.signal,
+                signalChannel: childSignalChannel,
+                cleanup: () => childSignalChannel.stop(),
+            });
+        },
+    });
+    env.spawnLoopIteration = (spawnInput) => loopIterationHost(spawnInput, args.onEvent);
+    // Action handlers run against a per-run effect ledger. The ledger is
+    // IN-MEMORY, and that is correct -- not a shortcut -- on the deployed store:
+    // appends are immediate-durable single-ref commits, `runAction` flushes
+    // StepStarted durably before the effect, and the runtime never re-invokes a
+    // crashed action (a mid-action crash settles the step failed; a loop-body
+    // action leaves a non-empty child log that fails the iteration loud rather
+    // than re-running). So the ledger is never consulted across a crash; its
+    // cross-crash exactly-once rests on that store-consistency invariant, which
+    // the store layer owns. A durable ledger here would re-enforce a constraint
+    // a lower layer already guarantees. Within a single invocation the ledger
+    // still dedups a handler that performs the same effect twice.
+    const effects = createInMemoryEffectLedger();
+    env.effects = effects;
+    env.invokeAction = createDefaultActionInvoker(args.authorize, effects, args.actionResolver);
+    return env;
 }
 /**
  * Forward a control-plane suspension to the supervisor over the upstream
@@ -1046,30 +1302,6 @@ function reclaimRunStorageIfCold(opts) {
         logger.warn `workflow-step-state cleanup failed for runId=${opts.runId}: ${message}`;
     });
 }
-/**
- * Resolve the run's trigger payload from the inbound mail message the
- * supervisor moved to the claim-check processing queue. Reads the
- * processing entry by messageId (a read-only snapshot of the
- * `refs/heads/events` tip that cannot race the supervisor's
- * `markConsumed` write), decodes the inlined raw MIME bytes, and
- * extracts the conversation text the agent's `agent.send` receives.
- *
- * Defensive: a missing processing entry, an entry with no inlined
- * bytes, or unparseable mail all throw. The run cannot proceed without
- * its input, and a placeholder would mask a mailbox-ownership failure.
- */
-async function resolveTriggerPayload(args) {
-    const entry = await readProcessingEntry(args.substrate, args.principal, args.workflowRunRepoId, args.mailboxAddress, args.messageId);
-    if (entry === null) {
-        throw new Error(`workflow-child trigger.fire: no claim-check processing entry for messageId ${args.messageId} at ${args.mailboxAddress}; the run has no input to deliver to the agent`);
-    }
-    const rawMessageBase64 = entry.envelope.rawMessage;
-    if (rawMessageBase64 === undefined) {
-        throw new Error(`workflow-child trigger.fire: processing entry for messageId ${args.messageId} carries no inlined rawMessage; the supervisor must inline the inbound mail bytes for the child to deliver them as the step input`);
-    }
-    const raw = base64Decode(rawMessageBase64);
-    return extractConversationText(raw, args.messageId);
-}
 function defaultClock() {
     return new Date();
 }

package/dist/child/substrate-write-bridge.d.ts

@@ -59,8 +59,9 @@ export interface CreateChildSubstrateWriteBridgeOpts {
 }
 /**
  * Construct the child-side substrate-write bridge. Pending writes
- * live in a map keyed by `requestId`; the bridge resolves the awaiter
- * when the supervisor's matching `substrate.write.response` lands.
+ * live in the shared pending-request core keyed by `requestId`; the
+ * bridge resolves the awaiter when the supervisor's matching
+ * `substrate.write.response` lands.
  *
  * The supervisor may emit zero or more `substrate.merge.request`
  * frames per pending write (the supervisor's merge callback may run