@intx/workflow-host 0.2.2 → 0.4.0

package/dist/child/index.js

@@ -1,7 +1,10 @@
 export { createCredentialsBackedAuthorize, hashGrants, runWorkflowChild, } from "./run-child.js";
 export { createChildSubstrateWriteBridge, } from "./substrate-write-bridge.js";
 export { createChildOutboundMailBridge, } from "./outbound-mail-bridge.js";
-export { createSupervisorBackedTransport } from "./supervisor-backed-transport.js";
+export { createChildMailboxMutationBridge, } from "./mailbox-mutation-bridge.js";
+export { createSupervisorBackedTransport, } from "./supervisor-backed-transport.js";
+export { createMailboxWatchRegistry, } from "./mailbox-watch-registry.js";
+export { createChildMailboxReader, } from "./child-mailbox-reader.js";
 export { createProxyWorkflowRunRepoStore, } from "./proxy-repo-store.js";
 export { parseSpawnTimeEnv } from "./env-bootstrap.js";
 export { discoverInFlightRuns, } from "./self-discovery.js";

package/dist/child/mailbox-mutation-bridge.d.ts

@@ -0,0 +1,61 @@
+import type { ControlChannelSender, ControlPayload } from "../ipc/control-channel.js";
+/**
+ * A mailbox mutation the child asks the supervisor to apply. A flag
+ * mutation carries the target `uid` and the `flags` to add or remove; an
+ * `expunge` sweeps every `\Deleted` message in the mailbox and so carries
+ * neither.
+ */
+export type MailboxMutation = {
+    runId: string;
+    mailbox: string;
+    op: "addFlags" | "removeFlags";
+    uid: number;
+    flags: string[];
+} | {
+    runId: string;
+    mailbox: string;
+    op: "expunge";
+};
+/**
+ * The supervisor's applied-mutation result. `expungedUids` is present
+ * only for an `expunge` and lists the uids the sweep removed, so the
+ * agent tool can report how many messages it consumed.
+ */
+export type MailboxMutationResult = {
+    expungedUids?: number[];
+};
+/**
+ * Bridge surface the child's supervisor-backed transport reaches into.
+ * `submit` sends a `mailbox.mutate.request` upstream and resolves once
+ * the supervisor's matching `mailbox.mutate.response` lands.
+ * `handleResult` is the receiver-side entry point the child's control
+ * loop invokes when the downstream `mailbox.mutate.response` frame
+ * arrives. `cancelAll` is the cleanup hook the control loop invokes on
+ * any exit path so a pending mutation does not leak an awaiter when the
+ * supervisor has torn the IPC down.
+ */
+export interface ChildMailboxMutationBridge {
+    submit(mutation: MailboxMutation): Promise<MailboxMutationResult>;
+    handleResult(data: Extract<ControlPayload, {
+        type: "mailbox.mutate.response";
+    }>["data"]): void;
+    cancelAll(reason: string): void;
+    readonly pendingCount: number;
+}
+export interface CreateChildMailboxMutationBridgeOpts {
+    upstreamSender: ControlChannelSender;
+    /**
+     * Optional `requestId` allocator. Production wires a per-instance
+     * monotonic counter plus a random suffix; tests inject a
+     * deterministic factory so the upstream frame's `requestId` is
+     * predictable.
+     */
+    allocateRequestId?: () => string;
+}
+/**
+ * Construct the child-side mailbox-mutation bridge. Pending mutations
+ * live in the shared pending-request core keyed by `requestId`; the
+ * bridge resolves the awaiter when the supervisor's matching
+ * `mailbox.mutate.response` lands.
+ */
+export declare function createChildMailboxMutationBridge(opts: CreateChildMailboxMutationBridgeOpts): ChildMailboxMutationBridge;

package/dist/child/mailbox-mutation-bridge.js

