@intx/workflow-host 0.2.2 → 0.4.0

package/dist/adapters/substrate-mailbox-store.js

@@ -0,0 +1,404 @@
+// Workflow-run-substrate backing for the `@intx/mailbox` `MailboxStore`.
+//
+// The `MailboxStore` mutation surface is SYNCHRONOUS, but the workflow-run
+// substrate is an async git store. This backing follows the shape of an IMAP
+// client with a local cache: the async `createSubstrateMailboxStore` factory
+// loads the committed `mailbox/INBOX/` METADATA (`index.json`) into an
+// in-memory mirror on open, exposes the synchronous mutation surface over that
+// mirror, and persists the current state back to the substrate through
+// `flush`. Callers mutate synchronously (append / addFlags / removeFlags /
+// remove) and `await flush()` at a boundary.
+//
+// The per-message raw RFC 2822 bytes are NOT loaded on open and are NOT held
+// resident: `readRaw(uid)` reads a message's `<uid>.eml` blob on demand from
+// the committed-read snapshot the open pinned. The only raw this backing keeps
+// in memory is that of a message appended-but-not-yet-flushed; a successful
+// `flush` drops it. So the resident footprint of a long-lived warm mailbox is
+// bounded to metadata regardless of how much mail it has accumulated.
+//
+// On-disk layout, a top-level subtree of the workflow-run repo (one mailbox per
+// deployment repo):
+//
+//   mailbox/INBOX/index.json      committed metadata: uidValidity, the
+//                                 uid/modseq counters, one entry per live
+//                                 message (uid, modseq, flags, pre-parsed
+//                                 envelope), and the expunged-uid tombstones
+//                                 QRESYNC answers `vanished` from.
+//   mailbox/INBOX/<uid>.eml       the verbatim raw RFC 2822 bytes of each live
+//                                 message, so `fetchFull` verifies signatures
+//                                 byte-exactly. Write-once per uid.
+//
+// Reads resolve from the committed substrate (`openCommittedReads`), never the
+// lagging working tree, matching the sibling `mail-part-store` reader. Writes
+// go through `writeTreeDelta`: `index.json` changes on every mutation and is
+// always put; each `<uid>.eml` is immutable, so a flush puts only the blobs
+// appended since the last successful flush and deletes only those whose
+// message was removed since then, and the substrate carries every untouched
+// `.eml` forward by object id. This keeps a flush O(delta) rather than
+// O(mailbox), so a long-lived warm conversational mailbox does not re-hash its
+// whole history on each append or flag change. The committed subtree the delta
+// leaves behind is byte-identical in shape to a full rewrite of the same live
+// set. The kind handler's push-time validation of this subtree is owned
+// separately by the hub replication layer; this module owns the on-disk shape
+// it validates.
+import { type } from "arktype";
+/** Top-level subtree of the workflow-run repo that holds the mailbox. */
+export const MAILBOX_PREFIX = "mailbox";
+/** The single mailbox this backing persists, an IMAP INBOX. */
+export const MAILBOX_INBOX_DIR = "INBOX";
+/** Committed metadata blob name directly under `mailbox/INBOX/`. */
+export const MAILBOX_INDEX_FILE = "index.json";
+/** Suffix of a per-message raw-bytes blob (`<uid>.eml`). */
+export const MAILBOX_EML_SUFFIX = ".eml";
+/**
+ * The `mailbox/INBOX/` prefix, ending in `/` as
+ * `writeTreePreservingPrefix` requires. Every blob this backing writes is a
+ * direct child of it.
+ */
+export const MAILBOX_INBOX_PREFIX = `${MAILBOX_PREFIX}/${MAILBOX_INBOX_DIR}/`;
+/** Relative directory path of the INBOX, for `CommittedReads.listDir`. */
+const MAILBOX_INBOX_DIR_PATH = `${MAILBOX_PREFIX}/${MAILBOX_INBOX_DIR}`;
+/** Current on-disk schema version of `index.json`. */
+const INDEX_VERSION = 1;
+const decoder = new TextDecoder();
+const encoder = new TextEncoder();
+/**
+ * On-disk envelope shape. Mirrors `StoredEnvelope` but serializes `date` as an
+ * ISO string and the three nullable header fields as `string | null` (JSON has
+ * no `undefined`); the loader maps `null` back to `undefined`.
+ */
+const StoredEnvelopeJson = type({
+    messageId: "string",
+    from: "string",
+    to: "string[]",
+    subject: "string",
+    date: "string",
+    inReplyTo: "string | null",
+    references: "string[]",
+    interchangeType: "string | null",
+    interchangeCorrelationId: "string | null",
+});
+/**
+ * On-disk `index.json` shape. Validated on every open: the committed tree is
+ * durable but external to this process, so it is parsed at the boundary rather
+ * than trusted. `expunged` records the uid and the modseq at which each
+ * message vanished so a QRESYNC `sync` can answer `vanished` since a client's
+ * known modseq.
+ */
+const MailboxIndexJson = type({
+    version: `${INDEX_VERSION}`,
+    uidValidity: "number >= 0",
+    uidNext: "number >= 1",
+    highestModSeq: "number >= 0",
+    messages: type({
+        uid: "number >= 1",
+        modseq: "number >= 1",
+        flags: "string[]",
+        envelope: StoredEnvelopeJson,
+    }).array(),
+    expunged: type({
+        uid: "number >= 1",
+        modseq: "number >= 1",
+    }).array(),
+});
+function serializeEnvelope(envelope) {
+    return {
+        messageId: envelope.messageId,
+        from: envelope.from,
+        to: envelope.to,
+        subject: envelope.subject,
+        date: envelope.date.toISOString(),
+        inReplyTo: envelope.inReplyTo ?? null,
+        references: envelope.references,
+        interchangeType: envelope.interchangeType ?? null,
+        interchangeCorrelationId: envelope.interchangeCorrelationId ?? null,
+    };
+}
+function deserializeEnvelope(raw) {
+    return {
+        messageId: raw.messageId,
+        from: raw.from,
+        to: raw.to,
+        subject: raw.subject,
+        date: new Date(raw.date),
+        inReplyTo: raw.inReplyTo === null ? undefined : raw.inReplyTo,
+        references: raw.references,
+        interchangeType: raw.interchangeType === null ? undefined : raw.interchangeType,
+        interchangeCorrelationId: raw.interchangeCorrelationId === null
+            ? undefined
+            : raw.interchangeCorrelationId,
+    };
+}
+/** The `<uid>.eml` blob name for a message. */
+function emlName(uid) {
+    return `${String(uid)}${MAILBOX_EML_SUFFIX}`;
+}
+/**
+ * Load the committed `mailbox/INBOX/` METADATA into an in-memory state, or the
+ * empty state (a fresh `uidValidity`) when the repo, the ref, or the subtree
+ * does not yet exist. Only `index.json` is read; the per-message `<uid>.eml`
+ * blobs stay on disk and are read lazily by `readRaw`, so an open's resident
+ * footprint is bounded to metadata regardless of mailbox size. The committed
+ * read snapshot and the uid->oid map are retained so `readRaw` resolves a
+ * blob against the same pinned commit the open observed. Every read resolves
+ * against the committed object store, so an open observes committed state even
+ * when the working tree lags.
+ */
+async function loadCommittedState(opts) {
+    const empty = (reads) => ({
+        uidValidity: Date.now(),
+        uidNext: 1,
+        highestModSeq: 0,
+        messages: [],
+        expunged: [],
+        reads,
+        oidByUid: new Map(),
+    });
+    const reads = await opts.substrate.openCommittedReads(opts.principal, opts.repoId, opts.ref);
+    if (reads === null)
+        return empty(reads);
+    const entries = await reads.listDir(MAILBOX_INBOX_DIR_PATH);
+    const indexEntry = entries.find((e) => e.name === MAILBOX_INDEX_FILE && e.type === "blob");
+    if (indexEntry === undefined)
+        return empty(reads);
+    const indexBytes = await reads.readBlobByOid(indexEntry.oid);
+    let parsedJson;
+    try {
+        parsedJson = JSON.parse(decoder.decode(indexBytes));
+    }
+    catch (cause) {
+        throw new Error(`substrate mailbox store: ${MAILBOX_INBOX_PREFIX}${MAILBOX_INDEX_FILE} is not valid JSON`, { cause });
+    }
+    const index = MailboxIndexJson(parsedJson);
+    if (index instanceof type.errors) {
+        throw new Error(`substrate mailbox store: invalid ${MAILBOX_INBOX_PREFIX}${MAILBOX_INDEX_FILE}: ${index.summary}`);
+    }
+    const emlByName = new Map(entries
+        .filter((e) => e.type === "blob" && e.name.endsWith(MAILBOX_EML_SUFFIX))
+        .map((e) => [e.name, e.oid]));
+    const messages = [];
+    const oidByUid = new Map();
+    for (const entry of index.messages) {
+        const oid = emlByName.get(emlName(entry.uid));
+        if (oid === undefined) {
+            throw new Error(`substrate mailbox store: index references message uid ${String(entry.uid)} but ${MAILBOX_INBOX_PREFIX}${emlName(entry.uid)} is absent`);
+        }
+        // The blob's presence is asserted by its object id; its bytes are not read
+        // here -- `readRaw` reads them on demand.
+        oidByUid.set(entry.uid, oid);
+        messages.push({
+            uid: entry.uid,
+            modseq: entry.modseq,
+            flags: new Set(entry.flags),
+            envelope: deserializeEnvelope(entry.envelope),
+        });
+    }
+    return {
+        uidValidity: index.uidValidity,
+        uidNext: index.uidNext,
+        highestModSeq: index.highestModSeq,
+        messages,
+        expunged: index.expunged.map((e) => ({ uid: e.uid, modseq: e.modseq })),
+        reads,
+        oidByUid,
+    };
+}
+/**
+ * Create a workflow-run-substrate-backed `MailboxStore`. Loads the committed
+ * `mailbox/INBOX/` subtree into an in-memory mirror, then serves the
+ * synchronous `MailboxStore` surface over that mirror. Mutations stay in
+ * memory until `flush` persists them.
+ */
+export async function createSubstrateMailboxStore(opts) {
+    const state = await loadCommittedState(opts);
+    const messages = state.messages;
+    const expunged = state.expunged;
+    const uidValidity = state.uidValidity;
+    const reads = state.reads;
+    const oidByUid = state.oidByUid;
+    let uidCounter = state.uidNext;
+    // The next modseq to assign. `highestModSeq` is the largest assigned, so the
+    // next is one past it; a fresh mailbox (highestModSeq 0) starts at 1.
+    let modseqCounter = state.highestModSeq + 1;
+    let dirty = false;
+    // Delta tracking for `flush`. `index.json` changes on every mutation, so it
+    // is put unconditionally; each `<uid>.eml` is immutable and written once, so
+    // a flush need only put the blobs appended since the last successful flush
+    // and delete the blobs whose message was removed since then. The removed set
+    // clears on a successful flush; a flush that throws leaves it intact so the
+    // next flush re-attempts the same delta.
+    //
+    // `pendingRawByUid` holds the raw bytes of appended-but-not-yet-flushed
+    // messages -- the only raw this backing keeps resident. It doubles as the
+    // "appended since flush" set: `flush` puts each entry's blob, then drops it
+    // so a flushed message's bytes leave memory and are read from disk on demand.
+    const pendingRawByUid = new Map();
+    const removedSinceFlush = new Set();
+    function find(uid) {
+        return messages.find((m) => m.uid === uid);
+    }
+    function require(uid) {
+        const msg = find(uid);
+        if (msg === undefined) {
+            throw new Error(`Message UID ${String(uid)} not found`);
+        }
+        return msg;
+    }
+    async function flush() {
+        if (!dirty)
+            return;
+        const index = {
+            version: INDEX_VERSION,
+            uidValidity,
+            uidNext: uidCounter,
+            highestModSeq: modseqCounter - 1,
+            messages: messages.map((m) => ({
+                uid: m.uid,
+                modseq: m.modseq,
+                flags: Array.from(m.flags),
+                envelope: serializeEnvelope(m.envelope),
+            })),
+            expunged: expunged.map((e) => ({ uid: e.uid, modseq: e.modseq })),
+        };
+        // `index.json` is put on every flush. Each `<uid>.eml` is immutable, so
+        // only the blobs appended since the last successful flush are put and only
+        // those whose message was removed are deleted; every other `.eml` is
+        // carried forward by object id, so the flush never re-hashes the mailbox's
+        // whole history.
+        const puts = {
+            [`${MAILBOX_INBOX_PREFIX}${MAILBOX_INDEX_FILE}`]: encoder.encode(JSON.stringify(index)),
+        };
+        const flushedUids = [];
+        for (const [uid, raw] of pendingRawByUid) {
+            puts[`${MAILBOX_INBOX_PREFIX}${emlName(uid)}`] = raw;
+            flushedUids.push(uid);
+        }
+        const deletes = Array.from(removedSinceFlush, (uid) => `${MAILBOX_INBOX_PREFIX}${emlName(uid)}`);
+        await opts.substrate.writeTreeDelta(opts.principal, opts.repoId, opts.ref, {
+            computeDelta: async () => ({ puts, deletes }),
+            changedPathPrefixes: new Set([MAILBOX_INBOX_PREFIX]),
+            message: `persist mailbox INBOX (${String(messages.length)} message(s))`,
+        });
+        // The appended blobs are now committed, so their raw leaves memory: a later
+        // `readRaw` reads them from disk. Their object ids are not recorded here
+        // (the pinned committed-read snapshot predates this commit), so `readRaw`
+        // resolves a post-open append only while its raw is still pending; the
+        // long-lived writer never reads its own appends back, and every reader
+        // opens a fresh snapshot that sees the committed blob.
+        for (const uid of flushedUids) {
+            pendingRawByUid.delete(uid);
+        }
+        removedSinceFlush.clear();
+        dirty = false;
+    }
+    function sync(known) {
+        const highestModSeq = modseqCounter - 1;
+        if (known.uidValidity !== uidValidity) {
+            return {
+                resync: true,
+                uidValidity,
+                uidNext: uidCounter,
+                highestModSeq,
+                messages: messages.slice(),
+            };
+        }
+        const changed = messages
+            .filter((m) => m.modseq > known.highestModSeq)
+            .sort((a, b) => a.uid - b.uid);
+        const vanished = expunged
+            .filter((e) => e.modseq > known.highestModSeq)
+            .map((e) => e.uid)
+            .sort((a, b) => a - b);
+        return {
+            resync: false,
+            uidValidity,
+            uidNext: uidCounter,
+            highestModSeq,
+            changed,
+            vanished,
+        };
+    }
+    return {
+        uidValidity,
+        get uidNext() {
+            return uidCounter;
+        },
+        get highestModSeq() {
+            return modseqCounter - 1;
+        },
+        get messages() {
+            return messages;
+        },
+        get pendingWrites() {
+            return dirty;
+        },
+        append(raw, envelope, flags) {
+            const uid = uidCounter++;
+            const modseq = modseqCounter++;
+            messages.push({ uid, modseq, flags: new Set(flags), envelope });
+            pendingRawByUid.set(uid, raw);
+            dirty = true;
+            return uid;
+        },
+        async readRaw(uid) {
+            if (find(uid) === undefined) {
+                throw new Error(`Message UID ${String(uid)} not found`);
+            }
+            // An appended-but-not-yet-flushed message keeps its raw in memory; a
+            // flushed or previously-committed message reads its blob from the pinned
+            // committed-read snapshot on demand.
+            const pending = pendingRawByUid.get(uid);
+            if (pending !== undefined)
+                return pending;
+            const oid = oidByUid.get(uid);
+            if (oid === undefined || reads === null) {
+                throw new Error(`substrate mailbox store: no committed blob for message uid ${String(uid)}; its raw bytes are not resolvable from this snapshot`);
+            }
+            return reads.readBlobByOid(oid);
+        },
+        find,
+        addFlags(uid, flags) {
+            const msg = require(uid);
+            for (const flag of flags) {
+                msg.flags.add(flag);
+            }
+            msg.modseq = modseqCounter++;
+            dirty = true;
+            return msg;
+        },
+        removeFlags(uid, flags) {
+            const msg = require(uid);
+            for (const flag of flags) {
+                msg.flags.delete(flag);
+            }
+            msg.modseq = modseqCounter++;
+            dirty = true;
+            return msg;
+        },
+        remove(uid) {
+            const idx = messages.findIndex((m) => m.uid === uid);
+            if (idx === -1) {
+                throw new Error(`Message UID ${String(uid)} not found`);
+            }
+            messages.splice(idx, 1);
+            // Record the expunge with a fresh modseq so a QRESYNC `sync` can report
+            // this uid as `vanished` to a client whose known modseq predates it. The
+            // in-memory reference backing does not advance modseq on remove; this
+            // backing does, because it must answer QRESYNC across reopens.
+            expunged.push({ uid, modseq: modseqCounter++ });
+            // A message appended and removed within the same flush window was never
+            // committed, so its `.eml` must be neither put nor deleted: drop its
+            // pending raw. Otherwise the blob is already committed and the next flush
+            // deletes it.
+            if (pendingRawByUid.has(uid)) {
+                pendingRawByUid.delete(uid);
+            }
+            else {
+                removedSinceFlush.add(uid);
+            }
+            dirty = true;
+        },
+        flush,
+        sync,
+    };
+}

