omkit 0.0.9 → 0.0.10

package/dist/output/Output.js

@@ -0,0 +1,27 @@
+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/folder/RunFolder.d.ts

@@ -0,0 +1,29 @@
+/**
+ * Owns this process's single output directory — `logs/<name>/<date>/<time>/`, where
+ * `run.log`, `run.jsonl`, and snapshots all live together.
+ *
+ * One folder per run, one run per process: the path is computed **once, lazily**, so
+ * a snapshot taken mid-run lands in the same folder as the log that's flushed later.
+ * The {@link SnapshotStore} and {@link RunLog} take a shared instance rather than
+ * reaching for module globals, so "where does this run's output go" has one owner.
+ */
+export declare class RunFolder {
+    private dir;
+    private made;
+    private ensuredSync;
+    /** The entry script's base name (the run's name), e.g. "tskb-build". */
+    name(): string;
+    /** The run's output directory, `logs/<name>/<date>/<time>/` — computed once, lazily. */
+    path(): string;
+    /** A path inside the run folder — `join(path(), name)`. */
+    resolve(name: string): string;
+    /** Create the folder, memoized — every caller awaits the same underlying mkdir. */
+    ensure(): Promise<void>;
+    /**
+     * Absolute path to the run folder, created **synchronously** so a caller can write
+     * into it in the same tick. Absolute so it's safe to hand to a child process with a
+     * different cwd. This is the artifact drop for actions that want to write beside
+     * `run.log` (one folder per run; one run per process).
+     */
+    artifacts(): string;
+}

package/dist/output/folder/RunFolder.js

@@ -0,0 +1,56 @@
+import { mkdirSync } from "node:fs";
+import { mkdir } from "node:fs/promises";
+import path from "node:path";
+import { ymd, hms } from "../../utils/format.js";
+/**
+ * Owns this process's single output directory — `logs/<name>/<date>/<time>/`, where
+ * `run.log`, `run.jsonl`, and snapshots all live together.
+ *
+ * One folder per run, one run per process: the path is computed **once, lazily**, so
+ * a snapshot taken mid-run lands in the same folder as the log that's flushed later.
+ * The {@link SnapshotStore} and {@link RunLog} take a shared instance rather than
+ * reaching for module globals, so "where does this run's output go" has one owner.
+ */
+export class RunFolder {
+    // Computed once on first access and cached — every consumer sees the same folder.
+    dir;
+    // Memoized async mkdir; the promise is shared so concurrent callers await one op.
+    made;
+    // Whether the folder has been created synchronously (for `artifacts()`).
+    ensuredSync = false;
+    /** The entry script's base name (the run's name), e.g. "tskb-build". */
+    name() {
+        const entry = process.argv[1];
+        return entry ? path.basename(entry, path.extname(entry)) : "pipeline";
+    }
+    /** The run's output directory, `logs/<name>/<date>/<time>/` — computed once, lazily. */
+    path() {
+        if (this.dir)
+            return this.dir;
+        const now = new Date();
+        this.dir = path.join("logs", this.name(), ymd(now), hms(now, "-"));
+        return this.dir;
+    }
+    /** A path inside the run folder — `join(path(), name)`. */
+    resolve(name) {
+        return path.join(this.path(), name);
+    }
+    /** Create the folder, memoized — every caller awaits the same underlying mkdir. */
+    ensure() {
+        return (this.made ??= mkdir(this.path(), { recursive: true }).then(() => { }));
+    }
+    /**
+     * Absolute path to the run folder, created **synchronously** so a caller can write
+     * into it in the same tick. Absolute so it's safe to hand to a child process with a
+     * different cwd. This is the artifact drop for actions that want to write beside
+     * `run.log` (one folder per run; one run per process).
+     */
+    artifacts() {
+        const abs = path.resolve(this.path());
+        if (!this.ensuredSync) {
+            mkdirSync(abs, { recursive: true });
+            this.ensuredSync = true;
+        }
+        return abs;
+    }
+}

package/dist/output/index.d.ts

