omkit 0.0.8 → 0.0.10

package/dist/core/folder-cache.js

@@ -1,109 +0,0 @@
-import { createHash } from "node:crypto";
-import { mkdir, readdir, readFile, rename, stat, writeFile } from "node:fs/promises";
-import { isAbsolute, join, resolve } from "node:path";
-/**
- * An input-fingerprint cache: hash the mtime+size of one or more **input**
- * targets (the files/folders an action reads — *not* what it produces), so an
- * expensive action can be skipped when its inputs are unchanged since its last
- * successful run. Backs the `.withCache(...)` method on action instances.
- *
- * Entries live under `node_modules/.cache/omkit/` (conventional, gitignored) —
- * one JSON file per set of inputs, named by a hash of their absolute paths.
- */
-/** Where cache entries are written — `node_modules/.cache/omkit/` under the cwd. */
-export const cacheDir = join(process.cwd(), "node_modules", ".cache", "omkit");
-/**
- * Require every path to be **absolute** (a relative path is a developer error —
- * throws, naming it) and return them canonicalized with `resolve`, so different
- * spellings of the same target (`.`/`..`/trailing slash) collapse to one stable
- * fingerprint prefix and cache key. `resolve` on an already-absolute path only
- * normalizes — it never falls back to the cwd. Each target may be a file or a
- * folder (see {@link fingerprint}).
- */
-export const resolvePaths = (paths) => paths.map((p) => {
-    if (!isAbsolute(p)) {
-        throw new Error(`withCache: path must be absolute, got "${p}"`);
-    }
-    return resolve(p);
-});
-/**
- * Fingerprints one or more **input** targets by mtime+size. Each target may be
- * a **file** (fingerprinted directly) or a **folder** (walked recursively, its
- * files fingerprinted). Every path must be absolute (throws otherwise). A
- * missing target contributes nothing — so an input that doesn't exist yet is
- * naturally a miss, not an error. The entry list is sorted for determinism
- * before hashing.
- */
-export const fingerprint = async (paths) => {
-    const targets = resolvePaths(paths);
-    const entries = [];
-    const record = (target, rel, mtimeMs, size) => {
-        entries.push(`${target}\0${rel}\0${mtimeMs}\0${size}`);
-    };
-    for (const target of targets) {
-        let root;
-        try {
-            root = await stat(target);
-        }
-        catch {
-            continue; // missing/unreadable — contributes no entries
-        }
-        // A file target fingerprints itself (empty rel — there's no walk).
-        if (root.isFile()) {
-            record(target, "", root.mtimeMs, root.size);
-            continue;
-        }
-        // A folder target: walk it and fingerprint every file inside.
-        let rels;
-        try {
-            rels = await readdir(target, { recursive: true });
-        }
-        catch {
-            continue;
-        }
-        for (const rel of rels) {
-            const abs = join(target, rel);
-            try {
-                const stats = await stat(abs);
-                if (stats.isFile())
-                    record(target, rel, stats.mtimeMs, stats.size);
-            }
-            catch {
-                // entry vanished between readdir and stat — skip
-            }
-        }
-    }
-    entries.sort();
-    return createHash("sha1").update(entries.join("\n")).digest("hex");
-};
-/** The on-disk filename for a set of targets — a hash of their absolute paths. */
-const entryPath = (paths) => {
-    const key = createHash("sha1").update(resolvePaths(paths).sort().join("\0")).digest("hex");
-    return join(cacheDir, `${key}.json`);
-};
-/**
- * Reads the fingerprint stored for these targets, or `undefined` when there's
- * no cache (absent, unreadable, or malformed — all treated as a miss).
- */
-export const read = async (paths) => {
-    try {
-        const raw = await readFile(entryPath(paths), "utf8");
-        const entry = JSON.parse(raw);
-        return typeof entry.fingerprint === "string" ? entry.fingerprint : undefined;
-    }
-    catch {
-        return undefined;
-    }
-};
-/**
- * Records the fingerprint for these targets after a successful run. Writes
- * atomically (temp file + rename) so a concurrent read never sees a half-file.
- */
-export const write = async (paths, fp) => {
-    await mkdir(cacheDir, { recursive: true });
-    const target = entryPath(paths);
-    const entry = { folders: paths, fingerprint: fp, ts: Date.now() };
-    const tmp = `${target}.${process.pid}.tmp`;
-    await writeFile(tmp, JSON.stringify(entry, null, 2));
-    await rename(tmp, target);
-};

