omkit 0.0.15 → 0.1.1

package/dist/orchestration/spin/SpinHost.js

@@ -1,345 +0,0 @@
-import { relative } from "node:path";
-import { producerOfRef } from "../action/action.js";
-import { LogsCollector, ScopedLogger } from "../../output/log/LogsCollector.js";
-import { LogRenderer } from "../../output/log/LogRenderer.js";
-import { actionScope, captureConsole } from "../../output/log/console-capture.js";
-import { Output } from "../../output/Output.js";
-import { createAssert } from "../assert.js";
-/** The entry script, relative to where node was invoked (so the log says what produced it). */
-const scriptPath = () => {
-    const entry = process.argv[1];
-    return entry ? relative(process.cwd(), entry) : "(unknown)";
-};
-/** A constructed instance is an object carrying a `start` function. */
-const isActionInstance = (value) => typeof value === "object" &&
-    value !== null &&
-    typeof value.start === "function";
-/** An *uncalled* action: the callable `action(name).run(…)` returns before it's invoked. */
-const isUncalledAction = (value) => typeof value === "function" && typeof value.actionName === "string";
-/**
- * Guard each launch argument: an action *instance* is required, not the action
- * itself. Forgetting the trailing `()` is an easy slip (the callable has no
- * `.start`), and silently treating it as something else would report a false
- * green — so fail loudly with the fix.
- */
-function assertInstance(value) {
-    if (isActionInstance(value))
-        return;
-    const hint = isUncalledAction(value)
-        ? ` — that looks like an action that wasn't invoked; construct an instance by calling it: action("…").run(…)()`
-        : "";
-    throw new Error(`run() expects action instances; received ${typeof value}${hint}`);
-}
-/**
- * A live spin over its own append-only log: constructing one launches the given
- * actions in parallel under a single abort controller and drives them to a terminal
- * {@link SpinResult}. Stop it with `.cancel()`, `await` its `.done` for the verdict.
- *
- * **A spin owns its world.** Each construction creates its *own* {@link LogsCollector}
- * and {@link Output} — the run's log, folder, and snapshots — rather than sharing a
- * process global, so runs don't bleed into each other and a fresh run can be created
- * in a living process (sequential re-runs, in-process tests). Attach further actions
- * to a running spin — including event-driven ones — via its `.run(…)` method.
- *
- * Each action runs against its own child logger (which headers and indents its
- * lines into this run's log) and the spin's shared abort signal — both injected
- * into its context, where the framework also binds a `proc` and the run's `output`
- * so child processes stream into the right log and die on teardown. A **failing
- * action never tears the spin down** — its `{ ok: false }` outcome is recorded in
- * the verdict (and sets exit code 1) and the spin keeps running. Teardown to
- * `closed` happens only on Ctrl-C, `.cancel()`, natural completion, or an uncaught
- * fatal. The process-level hooks (SIGINT/uncaught handlers, `exitCode`) are owned by
- * the run and cleaned at finalize, so they don't outlive it.
- */
-export class SpinHost {
-    /** This run's append-only log — its own store, not a process global. */
-    logs = new LogsCollector();
-    /** This run's output subsystem (folder + snapshots + run-log writer), wired to {@link logs}. */
-    output = new Output(this.logs);
-    /** The spin's abort signal — for consumers that want to observe teardown. */
-    signal;
-    /** Settles once the spin reaches `closed`, carrying the terminal verdict. Never rejects. */
-    done;
-    /** The original `console.log`, captured before patching — the run's terminal writer. */
-    term;
-    /** Reinstalls the pre-run console methods; called once at finalize. */
-    restoreConsole;
-    controller = new AbortController();
-    // ── Lifecycle state ──────────────────────────────────────────────────────
-    // The single source of truth for "where in its life is this run". Only
-    // `beginClosing` and the finalize step below mutate it, and only forward.
-    // The log stays open through teardown and is closed once at finalize (after the
-    // last entry), so `streamLog` captures the whole run — including lines logged
-    // *during* teardown — and its run.jsonl is complete before `writeLog` reads it.
-    phase = "open";
-    /** The current lifecycle state — see {@link SpinState}. */
-    get state() {
-        return this.phase;
-    }
-    // Genuine failures (not teardown cascade). Frozen into the verdict at close.
-    failures = [];
-    // Running tally of every assertion this run made, for the run.log summary footer.
-    assertionsPassed = 0;
-    assertionsFailed = 0;
-    // Every launched action's promise lives here until it settles; the drive loop
-    // empties this set. Daemons keep it non-empty until the controller aborts.
-    inFlight = new Set();
-    // Instances launched so far — used to verify a `.ref` dependency was launched
-    // before the action that consumes its handle.
-    launched = new WeakSet();
-    // The incremental crash-insurance stream; awaited at finalize before writeLog.
-    streaming;
-    // Ctrl-C tears the spin down gracefully through the lifecycle, like cancel().
-    onSigint = () => this.beginClosing("interrupted (SIGINT)");
-    onUncaught = this.onFatal("uncaughtException");
-    onUnhandled = this.onFatal("unhandledRejection");
-    constructor(...actions) {
-        // Validate eagerly so a bad argument throws cleanly before any work begins.
-        for (const instance of actions)
-            assertInstance(instance);
-        this.signal = this.controller.signal;
-        // Capture the ORIGINAL console.log as this run's terminal writer BEFORE patching,
-        // or `drain`/finalize would re-enter the patched method and feedback-loop. Then
-        // patch console so every console.* during the run folds into this run's log,
-        // attributed via `actionScope` (see `launch`).
-        this.term = console.log.bind(console);
-        this.restoreConsole = captureConsole(this.logs);
-        process.once("SIGINT", this.onSigint);
-        process.on("uncaughtException", this.onUncaught);
-        process.on("unhandledRejection", this.onUnhandled);
-        this.narrate(`run started · ${scriptPath()}`);
-        // Start streaming log entries to disk immediately — incremental writes survive
-        // hard kills where the final writeLog never runs. Kept so finalize can await it
-        // *before* writeLog rewrites the same files: otherwise a late flush from this
-        // stream lands past writeLog's truncation and the OS zero-fills the gap (a
-        // multi-MB NUL run in run.log).
-        this.streaming = this.output.runLog.stream(this.logs).catch(() => { });
-        // Live-render the log to the console for the whole run (replay + live). Always
-        // on — the run's terminal output, no flag or call required.
-        this.drain();
-        for (const instance of actions)
-            this.launch(instance, undefined);
-        // Launch before driving: the drive loop breaks on an empty `inFlight`, so it
-        // must not start until the initial actions have populated it.
-        this.done = this.drive();
-        // `done` resolves with the verdict and never rejects; guard anyway so a stray
-        // finalize error can't surface as an unhandled rejection.
-        this.done.catch(() => { });
-    }
-    /**
-     * Launch more actions into this same spin — same controller, same log. Chainable.
-     *
-     * Throws if the spin is no longer `open`.
-     */
-    run(...more) {
-        for (const instance of more)
-            this.nodInto(instance, undefined);
-        return this;
-    }
-    /**
-     * Launch `instance` into the spin under an optional `parentPath` (the nodding
-     * action's path, or `undefined` for a top-level nod). The single guarded entry to
-     * launching — `run` (top-level) and an action's own scoped `nod` both route here,
-     * so the "spin is open" check lives in one place.
-     */
-    nodInto(instance, parentPath) {
-        if (this.phase !== "open") {
-            throw new Error(`spin.run(…) rejected: the spin is "${this.phase}", not "open". Launch actions before ` +
-                `teardown, or from a lifecycle event of an action that is still running.`);
-        }
-        this.launch(instance, parentPath);
-    }
-    /** Begin teardown: abort the signal (killing procs, unblocking waits, stopping daemons). */
-    cancel() {
-        this.beginClosing("cancelled");
-    }
-    /**
-     * Live-render the log to the console. Started automatically from the constructor
-     * — every spin drains, with no flag to disable and nothing for the caller to
-     * invoke (for now). A single {@link LogRenderer} applies grouping/indentation as
-     * entries stream by; its state spans the replayed history and live entries as one
-     * continuous stream. The subscription ends itself when the run tears down (the
-     * collector closes it), so this loop simply runs to completion.
-     */
-    drain() {
-        void (async () => {
-            const renderer = new LogRenderer();
-            for await (const entry of this.logs.subscribe({ replay: true }))
-                this.term(renderer.render(entry));
-        })().catch(() => { });
-    }
-    /** Narrate a run-lifecycle milestone into this run's log (renders as a `[run]` line). */
-    narrate(message) {
-        this.logs.append({ source: "run", level: "run", message });
-    }
-    /**
-     * Move `open → closing`: abort the signal (unwinding procs, waits, and
-     * daemons), narrate the cause once, and stop accepting new actions. Idempotent
-     * — only the first caller transitions; later triggers (a second failure, a
-     * `cancel()` during teardown) are no-ops. This is the *only* path to abort, so
-     * every teardown reason flows through one place.
-     */
-    beginClosing(reason) {
-        if (this.phase !== "open")
-            return;
-        this.phase = "closing";
-        this.narrate(`tearing down · ${reason}`);
-        this.controller.abort();
-    }
-    /**
-     * Record a genuine fault in the verdict. It does **not** tear the spin down — a
-     * failing action is data, and the spin keeps running (only Ctrl-C / cancel /
-     * completion / an uncaught fatal close it).
-     */
-    recordFailure(action, error) {
-        this.failures.push({ action, error });
-    }
-    /**
-     * A throw or rejection that escaped every action's own handling. Without a
-     * handler Node prints it and exits *immediately* — before the run can flush its
-     * log, which leaves a silent, empty log directory and no verdict. So catch it,
-     * log it, fold it into the verdict, and drive teardown so the log still flushes
-     * and the exit code reflects the fault — degrading a stray throw to a recorded
-     * failure instead of a hard crash. Removed at finalize, so it only governs
-     * while this run owns the process.
-     */
-    onFatal(kind) {
-        return (error) => {
-            this.logs.append({
-                source: kind,
-                level: "error",
-                message: error instanceof Error ? (error.stack ?? error.message) : String(error),
-            });
-            // Genuine fault vs. teardown fallout: only one that surfaces *before* the
-            // signal aborts is the spin's own (mirrors `launch`'s cascade rule); a throw
-            // during unwind is logged but doesn't pollute the verdict. Either way tear
-            // down — unlike an action's own failure, an *uncaught* fatal leaves the
-            // process state undefined, so we always finish and flush.
-            if (!this.controller.signal.aborted)
-                this.failures.push({ action: kind, error });
-            this.beginClosing(kind);
-        };
-    }
-    launch(instance, parentPath) {
-        // A consumer built with another action's `.ref` (e.g. `chromePage("Explorer", driver.ref)`)
-        // must be launched *after* that producer — otherwise it awaits a handle that
-        // never arrives and the spin hangs silently. Catch it and say how to fix it.
-        for (const arg of instance.args) {
-            const producer = producerOfRef(arg);
-            if (producer && !this.launched.has(producer)) {
-                throw new Error(`${instance.name} was launched before its dependency ${producer.name}: it ` +
-                    `consumes ${producer.name}'s .ref, so nod ${producer.name} first.`);
-            }
-        }
-        this.launched.add(instance);
-        // The action's path: its name for a top-level nod, or `<parent> › <name>` when a
-        // parent action nodded it. Top-level actions keep this run's logger (output
-        // unchanged); a child gets a ScopedLogger so its every line — and its `proc`'s,
-        // and any grandchildren's — is prefixed with this path. Its own `nod` carries
-        // this path down, so scoping composes automatically.
-        const path = parentPath ? `${parentPath} › ${instance.name}` : instance.name;
-        const scoped = parentPath === undefined ? this.logs : new ScopedLogger(this.logs, path);
-        const nod = (child) => {
-            this.nodInto(child, path);
-            return child;
-        };
-        // A boolean check bound to this action's path: it logs a `⊨` milestone, tallies
-        // the result for the run.log summary, and on failure records a verdict failure
-        // the same way an action's own failure does — skipped during teardown (cascade,
-        // not a fault). Uses `this.logs` (not `scoped`) the same way `record` below does:
-        // the path is already embedded in the message via `name`, so routing through
-        // `scoped` would double-prefix the `source` field for a nodded child.
-        const assert = createAssert(path, this.logs, (pass, error) => {
-            if (pass)
-                this.assertionsPassed++;
-            else {
-                this.assertionsFailed++;
-                if (!this.controller.signal.aborted && error)
-                    this.recordFailure(path, error);
-            }
-        });
-        this.narrate(`launch ${path}`);
-        // The action logs into this run's shared store (entries carry their `source`;
-        // grouping is applied at render time) and gets the spin's signal directly; the
-        // framework injects a `proc` and the run's `output` bound to both, so there's no
-        // ambient context. `start()` resolves with the action's Outcome — it never
-        // rejects for the action's own failure — so a failure is handled here as data.
-        const record = (error) => {
-            // Always record the fault in the action's own log, under its path.
-            this.logs.append({
-                source: path,
-                level: "error",
-                message: error instanceof Error ? (error.stack ?? error.message) : String(error),
-            });
-            // Genuine failure vs. teardown fallout: if the signal was already aborted
-            // when this surfaced, the failure is almost certainly the abort killing the
-            // action (a cascade), not its own fault — so it must not pollute the verdict.
-            if (!this.controller.signal.aborted)
-                this.recordFailure(path, error);
-        };
-        const promise = actionScope
-            .run(path, () => instance.start({
-            logs: scoped,
-            signal: this.controller.signal,
-            nod,
-            output: this.output,
-            assert,
-        }))
-            .then((outcome) => {
-            if (!outcome.ok)
-                record(outcome.error);
-        })
-            // Defensive: `start()` shouldn't reject, but if the framework itself throws,
-            // treat it as a fault rather than losing it to an unhandled rejection.
-            .catch(record);
-        this.inFlight.add(promise);
-        void promise.finally(() => this.inFlight.delete(promise));
-    }
-    /**
-     * Drives the run to `closed`. The loop re-checks `inFlight` because actions can
-     * be added (or daemons can settle on abort) while we await. A synchronous
-     * `.run(…)` from a settling action's lifecycle event lands before that action's
-     * `finally` removes it, so `inFlight` never spuriously hits 0 mid-handoff.
-     */
-    async drive() {
-        for (;;) {
-            if (this.inFlight.size === 0) {
-                // Nothing left to run. If still open, every action finished on its own —
-                // natural completion; tear down so daemons/listeners unwind uniformly.
-                // If already closing, teardown is simply complete.
-                if (this.phase === "open")
-                    this.beginClosing("completed");
-                break;
-            }
-            await Promise.allSettled([...this.inFlight]);
-        }
-        // ── Finalize (reached exactly once) ──────────────────────────────────────
-        this.phase = "closed";
-        process.off("SIGINT", this.onSigint);
-        process.off("uncaughtException", this.onUncaught);
-        process.off("unhandledRejection", this.onUnhandled);
-        this.restoreConsole();
-        this.narrate("finished");
-        // Close the log now (after the last entry) so `streamLog` drains and finishes
-        // writing the complete run.jsonl, then wait for it to fully close its files —
-        // both so its last flush can't corrupt run.log later, and so run.jsonl is done
-        // before `writeLog` streams it into the final collapsed run.log.
-        this.logs.close();
-        await this.streaming;
-        // Hand the assertion tally to `write`, which bubbles a summary + the
-        // `assertions.log` link into the run.log footer (only when there were any).
-        const file = await this.output.runLog.write({
-            passed: this.assertionsPassed,
-            failed: this.assertionsFailed,
-        });
-        // Direct to the terminal — the file's already written, so this line isn't in it.
-        this.term(LogRenderer.marker("run", `log → ${file}`));
-        const result = { ok: this.failures.length === 0, failures: this.failures };
-        // One process = one run = one verdict; reflect pass/fail in the exit code so
-        // shells and CI see it without parsing the log. Only set it on failure, so a
-        // code a failing action's own handler may have set isn't clobbered to 0.
-        if (!result.ok)
-            process.exitCode = 1;
-        return result;
-    }
-}

