@intx/workflow-host 0.2.2 → 0.4.0

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;

package/dist/testing/memory-streams.js

@@ -0,0 +1,211 @@
+// In-memory stand-ins for the two IPC transports, for tests that drive a
+// supervisor or a workflow-process child without spawning one.
+//
+// Seventeen copies of these two factories accumulated across this package,
+// `apps/sidecar`, and the deploy tests, in nine variants apiece. The
+// divergences were almost entirely cosmetic, but the copies disagreed on one
+// thing that matters: whether `inject` appends the newline terminator that
+// delimits a wire frame.
+//
+// The two doubles answer that differently, because the two channels carry the
+// terminator differently. The event channel is byte-oriented and its
+// terminator is part of the payload, so `createMemoryFrameStream` separates
+// three roles and a caller says which one it means:
+//
+//   `writer`    what production writes through; bytes go in verbatim
+//   `inject`    one complete frame arriving on the wire, terminator supplied
+//   `injectRaw` bytes verbatim, for a deliberately malformed wire
+//
+// The control channel is line-oriented: one NDJSON line is one frame, and the
+// terminator is the line break the buffer does not store. So
+// `createMemoryNdjsonStream` has no third role -- `writer.write` and `inject`
+// are the same function -- and it strips one trailing newline, so a caller
+// that spells the terminator and one that omits it buffer the same line. A
+// malformed control frame is spelled as a malformed line, which `inject`
+// passes through unchanged apart from that newline, so there is no separate
+// raw role for a caller to reach for.
+//
+// A reader supports ONE `read()` iteration. Both channels are single-consumer
+// by construction -- the supervisor starts one pump per stream per child --
+// and the buffer is drained by whoever iterates, so a second iteration would
+// silently steal frames from the first. `read()` enforces that rather than
+// trusting it, because the way it gets violated is invisible: a spawner
+// double that hands the same streams to a respawned child re-reads them, and
+// the second iteration returns immediately off the closed stream instead of
+// receiving the new child's frames. The child then looks like it died on its
+// handshake, which is indistinguishable from the failure such a test is
+// usually written to examine.
+function announce(observers) {
+    const waiting = observers.list;
+    observers.list = [];
+    for (const observer of waiting)
+        observer();
+}
+/**
+ * Resolves on the next item to reach the buffer, from either direction.
+ *
+ * Edge-triggered: it does not see an item already buffered. A caller reads
+ * `flushed`, arms this, and re-checks in a loop, with the read and the arm in
+ * ONE synchronous block -- an `await` between them is what loses an item.
+ * Which of the two comes first inside that block decides nothing, because
+ * nothing can land between two synchronous statements. Both orders are in use
+ * here (`waitForUpstreamPayload` arms first, the park-notify waits in
+ * `apps/sidecar` read first) and both are safe for that reason.
+ */
+function nextWriteOf(observers) {
+    return new Promise((resolve) => {
+        observers.list.push(resolve);
+    });
+}
+export function createMemoryNdjsonStream() {
+    const buffer = [];
+    const observers = { list: [] };
+    const readObservers = { list: [] };
+    let reads = 0;
+    let waiter = null;
+    let done = false;
+    let reading = false;
+    function wake() {
+        const w = waiter;
+        waiter = null;
+        if (w)
+            w();
+    }
+    function push(line) {
+        buffer.push(line.replace(/\n$/, ""));
+        wake();
+        announce(observers);
+    }
+    const reader = {
+        read() {
+            if (reading) {
+                throw new Error("createMemoryNdjsonStream: a second read() on one stream; hand each spawn its own streams, as a real spawn does");
+            }
+            reading = true;
+            return (async function* () {
+                let handedOut = false;
+                for (;;) {
+                    if (handedOut) {
+                        // Counted here, on re-entry, rather than beside the `yield`. A
+                        // `for await` loop calls `next()` only after its body has run to
+                        // completion, so re-entry is the point at which the previous line
+                        // is finished with. Counting at the `yield` instead resolves a
+                        // waiter whose continuation is queued AHEAD of the consumer's, so
+                        // the one assertion the count exists for -- that a frame was
+                        // ignored -- would run before the consumer had looked at it.
+                        handedOut = false;
+                        reads += 1;
+                        announce(readObservers);
+                    }
+                    if (buffer.length > 0) {
+                        const next = buffer.shift();
+                        if (next === undefined) {
+                            throw new Error("buffer shift returned undefined");
+                        }
+                        handedOut = true;
+                        yield next;
+                        continue;
+                    }
+                    if (done)
+                        return;
+                    await new Promise((resolve) => {
+                        waiter = resolve;
+                    });
+                }
+            })();
+        },
+    };
+    return {
+        writer: { write: push },
+        reader,
+        inject: push,
+        flushed: () => buffer.slice(),
+        nextWrite: () => nextWriteOf(observers),
+        readCount: () => reads,
+        async awaitReadCount(count) {
+            for (;;) {
+                // Re-checked on every pass: level-triggered on the count, so a read
+                // that happened before this call resolves it. An edge wait on the next
+                // read deadlocks here, because the consumer usually reads an injected
+                // frame before a test can ask to be told about it.
+                const read = nextWriteOf(readObservers);
+                if (reads >= count)
+                    return;
+                await read;
+            }
+        },
+        close() {
+            done = true;
+            wake();
+            // A closed stream takes nothing further, so release anyone still
+            // watching rather than leaving them parked on a write that cannot come.
+            announce(observers);
+            announce(readObservers);
+        },
+    };
+}
+export function createMemoryFrameStream() {
+    const buffer = [];
+    const observers = { list: [] };
+    let waiter = null;
+    let done = false;
+    let reading = false;
+    function wake() {
+        const w = waiter;
+        waiter = null;
+        if (w)
+            w();
+    }
+    function pushRaw(bytes) {
+        buffer.push(bytes);
+        wake();
+        announce(observers);
+    }
+    const reader = {
+        read() {
+            if (reading) {
+                throw new Error("createMemoryFrameStream: a second read() on one stream; hand each spawn its own streams, as a real spawn does");
+            }
+            reading = true;
+            return (async function* () {
+                for (;;) {
+                    if (buffer.length > 0) {
+                        const next = buffer.shift();
+                        if (next === undefined) {
+                            throw new Error("frame buffer shift returned undefined");
+                        }
+                        yield next;
+                        continue;
+                    }
+                    if (done)
+                        return;
+                    await new Promise((resolve) => {
+                        waiter = resolve;
+                    });
+                }
+            })();
+        },
+    };
+    return {
+        writer: { write: pushRaw },
+        reader,
+        inject(bytes) {
+            // The event channel is newline-delimited: its sender terminates every
+            // frame, and the receiver splits on that terminator. A caller passing
+            // envelope bytes is describing one frame, so the terminator belongs
+            // here rather than at each call site.
+            const framed = new Uint8Array(bytes.length + 1);
+            framed.set(bytes, 0);
+            framed[bytes.length] = 0x0a;
+            pushRaw(framed);
+        },
+        injectRaw: pushRaw,
+        flushed: () => buffer.slice(),
+        nextWrite: () => nextWriteOf(observers),
+        close() {
+            done = true;
+            wake();
+            announce(observers);
+        },
+    };
+}