package/dist/child/child-mailbox-reader.d.ts

@@ -0,0 +1,10 @@
+import { type SubstrateMailboxStore, type SubstrateMailboxStoreOpts } from "../adapters/substrate-mailbox-store.js";
+export interface ChildMailboxReader {
+    /**
+     * Open a fresh committed snapshot of the deployment's substrate INBOX. Each
+     * call re-reads the committed `mailbox/INBOX/` subtree, so a snapshot opened
+     * after a `mailbox.notify` observes the newly committed message.
+     */
+    open(): Promise<SubstrateMailboxStore>;
+}
+export declare function createChildMailboxReader(opts: SubstrateMailboxStoreOpts): ChildMailboxReader;

package/dist/child/child-mailbox-reader.js

@@ -0,0 +1,23 @@
+// Child-side substrate mailbox reader (INBOUND half of mailbox ownership,
+// design §3b).
+//
+// The supervisor commits an arrived message to the deployment's workflow-run
+// substrate mailbox (`mailbox/INBOX/`), then fires a `mailbox.notify` control
+// frame. A step agent's supervisor-backed transport answers the IMAP read
+// surface (`search`, `fetchHeaders`, `fetchFull`, ...) by opening a fresh
+// committed snapshot of that mailbox through this reader. `open` re-reads the
+// committed subtree on every call, so a snapshot taken after a `mailbox.notify`
+// observes the message the supervisor just committed.
+//
+// Modeled on the sibling `createMailPartReader` wiring: the same per-deployment
+// substrate handles (substrate, repoId, principal, workflow-run ref), bound
+// once so the transport reads without re-threading them. `createSubstrateMailboxStore`
+// loads committed state on open and is async, so `open` returns a promise.
+import { createSubstrateMailboxStore, } from "../adapters/substrate-mailbox-store.js";
+export function createChildMailboxReader(opts) {
+    return {
+        open() {
+            return createSubstrateMailboxStore(opts);
+        },
+    };
+}