@@ -0,0 +1,11 @@
+/**
+ * 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

@@ -0,0 +1,11 @@
+/**
+ * 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

@@ -0,0 +1,73 @@
+import type { LogEntry } from "./LogsCollector.ts";
+/** The special "title" log lines that get a distinguishing prefix. */
+export type MarkerKind = "event" | "action" | "run" | "snapshot";
+/** 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;
+}

package/dist/output/log/LogRenderer.js

@@ -0,0 +1,131 @@
+const PREFIX = {
+    event: "⚡",
+    action: "▸",
+    run: "●",
+    snapshot: "📎",
+};
+/**
+ * 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 `▸ <source>` header and indents.
+ */
+const MILESTONE = {
+    run: "run",
+    event: "event",
+    snapshot: "snapshot",
+};
+/** Only runs *longer than* this collapse, so a trigger always hides a meaningful amount. */
+const COLLAPSE_THRESHOLD = 15;
+/**
+ * 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 class LogRenderer {
+    /** Lines of a collapsed run shown inline before the pointer. */
+    static COLLAPSE_HEAD = 5;
+    /** Prefix a milestone/header line with its marker (`● run`, `▸ action`, …). */
+    static marker(kind, text) {
+        return `${PREFIX[kind]} ${text}`;
+    }
+    /**
+     * 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, { rel, head = LogRenderer.COLLAPSE_HEAD }) {
+        const shown = run.lines.slice(0, head);
+        const lines = shown.map((message, i) => i === 0 ? `${LogRenderer.marker("action", run.source)}\n\t${message}` : `\t${message}`);
+        const hidden = run.lines.length - shown.length;
+        lines.push(`\t${LogRenderer.marker("snapshot", `… +${hidden} more lines → ${rel}`)}`);
+        return lines.join("\n");
+    }
+    // Streaming grouping state: the source of the group currently open.
+    lastSource;
+    // Batch state: the same-source run currently being accumulated.
+    run;
+    threshold;
+    constructor(threshold = COLLAPSE_THRESHOLD) {
+        this.threshold = threshold;
+    }
+    /**
+     * 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) {
+        const milestone = MILESTONE[entry.level];
+        if (milestone) {
+            // Reset grouping: after an interjection, the next action line re-headers.
+            this.lastSource = undefined;
+            return LogRenderer.marker(milestone, entry.message);
+        }
+        if (entry.source !== this.lastSource) {
+            this.lastSource = entry.source;
+            return `${LogRenderer.marker("action", entry.source)}\n\t${entry.message}`;
+        }
+        return `\t${entry.message}`;
+    }
+    /**
+     * 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) {
+        const out = [];
+        const milestone = MILESTONE[entry.level];
+        if (milestone) {
+            // A milestone breaks the current run, then renders as its own line.
+            this.flush(out);
+            out.push({ kind: "line", text: LogRenderer.marker(milestone, entry.message) });
+            return out;
+        }
+        if (this.run && this.run.source === entry.source) {
+            this.run.lines.push(entry.message);
+        }
+        else {
+            this.flush(out);
+            this.run = { source: entry.source, lines: [entry.message] };
+        }
+        return out;
+    }
+    /** Batch: flush the last pending run (call once after the final {@link push}). */
+    end() {
+        const out = [];
+        this.flush(out);
+        return out;
+    }
+    // Flush the pending run into `out`: collapse it if it ran long, else emit grouped
+    // lines exactly as `render` would (header first, indent the rest).
+    flush(out) {
+        const run = this.run;
+        if (!run)
+            return;
+        if (run.lines.length > this.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 ? `${LogRenderer.marker("action", run.source)}\n\t${message}` : `\t${message}`,
+                });
+            });
+        }
+        this.run = undefined;
+    }
+}

package/dist/{core/log-collector → output/log}/LogsCollector.d.ts

@@ -63,3 +63,17 @@ export declare class LogsCollector implements Logger {
     subscribe({ replay }?: SubscribeOptions): AsyncIterable<LogEntry>;
     snapshot(): readonly LogEntry[];
 }
+/**
+ * A {@link Logger} decorator that prefixes every entry's `source` with a fixed path
+ * (` › `-joined), forwarding to a base logger. Handed to a **child** action (and its
+ * `proc`) so all of its output is attributed to its ancestry — `parent › child ›
+ * <source>` — while the underlying store stays the run's one log.
+ */
+export declare class ScopedLogger implements Logger {
+    private readonly base;
+    private readonly prefix;
+    constructor(base: Logger, path: string);
+    attach(stream: AsyncIterable<unknown>, source: string, level: string): void;
+    append(entry: LogInput): void;
+    subscribe(options?: SubscribeOptions): AsyncIterable<LogEntry>;
+}