package/dist/testing/spawn-observer.d.ts

@@ -0,0 +1,12 @@
+export type SpawnObserver = {
+    /** Call from inside the spawner double with the env it received. */
+    record(env: Record<string, string>): void;
+    /**
+     * Resolve with the first recorded env, whether the spawn has happened yet
+     * or not. A respawn records again; this always resolves with the first.
+     */
+    first(): Promise<Record<string, string>>;
+    /** Every env recorded so far, in spawn order. */
+    all(): readonly Record<string, string>[];
+};
+export declare function createSpawnObserver(): SpawnObserver;

package/dist/testing/spawn-observer.js

@@ -0,0 +1,36 @@
+// Records the environment each spawn was invoked with, and lets a caller wait
+// for the first one.
+//
+// A test that needs the spawn-time env -- almost always to read the IPC
+// channel id and mint a child-side sender -- has to wait for the spawner to
+// be called. Twenty-two sites did that by assigning a mutable binding inside
+// the spawner and re-reading it on a one-millisecond timer until it stopped
+// being undefined. The spawner being called IS the event, so it is reported
+// rather than inferred.
+export function createSpawnObserver() {
+    const envs = [];
+    let waiters = [];
+    return {
+        record(env) {
+            envs.push(env);
+            const waiting = waiters;
+            waiters = [];
+            for (const waiter of waiting)
+                waiter();
+        },
+        async first() {
+            for (;;) {
+                // Re-read on every pass, so a spawn that happened before this call
+                // resolves it rather than leaving it waiting for another one.
+                const spawned = new Promise((resolve) => {
+                    waiters.push(resolve);
+                });
+                const head = envs[0];
+                if (head !== undefined)
+                    return head;
+                await spawned;
+            }
+        },
+        all: () => envs.slice(),
+    };
+}

package/dist/testing/stub-repo-store.d.ts

@@ -0,0 +1,10 @@
+import type { RepoStore } from "@intx/hub-sessions";
+export type StubRepoStoreOpts = {
+    /**
+     * Permit `writeTreePreservingPrefix`, returning a fixed commit and no
+     * newly-terminal runs. Off by default, so a test that does not ask for it
+     * fails on the call rather than accepting it.
+     */
+    writeTree?: boolean;
+};
+export declare function createStubRepoStore(baseDir: string, opts?: StubRepoStoreOpts): RepoStore;

package/dist/testing/stub-repo-store.js

