@intx/workflow-host 0.2.2 → 0.4.0

package/dist/supervisor/terminal-commit.d.ts

@@ -0,0 +1,36 @@
+import type { RepoId, RepoStore as SubstrateRepoStore } from "@intx/hub-sessions/substrate";
+export type CommitRunFailedOpts = {
+    /** Substrate handle the supervisor writes through. */
+    substrate: SubstrateRepoStore;
+    /** Workflow-run repo for this deployment. */
+    repoId: RepoId;
+    /** Events ref the workflow-run repo writes to. */
+    ref: string;
+    /** Anchor run id used to construct the supervisor principal. */
+    anchorRunId: string;
+    /** Run id whose event log receives the RunFailed entry. */
+    runId: string;
+    /** ISO-8601 commit timestamp the event carries. */
+    at: string;
+    /** Operator-facing failure reason on `RunFailed.error.message`. */
+    message: string;
+};
+export type CommitRunFailedResult = {
+    /** Substrate-assigned commit SHA the write produced. */
+    commitSha: string;
+    /**
+     * True when a `RunFailed` was appended; false when the run was already
+     * terminal and the write was a no-op (terminal-lock respected).
+     */
+    appended: boolean;
+};
+/**
+ * Append a supervisor-authored `RunFailed` to a run's event log, unless the
+ * run is already terminal. The next seq is computed inside the substrate
+ * merge (atomic against any concurrent writer under the per-repo lock): the
+ * first event on an empty tree lands at seq 1 (the runtime's convention),
+ * otherwise at `maxSeq + 1` so the log stays seq-contiguous. If the run's
+ * highest-seq event is already terminal, the write is a no-op so push
+ * validation's terminal-lock is never tripped.
+ */
+export declare function commitRunFailed(opts: CommitRunFailedOpts): Promise<CommitRunFailedResult>;

package/dist/supervisor/terminal-commit.js