@@ -0,0 +1,101 @@
+// Child-side mailbox-mutation bridge (INBOUND half of mailbox ownership,
+// §3b).
+//
+// The supervisor is the sole mail owner: it holds the long-lived
+// substrate mailbox store and is the only writer to the workflow-run
+// ref. A step agent reads its INBOX locally (the supervisor-backed
+// transport's read surface opens fresh committed snapshots), but every
+// MUTATION of the mailbox -- flag writes (`\Seen`, `\Deleted`, ...) and
+// `expunge` -- routes up to the supervisor through this bridge rather
+// than being flushed from the child. A second writer flushing the same
+// ref from the child would race the supervisor's in-memory mirror and
+// break uid / modseq monotonicity, so the child never writes the
+// mailbox directly.
+//
+// Lifecycle of one mutation:
+//
+//   1. The agent's mail tool (flag or expunge) calls the
+//      supervisor-backed transport's `setFlags` / `clearFlags` /
+//      `expunge`. The transport calls `bridge.submit(mutation)`.
+//   2. `submit` mints a `requestId`, registers a pending awaiter, and
+//      emits `mailbox.mutate.request` upstream carrying the op and its
+//      operands.
+//   3. The supervisor applies the op to its owned mailbox store,
+//      flushes, and replies with `mailbox.mutate.response`. The reply is
+//      sent only after the flush, so the child's next committed read
+//      observes the mutation (the same flush-before-signal ordering
+//      `mailbox.notify` relies on).
+//   4. The bridge resolves / rejects the pending awaiter; the
+//      transport method returns to the mail tool. A supervisor-side
+//      failure (unknown uid, substrate fault) surfaces as a rejection so
+//      the agent's mail-tool call fails loudly rather than silently
+//      dropping the mutation.
+import { getLogger } from "@intx/log";
+import { createPendingRequestCore } from "./pending-request.js";
+const logger = getLogger(["workflow-host", "child", "mailbox-mutation-bridge"]);
+/**
+ * Construct the child-side mailbox-mutation bridge. Pending mutations
+ * live in the shared pending-request core keyed by `requestId`; the
+ * bridge resolves the awaiter when the supervisor's matching
+ * `mailbox.mutate.response` lands.
+ */
+export function createChildMailboxMutationBridge(opts) {
+    const pending = createPendingRequestCore({
+        label: "workflow-child mailbox mutation",
+        allocatorPrefix: "mm",
+        allocateRequestId: opts.allocateRequestId,
+    });
+    return {
+        get pendingCount() {
+            return pending.pendingCount;
+        },
+        async submit(mutation) {
+            const { requestId, promise } = pending.register(undefined);
+            const data = mutation.op === "expunge"
+                ? {
+                    requestId,
+                    runId: mutation.runId,
+                    mailbox: mutation.mailbox,
+                    op: mutation.op,
+                }
+                : {
+                    requestId,
+                    runId: mutation.runId,
+                    mailbox: mutation.mailbox,
+                    op: mutation.op,
+                    uid: mutation.uid,
+                    flags: mutation.flags,
+                };
+            try {
+                await opts.upstreamSender.send({
+                    type: "mailbox.mutate.request",
+                    data,
+                });
+            }
+            catch (cause) {
+                pending.discard(requestId);
+                throw pending.sendFailedError(requestId, cause);
+            }
+            return promise;
+        },
+        handleResult(data) {
+            const entry = pending.settle(data.requestId);
+            if (entry === undefined) {
+                logger.warn `mailbox.mutate.response landed with no pending entry; requestId=${data.requestId} dropped`;
+                return;
+            }
+            if (data.result.ok) {
+                const result = {};
+                if (data.result.expungedUids !== undefined) {
+                    result.expungedUids = data.result.expungedUids;
+                }
+                entry.resolve(result);
+                return;
+            }
+            entry.reject(pending.rejectedError(data.requestId, data.result.reason));
+        },
+        cancelAll(reason) {
+            pending.cancelAll(reason);
+        },
+    };
+}