@@ -0,0 +1,39 @@
+// A RepoStore that implements only what a test declares it needs, and throws
+// for everything else.
+//
+// The throw is the point. These stubs assert, by failing, that the code under
+// them touches nothing beyond the named surface -- so the narrow ones are not
+// an incomplete version of the broad ones, and substituting a working store
+// would silently permit paths that currently fail loudly.
+//
+// Only the two capability sets that were byte-identical across several files
+// live here. The rest of this repo's stub stores are genuinely different
+// fidelities, up to a 218-line in-memory implementation, and merging those
+// would trade a real assertion for a smaller diff.
+import path from "node:path";
+export function createStubRepoStore(baseDir, opts = {}) {
+    const stub = {
+        getRepoDir(repoId) {
+            return path.join(baseDir, repoId.kind, repoId.id);
+        },
+        ...(opts.writeTree === true
+            ? {
+                writeTreePreservingPrefix: async () => ({
+                    commitSha: "deadbeefcafef00d",
+                    newlyTerminalRuns: [],
+                }),
+            }
+            : {}),
+    };
+    // eslint-disable-next-line @typescript-eslint/no-unsafe-type-assertion -- test stub; every method the opts did not enable surfaces a precise failure via the proxy
+    return new Proxy(stub, {
+        get(target, prop, receiver) {
+            const value = Reflect.get(target, prop, receiver);
+            if (value !== undefined)
+                return value;
+            return () => {
+                throw new Error(`stub RepoStore: ${String(prop)} not implemented for this test`);
+            };
+        },
+    });
+}

package/dist/testing/supervisor-reaper.d.ts

@@ -0,0 +1,24 @@
+/** The part of a supervisor a reaper needs. */
+export type ReapableSupervisor = {
+    shutdown(): Promise<void>;
+};
+export type SupervisorReaper = {
+    /** Register a supervisor and return it, for use at the construction site. */
+    track<T extends ReapableSupervisor>(supervisor: T): T;
+    /**
+     * Shut down every supervisor registered since the last call. Pass straight
+     * to `afterEach`.
+     *
+     * The teardowns overlap: every `shutdown()` is called before any is awaited,
+     * so they settle in whatever order they finish rather than registration
+     * order. Nothing here sequences one supervisor's teardown after another's.
+     *
+     * `shutdown` early-returns once the phase is terminal. That guard does not
+     * cover `stopping`, so a teardown already in flight is re-entered here --
+     * harmlessly, because every branch of the teardown is guarded on the prior
+     * phase and a second pass through `stopping` does no work. Either way the
+     * tests that tear themselves down are unaffected.
+     */
+    reap(): Promise<void>;
+};
+export declare function createSupervisorReaper(): SupervisorReaper;

package/dist/testing/supervisor-reaper.js

@@ -0,0 +1,49 @@
+// Per-file registry of the supervisors a test built, so a lifecycle hook can
+// tear them down whatever way the test ended.
+//
+// A supervisor is normally torn down by a `shutdown()` at the end of the test
+// that built it, which an earlier failed assertion skips -- and some tests
+// never had one. What that abandons is not inert: a dispatch suspended in
+// `waitForRunTerminalOrPark` holds that function's armed five-minute
+// backstop, whose clearing `finally` cannot run while the race it guards is
+// pending. Aborting the cohort is what settles that race, so reaping is what
+// disarms the timer. The unit pass shares a module registry per worker, so an
+// un-reaped supervisor outlives its file and any failure it causes is charged
+// to an unrelated test.
+//
+// The registry is per-call rather than module-level: two test files importing
+// one shared array would reap each other's supervisors if their lifecycles
+// ever overlapped.
+export function createSupervisorReaper() {
+    const live = [];
+    return {
+        track(supervisor) {
+            live.push(supervisor);
+            return supervisor;
+        },
+        async reap() {
+            // Every `shutdown()` is CALLED before any of them is awaited, so no
+            // supervisor's teardown waits on its neighbours': one that REJECTS and
+            // one that never SETTLES both leave the rest to run to completion.
+            // Awaiting them one at a time would not -- a teardown that never
+            // settled would mean the supervisors behind it never started theirs,
+            // each keeping its child and its armed backstop.
+            //
+            // A non-settling `shutdown()` still blocks this function's own
+            // resolution, because `allSettled` waits for that one too -- so the
+            // `afterEach` calling it does not complete, and the lane timeout is what
+            // fails the file. Abandoning the pending one would take a deadline,
+            // which "Synchronizing on State, Not Time" in CONVENTIONS.md rules out,
+            // and `shutdown()` offers no other signal to race. What this covers is
+            // the leak, not the hang.
+            //
+            // `shutdown` is documented as total, so a throw is a defect and fails
+            // the test rather than landing in a log nobody reads.
+            const settled = await Promise.allSettled(live.splice(0).map((supervisor) => supervisor.shutdown()));
+            const failures = settled.flatMap((result) => result.status === "rejected" ? [result.reason] : []);
+            if (failures.length > 0) {
+                throw new AggregateError(failures, "supervisor teardown threw");
+            }
+        },
+    };
+}