@@ -0,0 +1,130 @@
+// Supervisor-authored terminal-event commit for the crash-loop guard.
+//
+// When the crash-loop guard latches, the workflow-process child is dead
+// and cannot commit its own terminal event, yet the deployment's run must
+// reach a terminal state so its external `workflow_run.status` flips to
+// `failed` -- the sole durable, queryable signal of a crash-loop. The
+// supervisor's `crash-looping` phase is in-memory and per-process; no
+// external reader observes it. The supervisor, as the sole writer of the
+// workflow-run repo, authors a `RunFailed` for the deployment's stable
+// run so the crash-loop leaves a durable tombstone.
+//
+// Unlike `commitCancelRequested`, a terminal workflow event carries no
+// signature: only `CancelRequested` is signed (for its origin<->principal
+// cross-check at push validation), so this writer is unsigned. It writes
+// under the `supervisor` principal, which the workflow-run kind handler
+// authorizes for the deployment's own event log (`repoId.id ===
+// anchorRunId`); terminal events have no per-type authorship check.
+import { type } from "arktype";
+import { getLogger } from "@intx/log";
+import { parseEventSeq } from "@intx/hub-sessions/substrate";
+import { workflowEventToOnDisk } from "../adapters/repo-store.js";
+const logger = getLogger(["workflow-host", "supervisor", "terminal-commit"]);
+/** Path layout inside the workflow-run repo: `runs/<runId>/events/<seq>.json`. */
+const RUNS_PREFIX = "runs";
+const EVENTS_DIR = "events";
+/**
+ * Terminal run-event kinds, mirroring the runtime's terminal vocabulary
+ * (`RunCompleted`/`RunFailed`/`RunCancelled`). Inlined because the workflow
+ * package exports only the phase-level `isTerminalRunPhase`, not an
+ * event-kind set; the child runtime (`run-child`) and the substrate adapter
+ * (`repo-store`) inline the same three kinds. Reducing the log to a phase to
+ * reuse `isTerminalRunPhase` would be strictly heavier for a last-event
+ * type check.
+ */
+const TERMINAL_EVENT_KINDS = new Set([
+    "RunCompleted",
+    "RunFailed",
+    "RunCancelled",
+]);
+const SUPERVISOR_PRINCIPAL_KIND = "supervisor";
+/**
+ * On-disk event envelope, validated at the substrate read boundary. Only
+ * `seq` and `type` are load-bearing here (max-seq computation and the
+ * terminal-lock check); the rest of the event body is ignored.
+ */
+const OnDiskEventEnvelope = type({
+    seq: "number >= 0",
+    type: "string",
+    "+": "ignore",
+});
+/**
+ * Append a supervisor-authored `RunFailed` to a run's event log, unless the
+ * run is already terminal. The next seq is computed inside the substrate
+ * merge (atomic against any concurrent writer under the per-repo lock): the
+ * first event on an empty tree lands at seq 1 (the runtime's convention),
+ * otherwise at `maxSeq + 1` so the log stays seq-contiguous. If the run's
+ * highest-seq event is already terminal, the write is a no-op so push
+ * validation's terminal-lock is never tripped.
+ */
+export async function commitRunFailed(opts) {
+    const prefix = `${RUNS_PREFIX}/${opts.runId}/${EVENTS_DIR}/`;
+    const principal = {
+        kind: SUPERVISOR_PRINCIPAL_KIND,
+        anchorRunId: opts.anchorRunId,
+    };
+    const decoder = new TextDecoder();
+    let appended = false;
+    const { commitSha } = await opts.substrate.writeTreePreservingPrefix(principal, opts.repoId, opts.ref, {
+        preservePrefix: prefix,
+        merge: async (existing) => {
+            let maxSeq = -1;
+            let maxPath = null;
+            for (const filepath of existing.keys()) {
+                const name = filepath.slice(prefix.length);
+                const seq = parseEventSeq(name);
+                if (seq === null)
+                    continue;
+                if (seq > maxSeq) {
+                    maxSeq = seq;
+                    maxPath = filepath;
+                }
+            }
+            const carried = {};
+            for (const [k, v] of existing)
+                carried[k] = v;
+            // Terminal-lock: appending a terminal event after an existing one
+            // is rejected at push validation. If the run already ended, its
+            // `workflow_run.status` is already terminal, so the crash-loop
+            // tombstone is redundant -- no-op rather than push a rejected write.
+            //
+            // This detects the per-event (`events/<seq>.json`) form only, not
+            // the sealed combined-log (`events.jsonl`) form, which lives outside
+            // `preservePrefix`. That is sufficient here because the anchor run
+            // this commit targets is sealed only when the DEPLOYMENT itself is
+            // terminal, and the crash-loop latch fires only while the deployment
+            // is running -- so the run is never in the sealed form at this call.
+            // If a sealed run ever reached here, the append would produce a tree
+            // carrying both forms, which push validation rejects, and the caller
+            // logs the failure (best-effort tombstone) rather than corrupting.
+            if (maxPath !== null) {
+                const raw = existing.get(maxPath);
+                if (raw !== undefined) {
+                    const parsed = OnDiskEventEnvelope(JSON.parse(decoder.decode(raw)));
+                    if (parsed instanceof type.errors) {
+                        throw new Error(`commitRunFailed: event blob ${maxPath} failed validation: ${parsed.summary}`);
+                    }
+                    if (TERMINAL_EVENT_KINDS.has(parsed.type)) {
+                        return carried;
+                    }
+                }
+            }
+            const nextSeq = maxSeq < 0 ? 1 : maxSeq + 1;
+            const event = {
+                kind: "RunFailed",
+                seq: nextSeq,
+                at: opts.at,
+                error: { message: opts.message },
+            };
+            const onDisk = workflowEventToOnDisk(event, nextSeq);
+            carried[`${prefix}${String(nextSeq)}.json`] = JSON.stringify(onDisk);
+            appended = true;
+            return carried;
+        },
+        message: `append RunFailed (crash-loop) for run ${opts.runId}`,
+    });
+    if (!appended) {
+        logger.info `commitRunFailed: run ${opts.runId} already terminal; no RunFailed appended`;
+    }
+    return { commitSha, appended };
+}

package/dist/supervisor/types.d.ts