package/dist/orchestration/spin/spin.d.ts

@@ -1,24 +0,0 @@
-import type { SpinBody } from "./types.ts";
-/**
- * Runs a linear orchestration. You pass a plain (async) function; omkit hosts it
- * in a single in-flight action and hands it a {@link Nod}. Because that host
- * stays in-flight while your body `await`s, the spin never idles shut between
- * steps — so you write `await` / `if` control flow instead of nested callbacks.
- * When the body returns, the daemons it nodded in keep the spin alive until
- * teardown.
- *
- * A failing action **never throws into the body** — `await nod(x).done` yields an
- * {@link import("./action.ts").Outcome} you inspect, and the spin keeps going
- * (the failure is recorded in the verdict and sets exit code 1):
- *
- *   spin({ drain: false }, async ({ nod }) => {
- *     const ans = await nod(prompt({ … })).done;       // Outcome — never throws
- *     if (ans.ok && ans.value === "yes") await nod(test).done;
- *     nod(devServer);                                   // fire-and-forget daemon
- *     const chrome = nod(chromedriver({ … }));
- *     nod(chromePage("Explorer", chrome.ref));          // data deps via .ref
- *   });
- *
- * Auto-drains by default;
- */
-export declare function spin(body: SpinBody): void;

package/dist/orchestration/spin/spin.js