package/dist/core/log-collector/global.d.ts

@@ -1,7 +0,0 @@
-import { LogsCollector } from "./LogsCollector.ts";
-/**
- * The process-wide log. One per process: pipelines log into it and drain it, and
- * the event bus pushes an entry here on every `emit`. Created separately from any
- * pipeline so code that runs before/around a pipeline (like a bus) can reach it.
- */
-export declare const log: LogsCollector;

package/dist/core/log-collector/global.js

@@ -1,7 +0,0 @@
-import { LogsCollector } from "./LogsCollector.js";
-/**
- * The process-wide log. One per process: pipelines log into it and drain it, and
- * the event bus pushes an entry here on every `emit`. Created separately from any
- * pipeline so code that runs before/around a pipeline (like a bus) can reach it.
- */
-export const log = new LogsCollector();

package/dist/core/log-collector/render.d.ts

@@ -1,57 +0,0 @@
-import type { LogEntry } from "./LogsCollector.ts";
-/**
- * Builds a stateful renderer that turns raw {@link LogEntry} records into the
- * pretty, grouped text form. Presentation lives here and nowhere else: the
- * collector stores raw entries; `writeLog` and `drain` each create a renderer and
- * feed it the entry stream in order.
- *
- * Grouping is decided against the *single merged stream* (the renderer's own
- * `lastSource`), not per-producer — so interleaved concurrent sources re-header
- * correctly, which the old per-child grouping got wrong. A milestone line breaks
- * the current group, so the next action line re-headers.
- */
-export declare const createRenderer: () => ((entry: LogEntry) => string);
-/** Lines of a collapsed run shown inline before the pointer. */
-export declare const COLLAPSE_HEAD = 5;
-/** Only runs *longer than* this collapse, so a trigger always hides a meaningful amount. */
-export declare const COLLAPSE_THRESHOLD = 15;
-/** 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 createRenderer}'s output for that entry) or a
- * `collapsed` run the caller must off-load and render via {@link renderCollapsed}.
- */
-export type DisplayItem = {
-    kind: "line";
-    text: string;
-} | {
-    kind: "collapsed";
-    run: CollapsedRun;
-};
-/** Tunes {@link segmentForFile}. Defaults to {@link COLLAPSE_HEAD}/{@link COLLAPSE_THRESHOLD}. */
-export interface SegmentOptions {
-    head?: number;
-    threshold?: number;
-}
-/**
- * Segments a full, ordered entry list into {@link DisplayItem}s. Milestones and
- * runs no longer than `threshold` become `line` items byte-identical to
- * {@link createRenderer}; a run longer than `threshold` becomes a single
- * `collapsed` item carrying every line of the run. Pure — no filesystem, no
- * snapshot writing.
- */
-export declare const segmentForFile: (entries: readonly LogEntry[], { threshold }?: SegmentOptions) => DisplayItem[];
-/**
- * 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.
- */
-export declare const renderCollapsed: (run: CollapsedRun, { head, rel }: {
-    head: number;
-    rel: string;
-}) => string;

package/dist/core/log-collector/render.js