@@ -1,5 +1,6 @@
-import type { DequeueToProcessingResult, EnqueueInboxArgs, EnqueueInboxResult, MarkConsumedArgs, MarkConsumedResult, Principal, RepoId, RepoStore as SubstrateRepoStore, ReplayProcessingToInboxOpts, ReplayProcessingToInboxResult } from "@intx/hub-sessions/substrate";
-import type { OutboundMessage, SendReceipt } from "@intx/types/runtime";
+import type { DequeueToProcessingResult, EnqueueInboxArgs, EnqueueInboxOutcome, MarkConsumedArgs, MarkConsumedResult, Principal, RepoId, RepoStore as SubstrateRepoStore, ReplayProcessingToInboxOpts, ReplayProcessingToInboxResult } from "@intx/hub-sessions/substrate";
+import type { SignalKind } from "@intx/types";
+import type { ApprovalSnapshot, OutboundMessage, SendReceipt } from "@intx/types/runtime";
 import type { RunCancelled, RunCompleted, RunFailed } from "@intx/workflow";
 import type { FrameReader, NdjsonReader, NdjsonWriter } from "../ipc/index.js";
 /**
@@ -69,7 +70,13 @@ export type PrincipalSigner = (kind: WorkflowSupervisorPrincipalKind, payload: U
  *
  * `subscribeMailForAddress` returns a disposer the supervisor calls
  * during teardown. The supplied handler is invoked with the raw RFC
- * 2822 message bytes of each inbound message at the address.
+ * 2822 message bytes of each inbound message at the address, and returns
+ * a promise that resolves once the message is durably accepted (its inbox
+ * write landed, or the message was already durably present) and rejects
+ * when it was not (a transient failure, a stale refusal, or a phase where
+ * the deployment is tearing down). The host propagates that settlement to
+ * the wire so a durable-receipt ack is sent only on resolution -- resolve
+ * is the ack signal, reject is the withhold signal.
  *
  * `sendOutbound` is the OUTBOUND half of mailbox ownership (§3a). The
  * supervisor is the sole mail owner: the workflow-process child never
@@ -92,7 +99,7 @@ export type PrincipalSigner = (kind: WorkflowSupervisorPrincipalKind, payload: U
 export interface MailBusBindings {
     registerAddress(address: string): void;
     unregisterAddress(address: string): void;
-    subscribeMailForAddress(address: string, handler: (rawMessage: Uint8Array) => void): () => void;
+    subscribeMailForAddress(address: string, handler: (rawMessage: Uint8Array) => Promise<void>): () => void;
     sendOutbound(senderAddress: string, message: OutboundMessage): Promise<SendReceipt>;
 }
 /**
@@ -181,11 +188,33 @@ export type DeriveMailAuditRef = (messageId: string, rawMessage: Uint8Array) =>
  * surprise.
  */
 export interface InboxPrimitives {
-    enqueueInbox(store: SubstrateRepoStore, principal: Principal, repoId: RepoId, args: EnqueueInboxArgs): Promise<EnqueueInboxResult>;
+    enqueueInbox(store: SubstrateRepoStore, principal: Principal, repoId: RepoId, args: EnqueueInboxArgs): Promise<EnqueueInboxOutcome>;
     dequeueToProcessing(store: SubstrateRepoStore, principal: Principal, repoId: RepoId, address: string): Promise<DequeueToProcessingResult>;
     markConsumed(store: SubstrateRepoStore, principal: Principal, repoId: RepoId, args: MarkConsumedArgs): Promise<MarkConsumedResult>;
     replayProcessingToInbox(store: SubstrateRepoStore, principal: Principal, repoId: RepoId, address: string, opts?: ReplayProcessingToInboxOpts): Promise<ReplayProcessingToInboxResult>;
 }
