@intx/workflow-host 0.3.0 → 0.4.0

package/dist/supervisor/terminal-commit.js

@@ -17,12 +17,12 @@
 // 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";
-const EVENT_FILENAME_RE = /^(0|[1-9][0-9]*)\.json$/;
 /**
  * Terminal run-event kinds, mirroring the runtime's terminal vocabulary
  * (`RunCompleted`/`RunFailed`/`RunCancelled`). Inlined because the workflow
@@ -72,13 +72,9 @@ export async function commitRunFailed(opts) {
             let maxPath = null;
             for (const filepath of existing.keys()) {
                 const name = filepath.slice(prefix.length);
-                const match = EVENT_FILENAME_RE.exec(name);
-                if (match === null)
+                const seq = parseEventSeq(name);
+                if (seq === null)
                     continue;
-                const seqStr = match[1];
-                if (seqStr === undefined)
-                    continue;
-                const seq = Number.parseInt(seqStr, 10);
                 if (seq > maxSeq) {
                     maxSeq = seq;
                     maxPath = filepath;

package/dist/supervisor/types.d.ts

@@ -244,6 +244,36 @@ export interface WorkflowSupervisorBindings {
      * 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-

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;

package/dist/testing/log-capture.js

@@ -0,0 +1,124 @@
+// Capture LogTape records for one test file, so a test can await a log line
+// instead of polling for it.
+//
+// Some decisions announce themselves only in the log. A guard that returns
+// without touching any observable state leaves the record as the sole
+// evidence it ran, and a test that wants to assert on such a decision has no
+// other signal to await. Waiting on the record is what "Synchronizing on
+// State, Not Time" in CONVENTIONS.md asks for, and it replaces a poll whose
+// deadline had to be guessed against whatever the code under test was
+// waiting on.
+//
+// The capture is per-call, not module-level. The unit pass gives a worker one
+// module registry for every file it runs, so a module-level record array
+// would accumulate another file's records and a module-level waiter list
+// would let another file's log line resolve this file's wait.
+// `createChangeNotifier` and `createSupervisorReaper` are factories for the
+// same reason.
+//
+// `configureSync` is process-global, so `install` saves the configuration it
+// replaces and `restore` puts it back. Wire the three lifecycle methods to
+// `beforeAll`, `afterAll`, and `beforeEach`.
+import { configureSync, getConfig } from "@intx/log";
+export function createLogCapture() {
+    const captured = [];
+    // Tests awaiting a record that has not been logged yet. The sink resolves
+    // these as each record lands.
+    const waiters = [];
+    // Non-null exactly while this capture is installed, so it doubles as the
+    // installed flag.
+    let savedConfig = null;
+    function matches(record, needle, level) {
+        if (level !== null && level !== record.level)
+            return false;
+        return record.message.includes(needle);
+    }
+    function waitFor(needle, level) {
+        const already = captured.find((record) => matches(record, needle, level));
+        if (already !== undefined)
+            return Promise.resolve(already);
+        return new Promise((resolve, reject) => {
+            waiters.push({
+                needle,
+                level,
+                resolve,
+                abandon: () => {
+                    const what = level === null ? "record" : `${level} record`;
+                    reject(new Error(`no ${what} matching ${needle} arrived before teardown`));
+                },
+            });
+        });
+    }
+    return {
+        install() {
+            if (savedConfig !== null) {
+                throw new Error("this log capture is already installed");
+            }
+            const prior = getConfig();
+            // A null configuration means this file loaded without `@intx/log`
+            // having installed its default sink, which cannot happen -- importing
+            // the package runs the install. Failing here rather than at `restore`
+            // keeps the worker from running a whole suite it cannot unwind: there
+            // would be nothing to put back, and the install cannot re-fire to
+            // repair it.
+            if (prior === null) {
+                throw new Error("no logging configuration was present for the capture to replace");
+            }
+            savedConfig = prior;
+            configureSync({
+                reset: true,
+                sinks: {
+                    capture: (record) => {
+                        const message = record.message
+                            .map((part) => typeof part === "string" ? part : JSON.stringify(part))
+                            .join("");
+                        const entry = {
+                            category: record.category,
+                            level: record.level,
+                            message,
+                        };
+                        captured.push(entry);
+                        // Hand the record to anyone waiting for it. Take only the
+                        // matching waiters, leaving the rest armed for their own needles.
+                        for (const waiter of waiters.splice(0)) {
+                            if (matches(entry, waiter.needle, waiter.level)) {
+                                waiter.resolve(entry);
+                            }
+                            else {
+                                waiters.push(waiter);
+                            }
+                        }
+                    },
+                },
+                loggers: [
+                    { category: [], lowestLevel: "debug", sinks: ["capture"] },
+                    {
+                        category: ["logtape", "meta"],
+                        lowestLevel: "warning",
+                        sinks: ["capture"],
+                    },
+                ],
+            });
+        },
+        restore() {
+            const prior = savedConfig;
+            if (prior === null) {
+                throw new Error("this log capture was restored without being installed");
+            }
+            savedConfig = null;
+            configureSync({ reset: true, ...prior });
+        },
+        reset() {
+            captured.length = 0;
+            // Reject rather than drop: a waiter outstanding from a previous test
+            // (its test was killed mid-wait) would otherwise be discarded still
+            // armed, and its promise could never settle.
+            for (const waiter of waiters.splice(0))
+                waiter.abandon();
+        },
+        records: () => captured.slice(),
+        errors: () => captured.filter((r) => r.level === "error").map((r) => r.message),
+        waitForRecord: (needle) => waitFor(needle, null),
+        waitForError: (needle) => waitFor(needle, "error"),
+    };
+}

package/dist/testing/mail-bus.d.ts

@@ -0,0 +1,22 @@
+import type { MailBusBindings } from "../supervisor/types.js";
+export type MockMailBus = MailBusBindings & {
+    /** Addresses currently registered, in registration order. */
+    registered(): readonly string[];
+    /**
+     * Every registration and unregistration in order, as `register:<address>`
+     * and `unregister:<address>`. Distinguishes "never registered" from
+     * "registered and then released", which `registered()` cannot.
+     */
+    registrationHistory(): readonly string[];
+    /** Deliver a raw message to every handler subscribed for `address`. */
+    deliver(address: string, message: Uint8Array): void;
+    /**
+     * Resolve once `address` is registered, whether it already is or is
+     * registered later.
+     *
+     * The registration is the event a test waiting for a deployment to come up
+     * actually wants; polling `registered()` on a timer was standing in for it.
+     */
+    awaitRegistered(address: string): Promise<void>;
+};
+export declare function createMockMailBus(): MockMailBus;