package/dist/child/credential-cell.d.ts

@@ -0,0 +1,8 @@
+import type { CredentialDelivery } from "@intx/types/sidecar";
+/**
+ * Apply a `credentials-updated` frame to the current cell and return the next
+ * cell. Pure: it reads neither argument's identity back out, so the caller can
+ * assign the result to the live ref in one atomic whole-object swap and a
+ * concurrent reader never observes a torn cell.
+ */
+export declare function mergeCredentialDelivery(current: CredentialDelivery | null, delivery: CredentialDelivery, revoke: readonly string[] | undefined): CredentialDelivery;

package/dist/child/credential-cell.js

@@ -0,0 +1,66 @@
+// Merge semantics for the child's in-memory credential-material cell.
+//
+// The cell is fed by several INDEPENDENTLY-SCOPED producers: the deploy frame
+// (tool bindings plus the run's inference materials, frozen at deploy time and
+// re-asserted on every spawn and pre-trigger barrier), an inference rotation
+// (materials only, no binding), and a tool-grant push (tool bindings plus their
+// materials). Each producer carries only its own slice of the cell. A wholesale
+// swap would therefore let one producer evict another's credentials -- an
+// inference rotation would drop every tool binding, a barrier re-push would drop
+// a live-pushed tool credential. So a `credentials-updated` frame MERGES:
+// materials upsert by `credentialId`, bindings upsert by `(consumer, handle)`.
+//
+// Because omission no longer means "gone", revocation is EXPLICIT: a frame's
+// `revoke` list names the credentialIds to drop, and dropping one also drops
+// every binding that references it. Revocation is applied before the upsert, so
+// a frame that both revokes and re-adds the same credentialId resolves to the
+// re-add. A material an upsert leaves unreferenced (a rebind of a handle to a
+// different credential) is not garbage-collected -- inference materials never
+// carry a binding, so "unreferenced" is not a drop signal; only an explicit
+// `revoke` removes a material.
+// A binding's identity is the (consumer, handle) pair: a handle string is only
+// unique within a consumer, so two consumers can each bind their own handle of
+// the same name. The U+0000 joiner keeps the pair injective where a printable
+// joiner would not -- a handle is an arbitrary string that may contain a space
+// or a colon, but by convention never a NUL.
+function bindingKey(binding) {
+    return `${binding.consumer}\u0000${binding.handle}`;
+}
+/**
+ * Apply a `credentials-updated` frame to the current cell and return the next
+ * cell. Pure: it reads neither argument's identity back out, so the caller can
+ * assign the result to the live ref in one atomic whole-object swap and a
+ * concurrent reader never observes a torn cell.
+ */
+export function mergeCredentialDelivery(current, delivery, revoke) {
+    const materials = new Map();
+    const bindings = new Map();
+    if (current !== null) {
+        for (const material of current.materials) {
+            materials.set(material.credentialId, material);
+        }
+        for (const binding of current.bindings) {
+            bindings.set(bindingKey(binding), binding);
+        }
+    }
+    if (revoke !== undefined) {
+        for (const credentialId of revoke) {
+            materials.delete(credentialId);
+            for (const [key, binding] of bindings) {
+                if (binding.credentialId === credentialId) {
+                    bindings.delete(key);
+                }
+            }
+        }
+    }
+    for (const material of delivery.materials) {
+        materials.set(material.credentialId, material);
+    }
+    for (const binding of delivery.bindings) {
+        bindings.set(bindingKey(binding), binding);
+    }
+    return {
+        bindings: [...bindings.values()],
+        materials: [...materials.values()],
+    };
+}

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/from-process-env.d.ts