@@ -1,57 +0,0 @@
-import { action } from "../action/action.js";
-import { SpinHost } from "./SpinHost.js";
-/**
- * Runs a linear orchestration. You pass a plain (async) function; omkit hosts it
- * in a single in-flight action and hands it a {@link Nod}. Because that host
- * stays in-flight while your body `await`s, the spin never idles shut between
- * steps — so you write `await` / `if` control flow instead of nested callbacks.
- * When the body returns, the daemons it nodded in keep the spin alive until
- * teardown.
- *
- * A failing action **never throws into the body** — `await nod(x).done` yields an
- * {@link import("./action.ts").Outcome} you inspect, and the spin keeps going
- * (the failure is recorded in the verdict and sets exit code 1):
- *
- *   spin({ drain: false }, async ({ nod }) => {
- *     const ans = await nod(prompt({ … })).done;       // Outcome — never throws
- *     if (ans.ok && ans.value === "yes") await nod(test).done;
- *     nod(devServer);                                   // fire-and-forget daemon
- *     const chrome = nod(chromedriver({ … }));
- *     nod(chromePage("Explorer", chrome.ref));          // data deps via .ref
- *   });
- *
- * Auto-drains by default;
- */
-export function spin(body) {
-    // `run(...)` below assigns `host` synchronously, before the action's async body
-    // ever runs — so the closures here capture the spin safely.
-    let hostRun;
-    const hostAction = action("omkit:Spin").run(async (ctx) => {
-        const nod = (instance) => {
-            hostRun.run(instance);
-            return instance;
-        };
-        await body({
-            nod,
-            // TODO: maybe add a reason for cancel ???
-            cancel: () => hostRun.cancel(),
-            signal: ctx.signal,
-            // The host action runs inside the SpinHost, so its ctx already carries the
-            // run's output subsystem — surface the folder and a snapshot convenience to
-            // the body from there rather than reaching for a module singleton.
-            artifactsFolder: ctx.artifactsFolder,
-            snapshot: (name, value) => ctx.output.snapshots.snapshot(name, value),
-            assert: ctx.assert,
-        });
-    });
-    const mainSpinAction = hostAction();
-    hostRun = new SpinHost(mainSpinAction);
-    // The body is the orchestrator, not a peer action: if it throws, tear the whole
-    // spin down. Regular action failures only get recorded (they don't stop the
-    // spin), but the orchestrator crashing must end the run — otherwise any daemon
-    // it already nodded keeps the process alive forever on a pipeline bug.
-    void mainSpinAction.done.then((outcome) => {
-        if (!outcome.ok)
-            hostRun.cancel();
-    });
-}