@@ -1,111 +0,0 @@
-import { marker } from "../markers.js";
-/**
- * Levels that render as their own top-level milestone line — marker-prefixed and
- * never grouped/indented. Everything else is action/proc output, which the
- * renderer groups under an `[action] <source>` header and indents.
- */
-const MILESTONE = {
-    run: "run",
-    event: "event",
-    snapshot: "snapshot",
-};
-/**
- * Builds a stateful renderer that turns raw {@link LogEntry} records into the
- * pretty, grouped text form. Presentation lives here and nowhere else: the
- * collector stores raw entries; `writeLog` and `drain` each create a renderer and
- * feed it the entry stream in order.
- *
- * Grouping is decided against the *single merged stream* (the renderer's own
- * `lastSource`), not per-producer — so interleaved concurrent sources re-header
- * correctly, which the old per-child grouping got wrong. A milestone line breaks
- * the current group, so the next action line re-headers.
- */
-export const createRenderer = () => {
-    let lastSource;
-    return (entry) => {
-        const milestone = MILESTONE[entry.level];
-        if (milestone) {
-            // Reset grouping: after an interjection, the next action line re-headers.
-            lastSource = undefined;
-            return marker(milestone, entry.message);
-        }
-        if (entry.source !== lastSource) {
-            lastSource = entry.source;
-            return `${marker("action", entry.source)}\n\t${entry.message}`;
-        }
-        return `\t${entry.message}`;
-    };
-};
-// ── Collapsing large output runs (batch / file rendering) ───────────────────
-//
-// A *run* is a maximal stretch of consecutive non-milestone entries sharing one
-// `source` — the same grouping `createRenderer` does. When a proc emits a burst
-// (a build's file tree, tsc/vite chatter), that run can be dozens of lines and
-// drowns the durable `run.log`. The batch renderer below collapses an
-// over-threshold run to its head plus a pointer; the full run is off-loaded to a
-// text snapshot by the caller (which owns the filesystem — this stays pure).
-/** Lines of a collapsed run shown inline before the pointer. */
-export const COLLAPSE_HEAD = 5;
-/** Only runs *longer than* this collapse, so a trigger always hides a meaningful amount. */
-export const COLLAPSE_THRESHOLD = 15;
-/**
- * Segments a full, ordered entry list into {@link DisplayItem}s. Milestones and
- * runs no longer than `threshold` become `line` items byte-identical to
- * {@link createRenderer}; a run longer than `threshold` becomes a single
- * `collapsed` item carrying every line of the run. Pure — no filesystem, no
- * snapshot writing.
- */
-export const segmentForFile = (entries, { threshold = COLLAPSE_THRESHOLD } = {}) => {
-    const items = [];
-    // The run currently being accumulated: a same-source stretch of output lines.
-    let run;
-    // Flush the pending run: collapse it if it ran long, else emit grouped lines
-    // exactly as createRenderer would (header on the first line, indent the rest).
-    const flush = () => {
-        if (!run)
-            return;
-        if (run.lines.length > threshold) {
-            items.push({ kind: "collapsed", run: { source: run.source, lines: run.lines } });
-        }
-        else {
-            run.lines.forEach((message, i) => {
-                items.push({
-                    kind: "line",
-                    text: i === 0 ? `${marker("action", run.source)}\n\t${message}` : `\t${message}`,
-                });
-            });
-        }
-        run = undefined;
-    };
-    for (const entry of entries) {
-        const milestone = MILESTONE[entry.level];
-        if (milestone) {
-            // A milestone breaks the current run, then renders as its own line.
-            flush();
-            items.push({ kind: "line", text: marker(milestone, entry.message) });
-            continue;
-        }
-        if (run && run.source === entry.source) {
-            run.lines.push(entry.message);
-        }
-        else {
-            flush();
-            run = { source: entry.source, lines: [entry.message] };
-        }
-    }
-    flush();
-    return items;
-};
-/**
- * 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.
- */
-export const renderCollapsed = (run, { head, rel }) => {
-    const shown = run.lines.slice(0, head);
-    const lines = shown.map((message, i) => i === 0 ? `${marker("action", run.source)}\n\t${message}` : `\t${message}`);
-    const hidden = run.lines.length - shown.length;
-    lines.push(`\t${marker("snapshot", `… +${hidden} more lines → ${rel}`)}`);
-    return lines.join("\n");
-};

package/dist/core/markers.d.ts

@@ -1,9 +0,0 @@
-/** The special "title" log lines that get a distinguishing prefix. */
-export type MarkerKind = "event" | "action" | "run" | "snapshot";
-/**
- * Prefixes a special log line so it's explicit what it is when scanning the
- * global log — an emitted event (`[ev]`), an action's title (`[action]`), a run
- * lifecycle milestone (`[run]`), or a captured state snapshot (`[snapshot]`) —
- * versus plain output.
- */
-export declare const marker: (kind: MarkerKind, text: string) => string;