+/**
+ * A control-plane suspension the supervisor forwards to the host after a
+ * workflow-process child reports a park. The child supplies `runId`,
+ * `correlationId`, and `kind`; the supervisor stamps `anchorRunId` and
+ * `agentAddress` from its own bindings before invoking the host's
+ * `onSuspensionRegister`. The host (production: the sidecar) turns this into
+ * a `signal.correlation.register` frame the hub co-writes the run's routing +
+ * approval rows from.
+ */
+export interface SuspensionRegistration {
+    runId: string;
+    correlationId: string;
+    kind: SignalKind;
+    anchorRunId: string;
+    agentAddress: string;
+    /**
+     * Approver-facing snapshot of the parked tool call, forwarded from the
+     * child's `park.notify`. Present only for an ask-rail suspension; the host
+     * turns it into the register frame's snapshot.
+     */
+    approvalSnapshot?: ApprovalSnapshot;
+}
 /**
  * Constructor arguments for `createWorkflowSupervisor`. One
  * `RepoStore` handle plus a `signAsPrincipal` callback that mints
@@ -201,6 +230,79 @@ export interface WorkflowSupervisorBindings {
     signAsPrincipal: PrincipalSigner;
     /** Mail-bus surface for address registration and inbound subscription. */
     mailBus: MailBusBindings;
+    /**
+     * Optional control-plane suspension sink. Two callers invoke it, both
+     * stamping `anchorRunId` and `deploymentMailAddress` (as `agentAddress`)
+     * onto the child-supplied `runId`/`correlationId`/`kind`: the upstream-control
+     * pump's `park.notify` arm (the happy-path emit at suspend), and
+     * `reEmitParkedCorrelations` (the re-establishment re-emit that recovers a
+     * register the hub missed while it was down). Production wires this to the
+     * sidecar's hub link so a `signal.correlation.register` frame reaches the hub;
+     * a host that does not wire it does not register suspensions (today, the
+     * tests). Best-effort: a throwing sink is logged and
+     * both callers keep going, so one bad register cannot wedge the control pump
+     * or abort a re-emit partway through the parked set.
+     */
+    onSuspensionRegister?: (registration: SuspensionRegistration) => void;
+    /**
+     * Self-termination sink. The supervisor invokes it when it reaches a terminal
+     * phase on its own -- the crash-loop latch (`crash-looping`), a channel crash
+     * while recycling, or a recycle failure (both `stopped`) -- but NOT when the
+     * host drives it down through the public `shutdown()`, and NOT for a failure
+     * of the initial spawn handshake (that is the deploy's to unwind). Production
+     * wires this to the sidecar so it reclaims the deployment address (drops the
+     * supervisor from its active map and releases the address's routing state)
+     * and the address becomes redeployable without a manual undeploy.
+     *
+     * The handler MUST be idempotent. Firing is not exactly-once: two
+     * self-terminating callers interleaving through teardown (e.g. a channel
+     * crash while recycling plus the recycle-failure catch) can each fire. The
+     * sidecar's reclaim absorbs a repeat because its `activeSupervisors.has`
+     * guard makes the second run a no-op.
+     *
+     * Unlike `onSuspensionRegister`, this sink does NOT share the same
+     * log-and-continue contract on the host side. A missed suspension has an
+     * independent recovery path (`reEmitParkedCorrelations`); a missed reclaim
+     * does not -- the address stays stranded until an operator undeploys. So
+     * the host's handler is engineered to be total, and a failure there is
+     * logged loudly rather than swallowed. The supervisor still invokes this
+     * best-effort (a throwing sink cannot break the terminal transition), but a
+     * host that copies `onSuspensionRegister`'s quiet-swallow semantics onto its
+     * reclaim handler reintroduces the stranding bug.
+     */
+    onSelfTerminate?: (info: {
+        phase: "stopped" | "crash-looping";
+        reason: string;
+    }) => void;
+    /**
+     * Per-run grants source the dispatch loop consults before it forwards a
+     * `trigger.fire`. Unlike `onSuspensionRegister` (best-effort, fire-and-
+     * forget), this is a request/response contract: the supervisor awaits the
+     * returned `CredentialsSnapshot` and pushes it to the child over the
+     * control channel BEFORE firing the run's trigger, so the child's
+     * authorize closure binds to the run's grants rather than a stale
+     * spawn-time snapshot. A throwing sink is NOT swallowed -- the dispatch
+     * loop fails that run (a synthesized `RunFailed`) rather than firing the
+     * trigger against absent grants.
+     *
+     * When this binding is wired, it is the SOLE grants push: `spawn` does not
+     * push a spawn-time snapshot, so the per-run push is the only thing that
+     * satisfies the child's throw-on-null authorize guard. A caller that
+     * injects no per-run sink -- today, the supervisor's own tests -- keeps the
+     * spawn-time push instead. Production (the sidecar) wires it to the
+     * walk-derived per-step credentials assembly.
+     */
+    onRunStart?: (args: {
+        runId: string;
+        anchorRunId: string;
+    }) => Promise<import("./credentials.js").CredentialsSnapshot>;
+    /**
+     * Decrypted credential material for the deployment's tools, delivered to the
+     * child on the pre-trigger barrier alongside the grants. Absent when the
+     * deployment binds no credentials. A rotation flows through
+     * `deliverCredentials`, not this static binding.
+     */
+    credentialDelivery?: import("@intx/types/sidecar").CredentialDelivery;
     /** Subprocess spawner the supervisor invokes per spawn. */
     subprocessSpawner: SubprocessSpawner;
     /**
@@ -235,8 +337,8 @@ export interface WorkflowSupervisorBindings {
     workflowRunRepoId: import("@intx/hub-sessions").RepoId;
     /** Workflow-run repo ref the supervisor commits events to. */
     workflowRunRef: string;