package/dist/{core/log-collector → output/log}/LogsCollector.js

@@ -1,4 +1,4 @@
-import { AsyncQueue } from "../helpers/AsyncQueue.js";
+import { AsyncQueue } from "../../utils/AsyncQueue.js";
 export class LogsCollector {
     sequence = 0;
     // Recent entries retained in memory, only to replay to late subscribers. The
@@ -95,6 +95,29 @@ export class LogsCollector {
         return this.history;
     }
 }
+/**
+ * A {@link Logger} decorator that prefixes every entry's `source` with a fixed path
+ * (` › `-joined), forwarding to a base logger. Handed to a **child** action (and its
+ * `proc`) so all of its output is attributed to its ancestry — `parent › child ›
+ * <source>` — while the underlying store stays the run's one log.
+ */
+export class ScopedLogger {
+    base;
+    prefix;
+    constructor(base, path) {
+        this.base = base;
+        this.prefix = `${path} › `;
+    }
+    attach(stream, source, level) {
+        this.base.attach(stream, this.prefix + source, level);
+    }
+    append(entry) {
+        this.base.append({ ...entry, source: this.prefix + entry.source });
+    }
+    subscribe(options) {
+        return this.base.subscribe(options);
+    }
+}
 /**
  * Splits a byte/string stream into lines, calling `onLine` for each. Partial
  * lines are buffered across chunks and a non-empty trailing fragment is flushed

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

@@ -0,0 +1,44 @@
+import type { LogsCollector } from "./LogsCollector.ts";
+import type { RunFolder } from "../folder/RunFolder.ts";
+import type { SnapshotStore } from "../snapshot/SnapshotStore.ts";
+/**
+ * Writes the run's two log files: `run.jsonl` (the complete, authoritative record,
+ * streamed live so it survives a hard kill) and `run.log` (the human timeline).
+ *
+ * Two phases: {@link stream} runs for the whole run, appending each entry to both
+ * files as it arrives; {@link write} runs once at finalize, re-rendering `run.log`
+ * from the finished `run.jsonl` in collapsed form. Depends on a {@link RunFolder}
+ * (where the files land) and a {@link SnapshotStore} (to off-load collapsed runs).
+ */
+export declare class RunLog {
+    private readonly folder;
+    private readonly snapshots;
+    constructor(folder: RunFolder, snapshots: SnapshotStore);
+    /**
+     * 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 write} 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.
+     */
+    stream(logs: LogsCollector): Promise<void>;
+    /**
+     * Renders the final, collapsed `run.log` from the authoritative `run.jsonl` (the
+     * complete record {@link stream} 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. Returns the
+     * `run.log` path (surfaced to the terminal).
+     *
+     * Call only after {@link stream} has closed (the run's log is ended), so `run.jsonl`
+     * is complete and no longer being written.
+     */
+    write(): Promise<string>;
+    /** A compact header block for the top of run.log — legend + run identity. */
+    private header;
+}

package/dist/output/log/RunLog.js