package/dist/orchestration/spin/types.d.ts

@@ -1,63 +0,0 @@
-export type { Nod } from "../action/types.ts";
-import type { Nod } from "../action/types.ts";
-import type { Assert } from "../assert.ts";
-/** What a {@link spin} body receives. */
-export interface SpinContext {
-    /** Launch an action into the spin; returns the instance for awaiting/chaining. */
-    readonly nod: Nod;
-    /**
-     * Tear the spin down (abort the signal, stopping daemons). Use it to end a spin
-     * whose work is finished but which is held open by a daemon — e.g. once a
-     * one-shot build completes while a watcher is still running.
-     */
-    readonly cancel: () => void;
-    /** The spin's abort signal — honor it to stop early. */
-    readonly signal: AbortSignal;
-    /**
-     * Absolute path to this spin's output folder (`logs/<name>/<date>/<time>/`),
-     * created up front. Hand it to actions (or use `ctx.artifactsFolder` inside
-     * one) to write artifacts beside `run.log`.
-     */
-    readonly artifactsFolder: string;
-    /**
-     * Capture a JSON snapshot into this run's output folder and drop a `[snapshot]`
-     * line on the timeline — for run-level inputs the log should narrate (a build
-     * config, resolved options). Resolves with the snapshot's relative path. The
-     * run-scoped counterpart to the action `ctx.output.snapshots`.
-     */
-    readonly snapshot: (name: string, value: unknown) => Promise<string>;
-    /**
-     * Assert a boolean invariant from the spin body. Same semantics as the action
-     * `ctx.assert`; body assertions are attributed to the host action path
-     * (`omkit:Spin`).
-     */
-    readonly assert: Assert;
-}
-/** The body of a {@link spin}: any (async) function — it isn't named or wrapped by you. */
-export type SpinBody = (ctx: SpinContext) => void | Promise<void>;
-/**
- * A single action's failure, captured for the spin's verdict. Cascade failures —
- * actions that settled `{ ok: false }` only because teardown aborted them — are
- * deliberately excluded (see `launch`'s outcome handling), so this records
- * genuine faults, not fallout.
- */
-export interface ActionFailure {
-    /** The failing action's name. */
-    readonly action: string;
-    /** Whatever it failed with (the Outcome's `error`). */
-    readonly error: unknown;
-}
-/**
- * The terminal verdict of a spin: did everything that mattered succeed, and if
- * not, what failed. {@link SpinHost.done} resolves (never rejects) with this, so a
- * single `await` yields the outcome instead of forcing a try/catch on awaiters.
- * A failing action is *recorded* here (so `ok` is false and the exit code is 1)
- * but does **not** tear the spin down — see {@link SpinHost}.
- */
-export interface SpinResult {
-    /** True when no genuine failure was recorded. */
-    readonly ok: boolean;
-    /** The genuine failures, in the order they surfaced. Empty when `ok`. */
-    readonly failures: readonly ActionFailure[];
-}
-export type SpinState = "open" | "closing" | "closed";