@@ -2,6 +2,7 @@ import { type SpawnTimeEnv } from "./env-bootstrap.js";
 import { type RunWorkflowChildBindings, type RunWorkflowChildResult } from "./run-child.js";
 import { type ChildSubstrateWriteBridge } from "./substrate-write-bridge.js";
 import { type ChildOutboundMailBridge } from "./outbound-mail-bridge.js";
+import { type ChildMailboxMutationBridge } from "./mailbox-mutation-bridge.js";
 import { type FrameWriter, type NdjsonReader, type NdjsonWriter } from "../ipc/index.js";
 /**
  * File descriptor the supervisor's `Bun.spawn` wires the
@@ -63,6 +64,17 @@ export interface SubstrateFactoryEnv {
      * agent's signature without the child ever holding the agent's key.
      */
     readonly outboundMailBridge: ChildOutboundMailBridge;
+    /**
+     * Child-side IPC bridge over the upstream control channel for the
+     * INBOUND half of mailbox ownership (§3b). The substrate factory uses
+     * this to construct the supervisor-backed `MessageTransport`'s write
+     * surface: `setFlags` / `clearFlags` / `expunge` call `bridge.submit`,
+     * which emits a `mailbox.mutate.request` upstream frame and resolves
+     * once the supervisor's matching `mailbox.mutate.response` lands. The
+     * supervisor -- the sole mailbox writer -- applies the mutation to its
+     * owned store, so the child never flushes the run ref itself.
+     */
+    readonly mailboxMutationBridge: ChildMailboxMutationBridge;
 }
 /**
  * Substrate-factory callback the host supplies to

package/dist/child/from-process-env.js

@@ -21,6 +21,7 @@ import { parseSpawnTimeEnv } from "./env-bootstrap.js";
 import { runWorkflowChild, } from "./run-child.js";
 import { createChildSubstrateWriteBridge, } from "./substrate-write-bridge.js";
 import { createChildOutboundMailBridge, } from "./outbound-mail-bridge.js";
+import { createChildMailboxMutationBridge, } from "./mailbox-mutation-bridge.js";
 import { createControlChannelSender, } from "../ipc/index.js";
 /**
  * File descriptor the supervisor's `Bun.spawn` wires the
@@ -76,11 +77,15 @@ export async function runWorkflowChildFromProcessEnv(factory, opts = {}) {
     const outboundMailBridge = createChildOutboundMailBridge({
         upstreamSender,
     });
+    const mailboxMutationBridge = createChildMailboxMutationBridge({
+        upstreamSender,
+    });
     const bindings = await factory({
         spawn,
         substrateConfig,
         substrateWriteBridge,
         outboundMailBridge,
+        mailboxMutationBridge,
     });
     return runWorkflowChild({
         env: spawn,
@@ -98,6 +103,7 @@ export async function runWorkflowChildFromProcessEnv(factory, opts = {}) {
         upstreamSender,
         substrateWriteBridge,
         outboundMailBridge,
+        mailboxMutationBridge,
     });
 }
 const SubstrateConfigValue = type("string > 0");

package/dist/child/index.d.ts

@@ -1,9 +1,13 @@
-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 { createChildMailboxMutationBridge, type ChildMailboxMutationBridge, type CreateChildMailboxMutationBridgeOpts, type MailboxMutation, type MailboxMutationResult, } from "./mailbox-mutation-bridge.js";
+export { createSupervisorBackedTransport, type SupervisorBackedTransportInbound, } from "./supervisor-backed-transport.js";
+export { createMailboxWatchRegistry, type MailboxWatchRegistry, } from "./mailbox-watch-registry.js";
+export { createChildMailboxReader, type ChildMailboxReader, } from "./child-mailbox-reader.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";