package/dist/child/mailbox-watch-registry.d.ts

@@ -0,0 +1,17 @@
+import type { MailboxEvent, Unsubscribe } from "@intx/types/runtime";
+export interface MailboxWatchRegistry {
+    /**
+     * Register a callback for a mailbox. Returns an `Unsubscribe` that removes
+     * it; after unsubscribe the callback observes no further events, including
+     * one whose `fire` preceded the unsubscribe but whose asynchronous delivery
+     * had not yet run.
+     */
+    watch(mailbox: string, callback: (event: MailboxEvent) => void): Unsubscribe;
+    /**
+     * Deliver a `MailboxEvent` to every callback currently registered for the
+     * mailbox, each on its own microtask. A no-op when no callback is registered
+     * for the mailbox.
+     */
+    fire(mailbox: string, event: MailboxEvent): void;
+}
+export declare function createMailboxWatchRegistry(): MailboxWatchRegistry;

package/dist/child/mailbox-watch-registry.js

@@ -0,0 +1,61 @@
+// Child-side mailbox watch registry (INBOUND half of mailbox ownership,
+// design §3b).
+//
+// The supervisor is the sole mail owner: it commits an arrived message to the
+// workflow-run substrate mailbox and fires a `mailbox.notify` control frame.
+// The child's control loop routes that frame to this registry's `fire`, which
+// delivers a typed `exists` `MailboxEvent` to every callback registered for the
+// mailbox through `watch`. The step agent's supervisor-backed transport
+// implements `MessageTransport.watch` over this registry, so `mail_wait`
+// unblocks when new mail lands -- decoupled from the FIFO trigger dispatch that
+// resolves a run's first input.
+//
+// Delivery is ASYNCHRONOUS. A `fire` never invokes a callback synchronously on
+// the delivering call stack: it schedules each callback on a microtask, per the
+// IMAP IDLE contract the `MailboxEvent` watcher models (MESSAGE.md § Real-Time
+// Notification). Delivery re-checks registration at the microtask, so a watcher
+// that unsubscribes between `fire` and delivery observes no event.
+export function createMailboxWatchRegistry() {
+    const watchers = new Map();
+    return {
+        watch(mailbox, callback) {
+            let set = watchers.get(mailbox);
+            if (set === undefined) {
+                set = new Set();
+                watchers.set(mailbox, set);
+            }
+            set.add(callback);
+            let active = true;
+            return () => {
+                // Idempotent: a double-unsubscribe must not remove a same-identity
+                // callback a later `watch` re-registered.
+                if (!active)
+                    return;
+                active = false;
+                const current = watchers.get(mailbox);
+                if (current === undefined)
+                    return;
+                current.delete(callback);
+                if (current.size === 0)
+                    watchers.delete(mailbox);
+            };
+        },
+        fire(mailbox, event) {
+            const set = watchers.get(mailbox);
+            if (set === undefined)
+                return;
+            // Snapshot the callbacks registered at fire time, then deliver each on
+            // its own microtask so no callback runs synchronously on this call
+            // stack. Re-check membership at delivery so a callback unsubscribed
+            // between now and its microtask does not receive the event.
+            for (const callback of [...set]) {
+                queueMicrotask(() => {
+                    const current = watchers.get(mailbox);
+                    if (current === undefined || !current.has(callback))
+                        return;
+                    callback(event);
+                });
+            }
+        },
+    };
+}

package/dist/child/outbound-mail-bridge.d.ts

@@ -30,7 +30,8 @@ export interface CreateChildOutboundMailBridgeOpts {
 }
 /**
  * Construct the child-side outbound-mail bridge. Pending sends live in
- * a map keyed by `requestId`; the bridge resolves the awaiter when the
- * supervisor's matching `outbound.result` lands.
+ * the shared pending-request core keyed by `requestId`; the bridge
+ * resolves the awaiter when the supervisor's matching `outbound.result`
+ * lands.
  */
 export declare function createChildOutboundMailBridge(opts: CreateChildOutboundMailBridgeOpts): ChildOutboundMailBridge;