package/dist/output/Output.d.ts

@@ -1,24 +0,0 @@
-import type { Logger } from "./log/LogsCollector.ts";
-import { RunFolder } from "./folder/RunFolder.ts";
-import { SnapshotStore } from "./snapshot/SnapshotStore.ts";
-import { RunLog } from "./log/RunLog.ts";
-/**
- * The run's output subsystem — the composition root that owns the per-run folder and
- * the writers layered on it, and hands them to the rest of the process.
- *
- * Each run owns one of these: its {@link SpinHost} constructs an `Output` over the
- * run's log and threads it to actions as `ctx.output`. Everything that was
- * module-global in the old `output.ts` (the folder path, the mkdir latch, the
- * snapshot sequence) now lives inside these three members, reachable as
- * `output.folder`, `output.snapshots`, `output.runLog` — so callers reach for a named
- * layer instead of a free function, and the shared state has one owner per run.
- */
-export declare class Output {
-    /** The per-run directory and artifact drop. */
-    readonly folder: RunFolder;
-    /** Sequenced JSON/text snapshot files + `[snapshot]` timeline lines. */
-    readonly snapshots: SnapshotStore;
-    /** The `run.jsonl` / `run.log` writer. */
-    readonly runLog: RunLog;
-    constructor(logger: Logger);
-}