package/dist/core/markers.js

@@ -1,13 +0,0 @@
-const PREFIX = {
-    event: "⚡",
-    action: "▸",
-    run: "●",
-    snapshot: "📎",
-};
-/**
- * Prefixes a special log line so it's explicit what it is when scanning the
- * global log — an emitted event (`[ev]`), an action's title (`[action]`), a run
- * lifecycle milestone (`[run]`), or a captured state snapshot (`[snapshot]`) —
- * versus plain output.
- */
-export const marker = (kind, text) => `${PREFIX[kind]} ${text}`;

package/dist/core/output.d.ts

@@ -1,64 +0,0 @@
-import type { LogsCollector } from "./log-collector/LogsCollector.ts";
-/**
- * Absolute path to this run's output folder — `logs/<name>/<date>/<time>/`, where
- * `run.log`, `run.jsonl`, and snapshots live. Exposed so actions can drop their
- * own **artifacts** into the same per-run folder (one folder per run; one run per
- * process). The folder is created on first access — synchronously, so a caller
- * can write into it in the same tick — and the path is absolute so it's safe to
- * hand to a child process with a different cwd.
- */
-export declare const artifactsFolder: () => string;
-/**
- * Drains the collected log to two files in the run's output folder (the common
- * `logs/<name>/<date>/<time>/` convention, local time):
- *
- * - `run.log` — the pretty, human-scannable rendering: just the message lines.
- * - `run.jsonl` — the structured, machine-queryable record: one full {@link LogEntry}
- *   per line (sequence, timestamp, level, source, message), so an agent can filter
- *   and correlate by origin/level/time instead of parsing prose.
- *
- * Returns the `run.log` path (the one surfaced to the terminal).
- */
-export declare const writeLog: (logs: LogsCollector) => Promise<string>;
-/**
- * Streams log entries to `run.jsonl` and `run.log` incrementally as they arrive,
- * so output survives a hard kill or lost SIGINT. Each entry is appended via a
- * write stream. The subscription ends on teardown (`logs.endOn`), after which
- * {@link writeLog} overwrites both files with the authoritative final snapshot
- * (including post-abort entries like "finished"). For dirty exits, whatever was
- * flushed to disk by the OS is the best available record.
- */
-export declare const streamLog: (logs: LogsCollector) => Promise<void>;
-/** A written (or in-flight) snapshot file and where to find it. */
-export interface SnapshotRef {
-    /** Absolute path to the snapshot file. */
-    readonly file: string;
-    /** Path relative to cwd — what a log line references. */
-    readonly rel: string;
-    /** Resolves once the file is flushed to disk. */
-    readonly written: Promise<void>;
-}
-/**
- * Writes `value` as a sequenced JSON snapshot file (`<name>-NN.json`) in the run's
- * output folder and returns its path — **without** logging a pointer line. The
- * path is computed synchronously (so callers can reference it in the same tick)
- * while the write proceeds in the background. Use {@link snapshot} when you also
- * want a `[snapshot]` line in the timeline; the event bus uses this directly to
- * link a non-string payload from its own line.
- */
-export declare const captureSnapshot: (name: string, value: unknown) => SnapshotRef;
-/**
- * Writes raw text `lines` as a sequenced `.log` snapshot file in the run's output
- * folder and returns its path refs — the text sibling of {@link captureSnapshot}
- * (which writes JSON). {@link writeLog} uses it to off-load a collapsed output
- * run from `run.log`, keeping the burst's full text one click away.
- */
-export declare const captureText: (name: string, lines: readonly string[]) => SnapshotRef;
-/**
- * Captures any value as a JSON snapshot file (via {@link captureSnapshot}) and
- * records a `[snapshot] <name>: <path>` line in the timeline at the point it's
- * taken. Files are sequenced so repeated snapshots of the same name are kept as a
- * history rather than overwritten. Callable any time, anywhere in the run;
- * returns the file path once written.
- */
-export declare const snapshot: (name: string, value: unknown) => Promise<string>;

package/dist/core/output.js