package/dist/child/outbound-mail-bridge.js

@@ -32,24 +32,26 @@
 //      send.
 import { getLogger } from "@intx/log";
 import { base64Encode } from "@intx/types";
+import { createPendingRequestCore } from "./pending-request.js";
 const logger = getLogger(["workflow-host", "child", "outbound-mail-bridge"]);
 /**
  * Construct the child-side outbound-mail bridge. Pending sends live in
- * a map keyed by `requestId`; the bridge resolves the awaiter when the
- * supervisor's matching `outbound.result` lands.
+ * the shared pending-request core keyed by `requestId`; the bridge
+ * resolves the awaiter when the supervisor's matching `outbound.result`
+ * lands.
  */
 export function createChildOutboundMailBridge(opts) {
-    const pending = new Map();
-    const allocate = opts.allocateRequestId ?? defaultRequestIdAllocator();
+    const pending = createPendingRequestCore({
+        label: "workflow-child outbound mail",
+        allocatorPrefix: "om",
+        allocateRequestId: opts.allocateRequestId,
+    });
     return {
         get pendingCount() {
-            return pending.size;
+            return pending.pendingCount;
         },
         async submit(senderAddress, message) {
-            const requestId = allocate();
-            const resultPromise = new Promise((resolve, reject) => {
-                pending.set(requestId, { resolve, reject });
-            });
+            const { requestId, promise } = pending.register(undefined);
             try {
                 await opts.upstreamSender.send({
                     type: "outbound.message",
@@ -61,19 +63,17 @@ export function createChildOutboundMailBridge(opts) {
                 });
             }
             catch (cause) {
-                pending.delete(requestId);
-                const reason = cause instanceof Error ? cause.message : String(cause);
-                throw new Error(`workflow-child outbound mail: upstream send failed for requestId ${requestId}: ${reason}`, { cause });
+                pending.discard(requestId);
+                throw pending.sendFailedError(requestId, cause);
             }
-            return resultPromise;
+            return promise;
         },
         handleResult(data) {
-            const entry = pending.get(data.requestId);
+            const entry = pending.settle(data.requestId);
             if (entry === undefined) {
                 logger.warn `outbound.result landed with no pending entry; requestId=${data.requestId} dropped`;
                 return;
             }
-            pending.delete(data.requestId);
             if (data.result.ok) {
                 entry.resolve({
                     messageId: data.result.messageId,
@@ -81,13 +81,10 @@ export function createChildOutboundMailBridge(opts) {
                 });
                 return;
             }
-            entry.reject(new Error(`workflow-child outbound mail (requestId=${data.requestId}) rejected by supervisor: ${data.result.reason}`));
+            entry.reject(pending.rejectedError(data.requestId, data.result.reason));
         },
         cancelAll(reason) {
-            for (const [requestId, entry] of pending) {
-                entry.reject(new Error(`workflow-child outbound mail (requestId=${requestId}) cancelled: ${reason}`));
-            }
-            pending.clear();
+            pending.cancelAll(reason);
         },
     };
 }
@@ -114,6 +111,8 @@ function projectOutboundMessage(message) {
         payload.summary = message.summary;
     if (message.inReplyTo !== undefined)
         payload.inReplyTo = message.inReplyTo;
+    if (message.references !== undefined)
+        payload.references = message.references;
     if (message.correlationId !== undefined) {
         payload.correlationId = message.correlationId;
     }
@@ -125,19 +124,8 @@ function projectOutboundMessage(message) {
         payload.attachments = message.attachments.map((a) => ({
             name: a.name,
             contentType: a.contentType,
-            dataBase64: bytesToBase64(a.data),
+            dataBase64: base64Encode(a.data),
         }));
     }
     return payload;
 }
-function bytesToBase64(bytes) {
-    return base64Encode(bytes);
-}
-function defaultRequestIdAllocator() {
-    let counter = 0;
-    return () => {
-        counter += 1;
-        const rand = Math.random().toString(36).slice(2, 10);
-        return `om-${String(counter)}-${rand}`;
-    };
-}

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/pending-request.d.ts

@@ -0,0 +1,89 @@
+/**
+ * A live pending entry as returned by {@link PendingRequestCore.get} and
+ * {@link PendingRequestCore.settle}. `meta` is the per-bridge payload the
+ * entry was registered with (e.g. the substrate-write request whose merge
+ * closure the merge round-trip invokes).
+ */
+export type PendingEntryHandle<Value, Meta> = {
+    meta: Meta;
+    resolve: (value: Value) => void;
+    reject: (err: Error) => void;
+};
+/**
+ * Options for {@link createPendingRequestCore}. `label` prefixes every
+ * error the core builds (`<label>: upstream send failed for requestId
+ * <id>: ...`, `<label> (requestId=<id>) rejected by supervisor: ...`,
+ * `<label> (requestId=<id>) cancelled: ...`, `<label>: no pending entry
+ * for requestId <id>`), so each bridge's observable error strings stay
+ * its own. `allocatorPrefix` seeds the default requestId allocator
+ * (`<prefix>-<counter>-<rand>`); tests inject `allocateRequestId` for a
+ * deterministic id.
+ */
+export type PendingRequestCoreOptions = {
+    label: string;
+    allocatorPrefix: string;
+    /** `undefined` is accepted explicitly so callers can forward an optional option verbatim. */
+    allocateRequestId?: (() => string) | undefined;
+};
+/**
+ * The pending-request lifecycle surface a bridge composes into its own
+ * `submit` / `handle*` / `cancelAll` methods.
+ */
+export type PendingRequestCore<Value, Meta = undefined> = {
+    /** Number of registered-but-unsettled requests. */
+    readonly pendingCount: number;
+    /**
+     * Mint a requestId, register an awaiter keyed by it, and return the id
+     * plus the promise the bridge returns from its `submit`. The entry
+     * stays pending until `settle` or `cancelAll` acts on it, or `discard`
+     * removes it without settling (the upstream-send-failure path).
+     */
+    register(meta: Meta): {
+        requestId: string;
+        promise: Promise<Value>;
+    };
+    /**
+     * Remove a pending entry without settling its promise. Used when the
+     * upstream send itself fails, so the abandoned awaiter does not leak.
+     */
+    discard(requestId: string): void;
+    /**
+     * Look up a pending entry WITHOUT removing it. Used by the
+     * substrate-write bridge's merge round-trip, which must reach the
+     * entry's merge closure while the entry stays alive for the terminal
+     * write response.
+     */
+    get(requestId: string): PendingEntryHandle<Value, Meta> | undefined;
+    /**
+     * Look up a pending entry and remove it. Used by the response-frame
+     * handlers: the entry is gone before its promise resolves/rejects, so
+     * a later stale response or `cancelAll` finds nothing to act on.
+     */
+    settle(requestId: string): PendingEntryHandle<Value, Meta> | undefined;
+    /**
+     * Reject every pending entry with `<label> (requestId=<id>) cancelled:
+     * <reason>` and clear the map. The control loop invokes this on any
+     * exit path so no awaiter leaks when the supervisor has torn the IPC
+     * down.
+     */
+    cancelAll(reason: string): void;
+    /** `<label>: upstream send failed for requestId <id>: <cause message>` with `{ cause }`. */
+    sendFailedError(requestId: string, cause: unknown): Error;
+    /** `<label> (requestId=<id>) rejected by supervisor: <reason>`. */
+    rejectedError(requestId: string, reason: string): Error;
+    /** `<label>: no pending entry for requestId <id>` (substrate merge failure reply). */
+    noPendingError(requestId: string): Error;
+};
+/**
+ * Construct a pending-request core for one bridge. Pending entries live in
+ * a map keyed by `requestId`; the bridge's response handler settles the
+ * awaiter when the matching response frame lands.
+ */
+export declare function createPendingRequestCore<Value, Meta = undefined>(opts: PendingRequestCoreOptions): PendingRequestCore<Value, Meta>;
+/**
+ * Default `requestId` allocator: a per-instance monotonic counter plus a
+ * random suffix, so ids are unique across bridge instances without any
+ * cross-instance coordination. The `prefix` names the owning bridge
+ * (`sw-`, `om-`, `mm-`) for triage in supervisor logs.
+ */
+export declare function defaultRequestIdAllocator(prefix: string): () => string;

package/dist/child/pending-request.js

@@ -0,0 +1,80 @@
+// Generic pending-request core shared by the three child-side control-IPC
+// bridges (substrate-write, outbound-mail, mailbox-mutation).
+//
+// Every bridge runs the same request/response round-trip over the control
+// channel: `submit` mints a `requestId`, registers a pending awaiter keyed
+// by that id, emits a request frame upstream, and resolves/rejects the
+// awaiter when the supervisor's matching response frame lands. The three
+// bridges differ only in the request payload they send, the value they
+// resolve, the label their error messages carry, and (for the
+// substrate-write bridge) an intermediate merge round-trip that must peek
+// at the pending entry without settling it.
+//
+// This core owns that lifecycle in one place so the per-bridge files
+// contain only their wire-specific parts. It never touches the control
+// channel itself: each bridge performs its own `upstreamSender.send` so
+// the frame payloads stay byte-identical to what the supervisor's
+// `ControlPayload` validator expects.
+/**
+ * Construct a pending-request core for one bridge. Pending entries live in
+ * a map keyed by `requestId`; the bridge's response handler settles the
+ * awaiter when the matching response frame lands.
+ */
+export function createPendingRequestCore(opts) {
+    const pending = new Map();
+    const allocate = opts.allocateRequestId ?? defaultRequestIdAllocator(opts.allocatorPrefix);
+    return {
+        get pendingCount() {
+            return pending.size;
+        },
+        register(meta) {
+            const requestId = allocate();
+            const promise = new Promise((resolve, reject) => {
+                pending.set(requestId, { meta, resolve, reject });
+            });
+            return { requestId, promise };
+        },
+        discard(requestId) {
+            pending.delete(requestId);
+        },
+        get(requestId) {
+            return pending.get(requestId);
+        },
+        settle(requestId) {
+            const entry = pending.get(requestId);
+            if (entry !== undefined)
+                pending.delete(requestId);
+            return entry;
+        },
+        cancelAll(reason) {
+            for (const [requestId, entry] of pending) {
+                entry.reject(new Error(`${opts.label} (requestId=${requestId}) cancelled: ${reason}`));
+            }
+            pending.clear();
+        },
+        sendFailedError(requestId, cause) {
+            const reason = cause instanceof Error ? cause.message : String(cause);
+            return new Error(`${opts.label}: upstream send failed for requestId ${requestId}: ${reason}`, { cause });
+        },
+        rejectedError(requestId, reason) {
+            return new Error(`${opts.label} (requestId=${requestId}) rejected by supervisor: ${reason}`);
+        },
+        noPendingError(requestId) {
+            return new Error(`${opts.label}: no pending entry for requestId ${requestId}`);
+        },
+    };
+}
+/**
+ * Default `requestId` allocator: a per-instance monotonic counter plus a
+ * random suffix, so ids are unique across bridge instances without any
+ * cross-instance coordination. The `prefix` names the owning bridge
+ * (`sw-`, `om-`, `mm-`) for triage in supervisor logs.
+ */
+export function defaultRequestIdAllocator(prefix) {
+    let counter = 0;
+    return () => {
+        counter += 1;
+        const rand = Math.random().toString(36).slice(2, 10);
+        return `${prefix}-${String(counter)}-${rand}`;
+    };
+}