@@ -0,0 +1,119 @@
+import { createReadStream, createWriteStream } from "node:fs";
+import { createInterface } from "node:readline";
+import { LogRenderer } from "./LogRenderer.js";
+import { closeStream } from "../../system/fs/streams.js";
+import { ymd, hms } from "../../utils/format.js";
+/**
+ * Writes the run's two log files: `run.jsonl` (the complete, authoritative record,
+ * streamed live so it survives a hard kill) and `run.log` (the human timeline).
+ *
+ * Two phases: {@link stream} runs for the whole run, appending each entry to both
+ * files as it arrives; {@link write} runs once at finalize, re-rendering `run.log`
+ * from the finished `run.jsonl` in collapsed form. Depends on a {@link RunFolder}
+ * (where the files land) and a {@link SnapshotStore} (to off-load collapsed runs).
+ */
+export class RunLog {
+    folder;
+    snapshots;
+    constructor(folder, snapshots) {
+        this.folder = folder;
+        this.snapshots = snapshots;
+    }
+    /**
+     * 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 write} 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.
+     */
+    async stream(logs) {
+        const entries = logs.subscribe({ replay: true });
+        await this.folder.ensure();
+        const jsonl = createWriteStream(this.folder.resolve("run.jsonl"));
+        const pretty = createWriteStream(this.folder.resolve("run.log"));
+        const renderer = new LogRenderer();
+        pretty.write(this.header() + "\n");
+        try {
+            for await (const entry of entries) {
+                jsonl.write(JSON.stringify(entry) + "\n");
+                pretty.write(renderer.render(entry) + "\n");
+            }
+        }
+        finally {
+            // End AND wait for both streams to fully close before resolving. {@link write}
+            // re-renders run.log at finalize (from this run.jsonl); if a buffered chunk from
+            // this stream landed *after* write() truncated run.log, the OS would zero-fill the
+            // gap — a multi-MB run of NUL bytes. `run` awaits this promise before calling
+            // write(), so this writer is guaranteed done first (and run.jsonl is complete).
+            await Promise.all([closeStream(jsonl), closeStream(pretty)]);
+        }
+    }
+    /**
+     * Renders the final, collapsed `run.log` from the authoritative `run.jsonl` (the
+     * complete record {@link stream} 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. Returns the
+     * `run.log` path (surfaced to the terminal).
+     *
+     * Call only after {@link stream} has closed (the run's log is ended), so `run.jsonl`
+     * is complete and no longer being written.
+     */
+    async write() {
+        await this.folder.ensure();
+        const jsonlFile = this.folder.resolve("run.jsonl");
+        const file = this.folder.resolve("run.log");
+        const out = createWriteStream(file);
+        out.write(this.header());
+        const renderer = new LogRenderer();
+        const writes = [];
+        const emit = (item) => {
+            if (item.kind === "line") {
+                out.write(item.text + "\n");
+            }
+            else {
+                const snap = this.snapshots.captureText(`output-${item.run.source}`, item.run.lines);
+                writes.push(snap.written);
+                out.write(LogRenderer.renderCollapsed(item.run, { 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 renderer.push(entry))
+                    emit(item);
+            }
+        }
+        catch {
+            // run.jsonl missing/unreadable (e.g. a very early crash) — write what we have.
+        }
+        for (const item of renderer.end())
+            emit(item);
+        await closeStream(out); // flush + close run.log before reporting it written
+        await Promise.all(writes); // ensure every off-loaded run is on disk
+        return file;
+    }
+    /** A compact header block for the top of run.log — legend + run identity. */
+    header() {
+        const now = new Date();
+        return [
+            `─── ${this.folder.name()} · ${ymd(now)} ${hms(now)} ───`,
+            `● run  ⚡ event  ▸ action  📎 snapshot  ⇥ output`,
+            "",
+        ].join("\n");
+    }
+}

package/dist/output/snapshot/SnapshotStore.d.ts

@@ -0,0 +1,49 @@
+import type { Logger } from "../log/LogsCollector.ts";
+import type { RunFolder } from "../folder/RunFolder.ts";
+/** 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 sequenced snapshot files into the run folder and (for {@link snapshot})
+ * drops a `[snapshot]` pointer line into the timeline.
+ *
+ * Sequence numbers make repeated snapshots of the same name a history rather than an
+ * overwrite. Paths are computed synchronously so a caller can reference the file in
+ * the same tick while the write proceeds in the background. Depends on a
+ * {@link RunFolder} (where the files land) and a {@link Logger} (only `snapshot`
+ * writes a timeline line).
+ */
+export declare class SnapshotStore {
+    private seq;
+    private readonly folder;
+    private readonly log;
+    constructor(folder: RunFolder, log: Logger);
+    /**
+     * Writes `value` as a sequenced JSON snapshot file (`<name>-NN.json`) and returns its
+     * path — **without** logging a pointer line. The path is computed synchronously 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.
+     */
+    captureJson(name: string, value: unknown): SnapshotRef;
+    /**
+     * Writes raw text `lines` as a sequenced `.log` snapshot file — the text sibling of
+     * {@link captureJson}. {@link RunLog.write} uses it to off-load a collapsed output run
+     * from `run.log`, keeping the burst's full text one click away.
+     */
+    captureText(name: string, lines: readonly string[]): SnapshotRef;
+    /**
+     * Captures a value as a JSON snapshot (via {@link captureJson}) and records a
+     * `[snapshot] <name>: <path>` line in the timeline at the point it's taken. Callable
+     * any time, anywhere in the run; resolves with the file path once written.
+     */
+    snapshot(name: string, value: unknown): Promise<string>;
+    /** Shared writer: sequence + sanitize the name, write in the background, return its refs. */
+    private capture;
+}