-    /** Deployment id baked into the supervisor's principal claims. */
-    deploymentId: string;
+    /** Anchor run id baked into the supervisor's principal claims. */
+    anchorRunId: string;
     /**
      * Number of steps in the deployed `WorkflowDefinition`
      * (`stepOrder.length`). The supervisor threads this into the child's
@@ -268,7 +370,7 @@ export interface WorkflowSupervisorBindings {
     deriveStepAddress: import("./credentials.js").DeriveStepAddress;
     /**
      * Optional override for the step's agent-state repo identity. The
-     * default convention is `<deploymentId>-<stepId>`.
+     * default convention is `<anchorRunId>-<stepId>`.
      */
     deriveStepRepoId?: import("./credentials.js").DeriveStepRepoId;
     /**
@@ -377,11 +479,11 @@ export interface WorkflowSupervisorBindings {
     /**
      * Workflow-run substrate principal the supervisor uses to author
      * inbox/processing/consumed writes. The substrate's workflow-run
-     * kind handler accepts a `{ kind: "supervisor", deploymentId }`
+     * kind handler accepts a `{ kind: "supervisor", anchorRunId }`
      * principal for claim-check writes; the supervisor constructs this
      * value once at bindings construction and reuses it for every
      * claim-check operation. Defaults to `{ kind: "supervisor",
-     * deploymentId }` derived from `bindings.deploymentId`; tests
+     * anchorRunId }` derived from `bindings.anchorRunId`; tests
      * override it when they need to assert on a structurally distinct
      * principal shape.
      */