package/dist/output/Output.js

@@ -1,27 +0,0 @@
-import { RunFolder } from "./folder/RunFolder.js";
-import { SnapshotStore } from "./snapshot/SnapshotStore.js";
-import { RunLog } from "./log/RunLog.js";
-/**
- * The run's output subsystem — the composition root that owns the per-run folder and
- * the writers layered on it, and hands them to the rest of the process.
- *
- * Each run owns one of these: its {@link SpinHost} constructs an `Output` over the
- * run's log and threads it to actions as `ctx.output`. Everything that was
- * module-global in the old `output.ts` (the folder path, the mkdir latch, the
- * snapshot sequence) now lives inside these three members, reachable as
- * `output.folder`, `output.snapshots`, `output.runLog` — so callers reach for a named
- * layer instead of a free function, and the shared state has one owner per run.
- */
-export class Output {
-    /** The per-run directory and artifact drop. */
-    folder;
-    /** Sequenced JSON/text snapshot files + `[snapshot]` timeline lines. */
-    snapshots;
-    /** The `run.jsonl` / `run.log` writer. */
-    runLog;
-    constructor(logger) {
-        this.folder = new RunFolder();
-        this.snapshots = new SnapshotStore(this.folder, logger);
-        this.runLog = new RunLog(this.folder, this.snapshots);
-    }
-}

package/dist/output/index.d.ts

@@ -1,11 +0,0 @@
-/**
- * The output layer's barrel — the composition root ({@link Output}) and its member
- * classes. There is **no module singleton** here: each run's {@link SpinHost} owns
- * its own `Output`, and threads it to actions as `ctx.output` (and to the spin body
- * as `ctx.snapshot` / `ctx.artifactsFolder`), so nothing binds to process-global
- * state and runs stay isolated.
- */
-export { Output } from "./Output.ts";
-export { RunFolder } from "./folder/RunFolder.ts";
-export { type SnapshotRef, SnapshotStore } from "./snapshot/SnapshotStore.ts";
-export { RunLog } from "./log/RunLog.ts";