@@ -1,190 +0,0 @@
-import { createWriteStream, mkdirSync } from "node:fs";
-import { mkdir, writeFile } from "node:fs/promises";
-import path from "node:path";
-import { log } from "./log-collector/global.js";
-import { COLLAPSE_HEAD, createRenderer, renderCollapsed, segmentForFile, } from "./log-collector/render.js";
-const pad = (n, width = 2) => String(n).padStart(width, "0");
-/** The entry script's base name (the run's name), e.g. "tskb-build". */
-const pipelineName = () => {
-    const entry = process.argv[1];
-    return entry ? path.basename(entry, path.extname(entry)) : "pipeline";
-};
-// One output directory per run (one run per process): logs/<name>/<date>/<time>/.
-// Computed once, lazily — so the log file and every snapshot land together, even
-// when a snapshot is taken mid-run before the log is flushed.
-let dir;
-const runDir = () => {
-    if (dir)
-        return dir;
-    const now = new Date();
-    const day = `${now.getFullYear()}-${pad(now.getMonth() + 1)}-${pad(now.getDate())}`;
-    const time = `${pad(now.getHours())}-${pad(now.getMinutes())}-${pad(now.getSeconds())}`;
-    dir = path.join("logs", pipelineName(), day, time);
-    return dir;
-};
-let made;
-const ensureDir = () => (made ??= mkdir(runDir(), { recursive: true }).then(() => { }));
-let ensuredSync = false;
-/**
- * Absolute path to this run's output folder — `logs/<name>/<date>/<time>/`, where
- * `run.log`, `run.jsonl`, and snapshots live. Exposed so actions can drop their
- * own **artifacts** into the same per-run folder (one folder per run; one run per
- * process). The folder is created on first access — synchronously, so a caller
- * can write into it in the same tick — and the path is absolute so it's safe to
- * hand to a child process with a different cwd.
- */
-export const artifactsFolder = () => {
-    const abs = path.resolve(runDir());
-    if (!ensuredSync) {
-        mkdirSync(abs, { recursive: true });
-        ensuredSync = true;
-    }
-    return abs;
-};
-/** A compact header block for the top of run.log — legend + run identity. */
-const logHeader = () => {
-    const now = new Date();
-    const date = `${now.getFullYear()}-${pad(now.getMonth() + 1)}-${pad(now.getDate())}`;
-    const time = `${pad(now.getHours())}:${pad(now.getMinutes())}:${pad(now.getSeconds())}`;
-    return [
-        `─── ${pipelineName()} · ${date} ${time} ───`,
-        `● run  ⚡ event  ▸ action  📎 snapshot  ⇥ output`,
-        "",
-    ].join("\n");
-};
-/**
- * Drains the collected log to two files in the run's output folder (the common
- * `logs/<name>/<date>/<time>/` convention, local time):
- *
- * - `run.log` — the pretty, human-scannable rendering: just the message lines.
- * - `run.jsonl` — the structured, machine-queryable record: one full {@link LogEntry}
- *   per line (sequence, timestamp, level, source, message), so an agent can filter
- *   and correlate by origin/level/time instead of parsing prose.
- *
- * Returns the `run.log` path (the one surfaced to the terminal).
- */
-export const writeLog = async (logs) => {
-    await ensureDir();
-    const entries = logs.snapshot();
-    // Apply grouping/indentation at write time from the raw entries, so the stored
-    // messages stay presentation-free. Unlike the live `drain`, the final file
-    // collapses large same-source runs: each is off-loaded to a text snapshot and
-    // replaced inline by its head plus a pointer, so one proc's burst can't drown
-    // the timeline. `run.jsonl` below keeps every line, raw.
-    const file = path.join(runDir(), "run.log");
-    const header = logHeader();
-    const writes = [];
-    const parts = segmentForFile(entries).map((item) => {
-        if (item.kind === "line")
-            return item.text;
-        const snap = captureText(`output-${item.run.source}`, item.run.lines);
-        writes.push(snap.written);
-        return renderCollapsed(item.run, { head: COLLAPSE_HEAD, rel: snap.rel });
-    });
-    const pretty = parts.join("\n");
-    await writeFile(file, pretty ? `${header}${pretty}\n` : "", "utf8");
-    // Ensure every off-loaded run is flushed before we report the log is written.
-    await Promise.all(writes);
-    const jsonlFile = path.join(runDir(), "run.jsonl");
-    const jsonl = entries.map((entry) => JSON.stringify(entry)).join("\n");
-    await writeFile(jsonlFile, jsonl ? `${jsonl}\n` : "", "utf8");
-    return file;
-};
-/**
- * Streams log entries to `run.jsonl` and `run.log` incrementally as they arrive,
- * so output survives a hard kill or lost SIGINT. Each entry is appended via a
- * write stream. The subscription ends on teardown (`logs.endOn`), after which
- * {@link writeLog} overwrites both files with the authoritative final snapshot
- * (including post-abort entries like "finished"). For dirty exits, whatever was
- * flushed to disk by the OS is the best available record.
- */
-export const streamLog = async (logs) => {
-    await ensureDir();
-    const jsonlFile = path.join(runDir(), "run.jsonl");
-    const logFile = path.join(runDir(), "run.log");
-    const jsonl = createWriteStream(jsonlFile);
-    const pretty = createWriteStream(logFile);
-    const render = createRenderer();
-    pretty.write(logHeader() + "\n");
-    try {
-        for await (const entry of logs.subscribe({ replay: true })) {
-            jsonl.write(JSON.stringify(entry) + "\n");
-            pretty.write(render(entry) + "\n");
-        }
-    }
-    finally {
-        // End AND wait for both streams to fully close before resolving. {@link writeLog}
-        // truncates and rewrites these same files at finalize; if a buffered chunk from
-        // this stream landed *after* that truncation, the OS would zero-fill the gap —
-        // a multi-MB run of NUL bytes in run.log. `run` awaits this promise before
-        // calling `writeLog`, so this writer is guaranteed done before the rewrite.
-        await Promise.all([streamClosed(jsonl), streamClosed(pretty)]);
-    }
-};
-/** Resolve once a write stream has flushed and closed its file descriptor. */
-const streamClosed = (stream) => new Promise((resolve) => {
-    stream.on("close", () => resolve());
-    stream.on("error", () => resolve()); // a stream error still frees the file; don't hang
-    stream.end();
-});
-let seq = 0;
-/** Serialize a value for a snapshot file, tolerating circular refs / non-JSON values. */
-const serialize = (value) => {
-    try {
-        // JSON.stringify returns undefined for functions/undefined — fall back to a string.
-        return JSON.stringify(value, null, 2) ?? JSON.stringify(String(value));
-    }
-    catch {
-        // Circular or otherwise non-serializable: keep a best-effort representation
-        // rather than throwing and losing the value entirely.
-        return JSON.stringify(String(value));
-    }
-};
-/**
- * Writes `value` as a sequenced JSON snapshot file (`<name>-NN.json`) in the run's
- * output folder and returns its path — **without** logging a pointer line. The
- * path is computed synchronously (so callers can reference it in the same tick)
- * while the write proceeds in the background. Use {@link snapshot} when you also
- * want a `[snapshot]` line in the timeline; the event bus uses this directly to
- * link a non-string payload from its own line.
- */
-export const captureSnapshot = (name, value) => {
-    const safe = name.replace(/[^\w.-]+/g, "-");
-    const file = path.join(runDir(), `${safe}-${pad(++seq)}.json`);
-    const written = ensureDir().then(() => writeFile(file, `${serialize(value)}\n`, "utf8"));
-    // Normalize to forward slashes so the reference is portable in the log artifact.
-    const rel = path.relative(process.cwd(), file).replaceAll("\\", "/");
-    return { file, rel, written };
-};
-/**
- * Writes raw text `lines` as a sequenced `.log` snapshot file in the run's output
- * folder and returns its path refs — the text sibling of {@link captureSnapshot}
- * (which writes JSON). {@link writeLog} uses it to off-load a collapsed output
- * run from `run.log`, keeping the burst's full text one click away.
- */
-export const captureText = (name, lines) => {
-    const safe = name.replace(/[^\w.-]+/g, "-");
-    const file = path.join(runDir(), `${safe}-${pad(++seq)}.log`);
-    const body = lines.length ? `${lines.join("\n")}\n` : "";
-    const written = ensureDir().then(() => writeFile(file, body, "utf8"));
-    // Normalize to forward slashes so the reference is portable in the log artifact.
-    const rel = path.relative(process.cwd(), file).replaceAll("\\", "/");
-    return { file, rel, written };
-};
-/**
- * Captures any value as a JSON snapshot file (via {@link captureSnapshot}) and
- * records a `[snapshot] <name>: <path>` line in the timeline at the point it's
- * taken. Files are sequenced so repeated snapshots of the same name are kept as a
- * history rather than overwritten. Callable any time, anywhere in the run;
- * returns the file path once written.
- */
-export const snapshot = (name, value) => {
-    const { file, rel, written } = captureSnapshot(name, value);
-    // Record the pointer synchronously, so it sits at the right spot in the timeline.
-    log.append({
-        source: "snapshot",
-        level: "snapshot",
-        message: `${name}: ${rel}`,
-    });
-    return written.then(() => file);
-};