@@ -413,14 +515,65 @@ export interface WorkflowSupervisorBindings {
      */
     readyTimeoutMs?: number;
     /**
-     * Watchdog timeout (ms) for the supervisor's substrate-write
-     * handler's wait on the dispatch loop's `markConsumed` when a
-     * terminal-event blob lands in a proxied write. Defaults to
-     * `DEFAULT_TERMINAL_WRITE_WATCHDOG_MS`. Tests inject a small value
-     * so the watchdog path is observable without holding a test loop
-     * for the production duration.
+     * Crash-loop guard: the maximum number of UNEXPECTED workflow-process
+     * child exits (crash, OOM, panic, signal) the supervisor tolerates
+     * within `crashLoopWindowMs` before it stops respawning and latches the
+     * deployment to a terminal state. The boot edge resolves the operator's
+     * config and supplies it; absent, `DEFAULT_CRASH_LOOP_MAX_COUNT` (3)
+     * applies. The operator owns this bound.
+     */
+    crashLoopMaxCount?: number;
+    /**
+     * Sliding window (ms) over which `crashLoopMaxCount` unexpected exits
+     * latch the deployment. Absent, `DEFAULT_CRASH_LOOP_WINDOW_MS` (60s)
+     * applies.
+     */
+    crashLoopWindowMs?: number;
+    /**
+     * Stable-run duration (ms) after a respawn: once a respawned child has
+     * stayed up this long, the crash counter resets, so a burst of crashes
+     * followed by stability does not permanently latch. Absent,
+     * `DEFAULT_CRASH_LOOP_STABLE_RESET_MS` (60s) applies. Driven by the
+     * injectable `setTimer`/`clearTimer` pair so tests are deterministic.
+     */
+    crashLoopStableResetMs?: number;
+    /**
+     * Initial respawn backoff (ms): the wait before the FIRST respawn after
+     * an unexpected exit. Each subsequent respawn doubles the wait, capped at
+     * `respawnBackoffMaxMs`; a stable run resets it to this value. Absent,
+     * `DEFAULT_RESPAWN_BACKOFF_INITIAL_MS` (1s) applies.
      */
-    terminalWriteWatchdogMs?: number;
+    respawnBackoffInitialMs?: number;
+    /**
+     * Maximum respawn backoff (ms) the exponential doubling is capped at, so
+     * a rapidly-flapping child does not saturate the host. Absent,
+     * `DEFAULT_RESPAWN_BACKOFF_MAX_MS` (30s) applies.
+     *
+     * Config invariant: keep this comfortably below `crashLoopWindowMs`.
+     * Crashes must fall within the window to accumulate toward the latch, and
+     * the backoff spaces them apart; a cap at or above the window guarantees a
+     * slow flapper's timestamps age out before the count reaches
+     * `crashLoopMaxCount`, so the guard never latches. This is necessary but
+     * not sufficient: the child's own lifetime also spaces crashes, so a child
+     * whose healthy lifetime approaches `crashLoopStableResetMs` can still
+     * out-space the window (and never earn a counter reset either), respawning
+     * indefinitely. Windowed crash detection cannot catch an arbitrarily slow
+     * flapper; the window/backoff/stable-reset trio bounds the FAST flap this
+     * guard targets.
+     */
+    respawnBackoffMaxMs?: number;
+    /**
+     * Watchdog timeout (ms) for `reEmitParkedCorrelations`' wait on the
+     * child's `parked-correlations.response`. Caps the wait so a
+     * wedged-but-alive child (whose cohort never tears down, so the
+     * cohort-abort rejection never fires) cannot hang the re-registration
+     * driver -- and therefore the reconnect/re-establishment caller that
+     * awaits it. On expiry the pending query is dropped and the driver
+     * returns; the next re-establishment re-drives it. Defaults to
+     * `DEFAULT_PARKED_QUERY_WATCHDOG_MS`. Tests inject a small value so the
+     * timeout path is observable.
+     */
+    parkedQueryWatchdogMs?: number;
     /**
      * Optional per-message dispatch-timing observer. When supplied, the
      * dispatch loop invokes it twice per dispatched inbox entry: once with
@@ -490,9 +643,8 @@ export type DispatchSubstrateLeg = "enqueue" | "dequeue" | "runevent" | "markcon
  * (design §10b). All are cheap filesystem reads against the workflow-run
  * repo's on-disk working tree, taken only when the observer is wired.
  *
- *   - `runsFanOut`     — entry count under `runs/` (one subdir per message;
- *                        never pruned). The candidate-(i) "collapse runs"
- *                        win is sized by this.
+ *   - `runsFanOut`     — entry count under `runs/` (the stable top-level run
+ *                        plus any internal body-child runs).
  *   - `consumedFanOut` — entry count under
  *                        `addresses/<addr>/consumed/` (one dedup entry per
  *                        message; never pruned). The candidate-(iv) "prune
@@ -512,8 +664,13 @@ export type DispatchStructuralCounters = {
 /**
  * One observation emitted by `WorkflowSupervisorBindings.onDispatchTiming`.
  *
+ * Both variants key on `messageId`, the per-message identifier (the mail's
+ * Message-ID). The top-level run id cannot serve as the key: one deployment
+ * keeps that stable id across all of its live trigger occurrences, so it does
+ * not distinguish one dispatched message from the next.
+ *
  * The `"roundtrip"` variant is the 4.7 latency-gate bracket: pair the
- * `"dispatch-start"` and `"reply-produced"` marks for the same `runId` to
+ * `"dispatch-start"` and `"reply-produced"` marks for the same `messageId` to
  * recover the per-message round-trip. `atMs` is a high-resolution
  * monotonic timestamp (`performance.now()`).
  *
@@ -528,12 +685,12 @@ export type DispatchStructuralCounters = {
  */
 export type DispatchTimingMark = {
     kind: "roundtrip";
-    runId: string;
+    messageId: string;
     marker: "dispatch-start" | "reply-produced";
     atMs: number;
 } | {
     kind: "leg";
-    runId: string;
+    messageId: string;
     leg: DispatchSubstrateLeg;
     phase: "start" | "end";
     atMs: number;

package/dist/testing/change-notifier.d.ts

@@ -0,0 +1,12 @@
+export type ChangeNotifier = {
+    /** Call from the double after any mutation a waiter might care about. */
+    notify(): void;
+    /**
+     * Resolve once `predicate` holds. Evaluated immediately, then again after
+     * each `notify`. Carries no deadline: a predicate that never holds is
+     * caught by the lane timeout, per "Synchronizing on State, Not Time" in
+     * CONVENTIONS.md.
+     */
+    until(predicate: () => boolean): Promise<void>;
+};
+export declare function createChangeNotifier(): ChangeNotifier;

package/dist/testing/change-notifier.js

@@ -0,0 +1,63 @@
+// Level-triggered wait over a mutable test double.
+//
+// A test that needs a double to have reached some state -- two entries
+// consumed, an entry moved to processing -- has no event to await, because
+// the state lives in a map the double mutates in place. The usual stand-in is
+// a predicate re-evaluated on a timer, which makes the tick interval and the
+// deadline part of whether the test passes.
+//
+// This inverts it: the double reports that it changed, and the waiter
+// re-evaluates the predicate only then. The predicate is still a predicate --
+// there is no event to name when the subject is "the map now looks like this"
+// -- but nothing is re-read on a schedule and no duration decides the
+// outcome.
+//
+// `until` evaluates the predicate on entry to every pass of its loop, so a
+// state the double already reached resolves it and a caller never has to know
+// whether it armed the wait in time. Only `notify` is an edge: one with no
+// waiter registered is dropped, which is why the double must call it after
+// every mutation rather than only when it thinks someone is watching.
+//
+// It is deliberately NOT a consolidation of the doubles themselves. The five
+// inbox doubles in this package are genuinely different implementations
+// rather than cosmetic variants, and a merged superset could not be shown to
+// preserve what each test relies on. Sharing the waiting is the part that was
+// worth sharing.
+export function createChangeNotifier() {
+    let waiters = [];
+    return {
+        notify() {
+            // Clearing the list is what bounds it. Every pass of the wait loop
+            // below registers a resolver, and the pass that returns leaves its own
+            // resolver behind unsettled; without the clear those accumulate for the
+            // life of the notifier. Measured over 50 notifies with one waiter: 1
+            // entry with the clear, 51 without.
+            //
+            // Clearing BEFORE the wake rather than after is not what makes a
+            // re-arming waiter wait for the next change instead of this one. Waking
+            // a settled resolver is a no-op, and the loop re-registers only after
+            // `await changed` resumes, which is a microtask boundary -- by then this
+            // function has finished iterating. A mutant that wakes the live list and
+            // clears afterwards passes every test that uses this helper.
+            const waking = waiters;
+            waiters = [];
+            for (const waiter of waking)
+                waiter();
+        },
+        async until(predicate) {
+            for (;;) {
+                // Re-checked on every pass, which is what makes this usable when the
+                // change already happened before the wait was created. The registering
+                // executor runs synchronously, so no notify can land between the check
+                // and the registration in either order -- the loop is the invariant,
+                // not the order of those two lines.
+                const changed = new Promise((resolve) => {
+                    waiters.push(resolve);
+                });
+                if (predicate())
+                    return;
+                await changed;
+            }
+        },
+    };
+}

package/dist/testing/index.d.ts

@@ -0,0 +1,8 @@
+export { createMemoryFrameStream, createMemoryNdjsonStream, type MemoryFrameStream, type MemoryNdjsonStream, } from "./memory-streams.js";
+export { createSupervisorReaper, type ReapableSupervisor, type SupervisorReaper, } from "./supervisor-reaper.js";
+export { createMockMailBus, type MockMailBus } from "./mail-bus.js";
+export { createSpawnObserver, type SpawnObserver } from "./spawn-observer.js";
+export { parseTriggerFireRunIds, readPayloadsOfType, waitForTriggerFireRunIds, waitForUpstreamPayload, waitForUpstreamPayloads, type UpstreamFrameSource, } from "./upstream-frames.js";
+export { createChangeNotifier, type ChangeNotifier } from "./change-notifier.js";
+export { createLogCapture, type CapturedLogRecord, type LogCapture, } from "./log-capture.js";
+export { createStubRepoStore, type StubRepoStoreOpts } from "./stub-repo-store.js";

package/dist/testing/index.js

@@ -0,0 +1,16 @@
+// @intx/workflow-host/testing -- in-memory doubles for the IPC transports.
+//
+// These exist so a test can drive a supervisor or a workflow-process child
+// over the real channel code without spawning a process. They hold their
+// frames in an array and have no durability, no backpressure, and no
+// framing beyond the newline terminator the event channel expects, so a
+// production caller reaching for this subpath is almost certainly looking
+// for the real transports in the package root instead.
+export { createMemoryFrameStream, createMemoryNdjsonStream, } from "./memory-streams.js";
+export { createSupervisorReaper, } from "./supervisor-reaper.js";
+export { createMockMailBus } from "./mail-bus.js";
+export { createSpawnObserver } from "./spawn-observer.js";
+export { parseTriggerFireRunIds, readPayloadsOfType, waitForTriggerFireRunIds, waitForUpstreamPayload, waitForUpstreamPayloads, } from "./upstream-frames.js";
+export { createChangeNotifier } from "./change-notifier.js";
+export { createLogCapture, } from "./log-capture.js";
+export { createStubRepoStore } from "./stub-repo-store.js";

package/dist/testing/log-capture.d.ts

@@ -0,0 +1,52 @@
+/** One captured record, with its message template already interpolated. */
+export type CapturedLogRecord = {
+    readonly category: readonly string[];
+    readonly level: string;
+    readonly message: string;
+};
+export type LogCapture = {
+    /**
+     * Replace the process-wide logging configuration with the capturing one.
+     * Pass straight to `beforeAll`. Throws if a capture is already installed
+     * through this object.
+     */
+    install(): void;
+    /**
+     * Put back the configuration `install` replaced. Pass straight to
+     * `afterAll`. Throws if nothing was installed.
+     */
+    restore(): void;
+    /**
+     * Drop the captured records and abandon every armed waiter. Pass straight
+     * to `beforeEach`.
+     */
+    reset(): void;
+    /** Every record captured since the last `reset`, in log order. */
+    records(): readonly CapturedLogRecord[];
+    /** The messages of the captured `error` records, in log order. */
+    errors(): string[];
+    /**
+     * Resolve with the first record at any level whose message contains
+     * `needle`, whether it was logged before this call or arrives after it.
+     * Carries no deadline: a record that never arrives is caught by the lane
+     * timeout, per "Synchronizing on State, Not Time" in CONVENTIONS.md.
+     *
+     * `needle` must identify the record uniquely within its own test. Matching
+     * on a message some other test also emits is what makes this a barrier in
+     * name only: `reset` clears the records a previous test logged, but it
+     * cannot exclude the ones still arriving from work that test left running,
+     * and nothing in a record says which test caused it. A wait satisfied by
+     * such a straggler returns before the awaited work has happened, and the
+     * assertion behind it reads pre-barrier state and passes. Where two tests
+     * exercise the same path, vary an input the record carries -- see the
+     * crash-reason token in `substrate-write.test.ts`.
+     *
+     * A test that triggers fire-and-forget work owes the next test the same
+     * courtesy: await that work's own completion record before returning, so
+     * it cannot straggle across the boundary in the first place.
+     */
+    waitForRecord(needle: string): Promise<CapturedLogRecord>;
+    /** As `waitForRecord`, restricted to records at the `error` level. */
+    waitForError(needle: string): Promise<CapturedLogRecord>;
+};
+export declare function createLogCapture(): LogCapture;