omkit 0.0.9 → 0.0.11

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,68 +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;
-}
-/**
- * A stateful, **streaming** segmenter: `push` each {@link LogEntry} in order and
- * it returns the {@link DisplayItem}s that just became final (0, 1, or a whole
- * flushed run), then `end()` flushes the last pending run. Only the current
- * same-source run is held in memory, so segmenting a huge log stays bounded —
- * {@link writeLog} feeds it straight from `run.jsonl` on disk. Output is
- * byte-identical to {@link segmentForFile}. Pure — no filesystem.
- */
-export declare const createFileSegmenter: ({ threshold }?: SegmentOptions) => {
-    push(entry: LogEntry): DisplayItem[];
-    end(): DisplayItem[];
-};
-/**
- * Segments a full, ordered entry list into {@link DisplayItem}s (the array form of
- * {@link createFileSegmenter}). 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.
- */
-export declare const segmentForFile: (entries: readonly LogEntry[], options?: 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,132 +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;
-/**
- * A stateful, **streaming** segmenter: `push` each {@link LogEntry} in order and
- * it returns the {@link DisplayItem}s that just became final (0, 1, or a whole
- * flushed run), then `end()` flushes the last pending run. Only the current
- * same-source run is held in memory, so segmenting a huge log stays bounded —
- * {@link writeLog} feeds it straight from `run.jsonl` on disk. Output is
- * byte-identical to {@link segmentForFile}. Pure — no filesystem.
- */
-export const createFileSegmenter = ({ threshold = COLLAPSE_THRESHOLD } = {}) => {
-    // The run currently being accumulated: a same-source stretch of output lines.
-    let run;
-    // Flush the pending run into `out`: collapse it if it ran long, else emit
-    // grouped lines exactly as createRenderer would (header first, indent the rest).
-    const flush = (out) => {
-        if (!run)
-            return;
-        if (run.lines.length > threshold) {
-            out.push({ kind: "collapsed", run: { source: run.source, lines: run.lines } });
-        }
-        else {
-            run.lines.forEach((message, i) => {
-                out.push({
-                    kind: "line",
-                    text: i === 0 ? `${marker("action", run.source)}\n\t${message}` : `\t${message}`,
-                });
-            });
-        }
-        run = undefined;
-    };
-    return {
-        push(entry) {
-            const out = [];
-            const milestone = MILESTONE[entry.level];
-            if (milestone) {
-                // A milestone breaks the current run, then renders as its own line.
-                flush(out);
-                out.push({ kind: "line", text: marker(milestone, entry.message) });
-                return out;
-            }
-            if (run && run.source === entry.source) {
-                run.lines.push(entry.message);
-            }
-            else {
-                flush(out);
-                run = { source: entry.source, lines: [entry.message] };
-            }
-            return out;
-        },
-        end() {
-            const out = [];
-            flush(out);
-            return out;
-        },
-    };
-};
-/**
- * Segments a full, ordered entry list into {@link DisplayItem}s (the array form of
- * {@link createFileSegmenter}). 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.
- */
-export const segmentForFile = (entries, options = {}) => {
-    const seg = createFileSegmenter(options);
-    const items = [];
-    for (const entry of entries)
-        items.push(...seg.push(entry));
-    items.push(...seg.end());
-    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,68 +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;
-/**
- * Renders the final, collapsed `run.log` from the authoritative `run.jsonl` (the
- * complete record {@link streamLog} wrote), **streaming** it line by line so the
- * whole run is never held in memory. Grouping/indentation is applied here so the
- * stored `run.jsonl` stays presentation-free; large same-source runs are collapsed
- * — off-loaded to a text snapshot and replaced inline by their head plus a pointer
- * — so one proc's burst can't drown the timeline. `run.jsonl` is left as-is (it's
- * the full raw record). Returns the `run.log` path (surfaced to the terminal).
- *
- * Call only after {@link streamLog} has closed (the run's log is ended), so
- * `run.jsonl` is complete and no longer being written.
- */
-export declare const writeLog: () => Promise<string>;
-/**
- * Streams every log entry to `run.jsonl` (the complete, authoritative record) and
- * a live `run.log` incrementally as they arrive, so output survives a hard kill or
- * lost SIGINT. The log is closed once at finalize, after which {@link writeLog}
- * re-renders `run.log` from `run.jsonl` in collapsed form.
- *
- * Subscribes **synchronously, before any `await`** — so a fast synchronous
- * producer that appends (and trims the in-memory history) before the file setup
- * finishes still has its entries buffered on the subscription queue rather than
- * lost. `replay: true` covers anything already logged when this is called.
- */
-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,213 +0,0 @@
-import { createReadStream, createWriteStream, mkdirSync } from "node:fs";
-import { mkdir, writeFile } from "node:fs/promises";
-import { createInterface } from "node:readline";
-import path from "node:path";
-import { log } from "./log-collector/global.js";
-import { COLLAPSE_HEAD, createFileSegmenter, createRenderer, renderCollapsed, } 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");
-};
-/**
- * Renders the final, collapsed `run.log` from the authoritative `run.jsonl` (the
- * complete record {@link streamLog} wrote), **streaming** it line by line so the
- * whole run is never held in memory. Grouping/indentation is applied here so the
- * stored `run.jsonl` stays presentation-free; large same-source runs are collapsed
- * — off-loaded to a text snapshot and replaced inline by their head plus a pointer
- * — so one proc's burst can't drown the timeline. `run.jsonl` is left as-is (it's
- * the full raw record). Returns the `run.log` path (surfaced to the terminal).
- *
- * Call only after {@link streamLog} has closed (the run's log is ended), so
- * `run.jsonl` is complete and no longer being written.
- */
-export const writeLog = async () => {
-    await ensureDir();
-    const jsonlFile = path.join(runDir(), "run.jsonl");
-    const file = path.join(runDir(), "run.log");
-    const out = createWriteStream(file);
-    out.write(logHeader());
-    const seg = createFileSegmenter();
-    const writes = [];
-    const emit = (item) => {
-        if (item.kind === "line") {
-            out.write(item.text + "\n");
-        }
-        else {
-            const snap = captureText(`output-${item.run.source}`, item.run.lines);
-            writes.push(snap.written);
-            out.write(renderCollapsed(item.run, { head: COLLAPSE_HEAD, rel: snap.rel }) + "\n");
-        }
-    };
-    try {
-        const rl = createInterface({ input: createReadStream(jsonlFile), crlfDelay: Infinity });
-        for await (const line of rl) {
-            if (!line)
-                continue;
-            let entry;
-            try {
-                entry = JSON.parse(line);
-            }
-            catch {
-                continue; // a torn final line (dirty exit) — skip it
-            }
-            for (const item of seg.push(entry))
-                emit(item);
-        }
-    }
-    catch {
-        // run.jsonl missing/unreadable (e.g. a very early crash) — write what we have.
-    }
-    for (const item of seg.end())
-        emit(item);
-    await streamClosed(out); // flush + close run.log before reporting it written
-    await Promise.all(writes); // ensure every off-loaded run is on disk
-    return file;
-};
-/**
- * Streams every log entry to `run.jsonl` (the complete, authoritative record) and
- * a live `run.log` incrementally as they arrive, so output survives a hard kill or
- * lost SIGINT. The log is closed once at finalize, after which {@link writeLog}
- * re-renders `run.log` from `run.jsonl` in collapsed form.
- *
- * Subscribes **synchronously, before any `await`** — so a fast synchronous
- * producer that appends (and trims the in-memory history) before the file setup
- * finishes still has its entries buffered on the subscription queue rather than
- * lost. `replay: true` covers anything already logged when this is called.
- */
-export const streamLog = async (logs) => {
-    const entries = logs.subscribe({ replay: true });
-    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 entries) {
-            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}
-        // re-renders run.log at finalize (from this run.jsonl); if a buffered chunk from
-        // this stream landed *after* writeLog truncated run.log, the OS would zero-fill
-        // the gap — a multi-MB run of NUL bytes. `run` awaits this promise before
-        // calling `writeLog`, so this writer is guaranteed done first (and run.jsonl is
-        // complete for writeLog to read).
-        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);
-};