package/dist/testing/mail-bus.js

@@ -0,0 +1,78 @@
+// In-memory MailBusBindings, for supervisor tests that need mail delivered to
+// a deployment address without a real bus.
+//
+// Seven copies of this had accumulated in five variants. Beyond cosmetics
+// they differed in what they let a test observe: one kept a register/
+// unregister history, one kept only the current set. Both observables are
+// here, because a test asking "is it registered now" and one asking "was it
+// ever unregistered" are asking different questions and the second cannot be
+// answered from the first.
+export function createMockMailBus() {
+    const registered = [];
+    const history = [];
+    const subscribers = new Map();
+    let waiters = [];
+    function announce() {
+        const waiting = waiters;
+        waiters = [];
+        for (const waiter of waiting)
+            waiter();
+    }
+    return {
+        registerAddress(address) {
+            registered.push(address);
+            history.push(`register:${address}`);
+            announce();
+        },
+        unregisterAddress(address) {
+            const idx = registered.lastIndexOf(address);
+            if (idx >= 0)
+                registered.splice(idx, 1);
+            subscribers.delete(address);
+            history.push(`unregister:${address}`);
+            // Every mutation of the registration set is announced, which is what
+            // makes an arbitrary predicate over that set awaitable: a waiter re-reads
+            // on any change rather than on the subset of changes someone remembered
+            // to report. `awaitRegistered` is the only waiter today, and an
+            // unregister can only falsify its predicate, so this wake settles nothing
+            // for it -- a fact about that one predicate, not a gap in the reporting.
+            announce();
+        },
+        subscribeMailForAddress(address, handler) {
+            let set = subscribers.get(address);
+            if (set === undefined) {
+                set = new Set();
+                subscribers.set(address, set);
+            }
+            set.add(handler);
+            return () => {
+                const current = subscribers.get(address);
+                current?.delete(handler);
+            };
+        },
+        sendOutbound() {
+            throw new Error("sendOutbound not exercised in this test");
+        },
+        registered: () => registered.slice(),
+        registrationHistory: () => history.slice(),
+        deliver(address, message) {
+            const set = subscribers.get(address);
+            if (set === undefined)
+                return;
+            for (const handler of set)
+                void handler(message).catch(() => undefined);
+        },
+        async awaitRegistered(address) {
+            for (;;) {
+                // Re-read on every pass, so an address registered before this call
+                // resolves it rather than leaving it waiting for a re-registration.
+                const changed = new Promise((resolve) => {
+                    waiters.push(resolve);
+                });
+                if (registered.includes(address))
+                    return;
+                await changed;
+            }
+        },
+    };
+}

package/dist/testing/memory-streams.d.ts

@@ -0,0 +1,43 @@
+import type { NdjsonReader, NdjsonWriter } from "../ipc/control-channel.js";
+import type { FrameReader, FrameWriter } from "../ipc/event-channel.js";
+export type MemoryNdjsonStream = {
+    writer: NdjsonWriter;
+    reader: NdjsonReader;
+    inject(line: string): void;
+    flushed(): readonly string[];
+    nextWrite(): Promise<void>;
+    /** How many lines the consumer has taken off the buffer and finished with. */
+    readCount(): number;
+    /**
+     * Resolves once the consumer has finished with at least `count` lines.
+     *
+     * The write report says a line arrived; this says the pump reading the
+     * stream is done with it. A test that injects a frame the consumer is
+     * supposed to IGNORE needs the second one: without it, the assertion that
+     * nothing happened can run before the consumer has even looked.
+     *
+     * "Finished with" is the consumer asking for the next line, which a
+     * `for await` loop does only after its body returns -- so the guarantee is
+     * exactly as strong as the loop body is. A body that dispatches work with
+     * `void` and returns has finished in this sense while its handler is still
+     * in flight, and a consumer that stops iterating never asks again, so its
+     * last line stays uncounted.
+     *
+     * Level-triggered on a count rather than edge-triggered on the next read,
+     * so a caller that arms it after the read already happened is not left
+     * waiting for another one.
+     */
+    awaitReadCount(count: number): Promise<void>;
+    close(): void;
+};
+export declare function createMemoryNdjsonStream(): MemoryNdjsonStream;
+export type MemoryFrameStream = {
+    writer: FrameWriter;
+    reader: FrameReader;
+    inject(bytes: Uint8Array): void;
+    injectRaw(bytes: Uint8Array): void;
+    flushed(): readonly Uint8Array[];
+    nextWrite(): Promise<void>;
+    close(): void;
+};
+export declare function createMemoryFrameStream(): MemoryFrameStream;