package/dist/output/index.js

@@ -1,11 +0,0 @@
-/**
- * The output layer's barrel — the composition root ({@link Output}) and its member
- * classes. There is **no module singleton** here: each run's {@link SpinHost} owns
- * its own `Output`, and threads it to actions as `ctx.output` (and to the spin body
- * as `ctx.snapshot` / `ctx.artifactsFolder`), so nothing binds to process-global
- * state and runs stay isolated.
- */
-export { Output } from "./Output.js";
-export { RunFolder } from "./folder/RunFolder.js";
-export { SnapshotStore } from "./snapshot/SnapshotStore.js";
-export { RunLog } from "./log/RunLog.js";

package/dist/output/log/LogRenderer.d.ts

@@ -1,73 +0,0 @@
-import type { LogEntry } from "./LogsCollector.ts";
-/** The special "title" log lines that get a distinguishing prefix. */
-export type MarkerKind = "event" | "action" | "run" | "snapshot" | "assert";
-/** A run set aside for collapsing: its source and every output line, in order. */
-export interface CollapsedRun {
-    readonly source: string;
-    readonly lines: readonly string[];
-}
-/**
- * One unit of batch-rendered output: either a ready-to-write text `line`
- * (identical to {@link LogRenderer.render}'s output for that entry) or a
- * `collapsed` run the caller must off-load and render via {@link LogRenderer.renderCollapsed}.
- */
-export type DisplayItem = {
-    kind: "line";
-    text: string;
-} | {
-    kind: "collapsed";
-    run: CollapsedRun;
-};
-/**
- * Turns raw {@link LogEntry} records into the pretty, grouped text form.
- * Presentation lives here and nowhere else: the collector stores raw entries; the
- * live drain and `run.log` writer each construct a renderer and feed it entries in
- * order. Two modes over the same grouping rules — pick per instance, don't mix:
- *
- * - **streaming** — {@link render} returns one entry's line as it arrives (live
- *   drain, incremental `run.log`).
- * - **batch** — {@link push}/{@link end} accumulate a same-source run and collapse
- *   it when it grows past the threshold, so one proc's burst can't drown the
- *   durable `run.log` (the caller off-loads the full run to a snapshot).
- *
- * Grouping is decided against the *single merged stream* (`lastSource`), not
- * per-producer — so interleaved concurrent sources re-header correctly. A
- * milestone line breaks the current group, so the next action line re-headers.
- */
-export declare class LogRenderer {
-    /** Lines of a collapsed run shown inline before the pointer. */
-    static readonly COLLAPSE_HEAD = 5;
-    /** Prefix a milestone/header line with its marker (`● run`, `▸ action`, …). */
-    static marker(kind: MarkerKind, text: string): string;
-    /**
-     * Renders a {@link CollapsedRun} as its `head` lines under the `▸ <source>`
-     * header, then a single indented `📎` pointer line to the off-loaded snapshot at
-     * `rel` reporting how many lines were hidden. Pure — `rel` is supplied by the
-     * caller after it writes the file.
-     */
-    static renderCollapsed(run: CollapsedRun, { rel, head }: {
-        rel: string;
-        head?: number;
-    }): string;
-    private lastSource;
-    private run;
-    private readonly threshold;
-    constructor(threshold?: number);
-    /**
-     * Streaming: render one entry to its pretty line. A milestone renders as its own
-     * marker line and breaks the group; other entries are grouped under an
-     * `▸ <source>` header (first line of a group) and indented (the rest).
-     */
-    render(entry: LogEntry): string;
-    /**
-     * Batch: push an entry in order and get back the {@link DisplayItem}s that just
-     * became final (0, 1, or a whole flushed run). Only the current same-source run
-     * is held in memory, so segmenting a huge log stays bounded — the `run.log`
-     * writer feeds this straight from `run.jsonl` on disk. Output is byte-identical
-     * to {@link render} for non-collapsed runs. Pure — no filesystem.
-     */
-    push(entry: LogEntry): DisplayItem[];
-    /** Batch: flush the last pending run (call once after the final {@link push}). */
-    end(): DisplayItem[];
-    private flush;
-}