package/dist/core/run.d.ts

@@ -1,88 +0,0 @@
-import type { AnyActionInstance } from "./action.ts";
-import { log as logs } from "./log-collector/global.ts";
-/**
- * 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 Spin.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 Spin}.
- */
-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[];
-}
-/**
- * The spin's lifecycle. It only ever moves forward:
- *
- *   open ──▶ closing ──▶ closed
- *
- * - **open** — launching and running actions; `.run(…)` is accepted.
- * - **closing** — teardown has begun (cancel, Ctrl-C, natural completion, or an
- *   uncaught fatal). The signal is aborted, in-flight actions are unwinding, and
- *   new `.run(…)` is refused. Note: a failing *action* does not begin teardown.
- * - **closed** — everything has settled, the log is flushed, the verdict is final.
- */
-export type SpinState = "open" | "closing" | "closed";
-/** A live spin: a set of actions sharing one abort controller and the global log. */
-export interface Spin {
-    /** The shared global log (output + events for everything in this spin). */
-    readonly logs: typeof logs;
-    /** The current lifecycle state — see {@link SpinState}. */
-    readonly state: SpinState;
-    /** Settles once the spin reaches `closed`, carrying the terminal {@link SpinResult}. */
-    readonly done: Promise<SpinResult>;
-    /** The spin's abort signal — for consumers that want to observe teardown. */
-    readonly signal: AbortSignal;
-    /**
-     * Launch more actions into this same spin — same controller, same log. Chainable.
-     *
-     * Throws if the spin is no longer `open`: launching into a closing/closed spin
-     * would bind the actions to an already-aborted signal, so they'd start and
-     * immediately unwind, silently doing nothing. Launch before teardown, or from
-     * a lifecycle event of an action that is still running (those fire while the
-     * spin is still `open`).
-     */
-    run(...actions: AnyActionInstance[]): Spin;
-    /** Begin teardown: abort the signal (killing procs, unblocking waits, stopping daemons). */
-    cancel(): void;
-    /**
-     * Start streaming the global log live to a writer (console by default) in the
-     * background; it stops on its own when the spin settles. Returns the spin, so it
-     * chains. Await `.done` for the verdict.
-     */
-    drain(write?: (message: string) => void): Spin;
-}
-/**
- * Starts the spin: launches the given actions in parallel under one abort
- * controller, against the process-wide global log. Returns a {@link Spin} — add
- * more actions on demand with `.run(…)`, observe `.done` for the verdict, stop
- * with `.cancel()`.
- *
- * **Callable once per process.** A spin *is* the world being modelled, and there's
- * one global log per world; a second call would silently share that log, so it
- * throws instead. Attach further actions — including event-driven ones — to the
- * returned {@link Spin} via its `.run(…)` method, not by calling this again.
- *
- * Each action runs against its own child logger (which headers and indents its
- * lines into the global log) and the spin's shared abort signal — both injected
- * into its context, where the framework also binds a `proc` to them 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.
- */
-export declare function run(...actions: AnyActionInstance[]): Spin;