omkit 0.0.15 → 0.1.1

package/dist/{utils → foundation}/AsyncQueue.js

@@ -1,3 +1,4 @@
+/** A single-consumer async queue: `push` feeds it, `for await` drains it, `close` ends it. */
 export class AsyncQueue {
     items = [];
     resolvers = [];
@@ -7,35 +8,23 @@ export class AsyncQueue {
             return;
         const resolver = this.resolvers.shift();
         if (resolver) {
-            resolver({
-                done: false,
-                value: item,
-            });
+            resolver({ done: false, value: item });
             return;
         }
         this.items.push(item);
     }
-    /**
-     * Ends the queue: any parked reader resolves `{ done: true }` immediately, and
-     * once already-buffered items are drained, future reads do too. Idempotent.
-     */
+    /** Ends the queue: parked readers resolve `{ done: true }`, drained reads too. Idempotent. */
     close() {
         if (this.closed)
             return;
         this.closed = true;
-        // Unblock everyone parked — nothing more is coming.
         for (const resolve of this.resolvers.splice(0))
             resolve({ done: true, value: undefined });
     }
     next() {
         const item = this.items.shift();
-        if (item !== undefined) {
-            return Promise.resolve({
-                done: false,
-                value: item,
-            });
-        }
-        // Drained and closed → the iteration is over.
+        if (item !== undefined)
+            return Promise.resolve({ done: false, value: item });
         if (this.closed)
             return Promise.resolve({ done: true, value: undefined });
         return new Promise((resolve) => {
@@ -43,8 +32,6 @@ export class AsyncQueue {
         });
     }
     [Symbol.asyncIterator]() {
-        return {
-            next: () => this.next(),
-        };
+        return { next: () => this.next() };
     }
 }

package/dist/foundation/CancelledError.d.ts

@@ -0,0 +1,10 @@
+/**
+ * The error a cancelled node reports — its `.ref` rejects with it and its `.result`
+ * resolves `{ ok: false, error: CancelledError }` — so an awaiter can tell cancellation
+ * from a genuine failure. A cancelled node is never a verdict failure.
+ */
+export declare class CancelledError extends Error {
+    constructor(message?: string);
+}
+/** True if `error` is a {@link CancelledError}. */
+export declare const isCancelled: (error: unknown) => error is CancelledError;

package/dist/foundation/CancelledError.js

@@ -0,0 +1,13 @@
+/**
+ * The error a cancelled node reports — its `.ref` rejects with it and its `.result`
+ * resolves `{ ok: false, error: CancelledError }` — so an awaiter can tell cancellation
+ * from a genuine failure. A cancelled node is never a verdict failure.
+ */
+export class CancelledError extends Error {
+    constructor(message = "cancelled") {
+        super(message);
+        this.name = "CancelledError";
+    }
+}
+/** True if `error` is a {@link CancelledError}. */
+export const isCancelled = (error) => error instanceof CancelledError;

package/dist/foundation/Deferred.d.ts

@@ -0,0 +1,8 @@
+/** A promise paired with its settlers, for a set-once value (a handle, an Outcome, …). */
+export interface Deferred<T> {
+    promise: Promise<T>;
+    resolve: (value: T) => void;
+    reject: (reason: unknown) => void;
+}
+/** Create a {@link Deferred}: a fresh promise with its `resolve`/`reject` captured. */
+export declare function defer<T>(): Deferred<T>;

package/dist/foundation/Deferred.js

@@ -0,0 +1,10 @@
+/** Create a {@link Deferred}: a fresh promise with its `resolve`/`reject` captured. */
+export function defer() {
+    let resolve;
+    let reject;
+    const promise = new Promise((res, rej) => {
+        resolve = res;
+        reject = rej;
+    });
+    return { promise, resolve, reject };
+}

package/dist/foundation/LogEntry.d.ts

@@ -0,0 +1,29 @@
+/**
+ * One row on the run's timeline, and the read-only log view. Plain data shapes in
+ * foundation so every layer (output writers, core, actions) can name them without
+ * depending on the output layer. Attribution is lightweight — `nodeId`/`path`, not
+ * the full ActionRef — so name/tags aren't repeated per row.
+ */
+export interface LogEntry {
+    /** The run-global monotonic sequence — the cross-file merge/ordering key. */
+    readonly sequence: number;
+    /** Epoch millis when appended. */
+    readonly ts: number;
+    /** The owning node's id (attribution key). */
+    readonly nodeId: string;
+    /** The owning node's execution path (`main/chromePage_9f3c`). */
+    readonly path: string;
+    /** `info` | `error` | `event` | `assert` | `snapshot` | `tag` | `child` | `run`. */
+    readonly level: string;
+    /** Finer origin within the node (proc name, `event`, `run`, …). */
+    readonly source: string;
+    readonly message: string;
+}
+/** What an appender supplies; the store stamps `sequence` and `ts`. */
+export type LogInput = Omit<LogEntry, "sequence" | "ts">;
+/** The read-only view handed to actions — they can observe the log, never write it. */
+export interface ReadableLog {
+    subscribe(options?: {
+        replay?: boolean;
+    }): AsyncIterable<LogEntry>;
+}

package/dist/{orchestration/events → foundation}/events.d.ts

@@ -12,20 +12,11 @@ type EmitArgs<P> = [P] extends [void] ? [] : [payload: P];
  * immediately (with `isSnapshot: true`) before receiving live emits.
  */
 export interface Emitter<Events extends object> {
-    /** Emit `key`'s payload to current listeners and retain it as the snapshot. */
     emit<K extends keyof Events>(key: K, ...args: EmitArgs<Events[K]>): void;
-    /** Subscribe to `key`. Fires immediately with the snapshot if one exists. Returns an unsubscribe. */
     listen<K extends keyof Events>(key: K, handler: EventHandler<Events[K]>): () => void;
-    /** Like {@link Emitter.listen} but auto-unsubscribes after the first delivery (snapshot counts). */
     listenOnce<K extends keyof Events>(key: K, handler: EventHandler<Events[K]>): () => void;
-    /**
-     * Observe **every** live emit on this bus, whatever the key — the cross-cutting
-     * hook the bus itself stays out of. Used by the action engine to log each emit
-     * onto the run timeline (through the action's scoped logger), so the bus is pure
-     * pub/sub and logging is layered on top. Fires only for live emits, not snapshot
-     * replays. Returns an unsubscribe.
-     */
+    /** Observe every live emit, whatever the key — the cross-cutting hook (e.g. logging). */
     onAny(handler: (key: keyof Events, payload: unknown) => void): () => void;
 }
-export declare const events: <Events extends object>(_namespace?: string) => Emitter<Events>;
+export declare const events: <Events extends object>() => Emitter<Events>;
 export {};

package/dist/{orchestration/events → foundation}/events.js

@@ -1,19 +1,15 @@
-export const events = (_namespace) => {
+export const events = () => {
     const handlers = new Map();
     const snapshots = new Map();
     const anyHandlers = new Set();
     const emit = (key, ...args) => {
         const payload = args[0];
         snapshots.set(key, payload);
-        // Notify the cross-cutting observers first (they log the emit onto the
-        // timeline), then the keyed handlers — the bus does no logging of its own.
-        // Copy so an observer unsubscribing mid-emit doesn't disturb iteration.
         for (const handler of [...anyHandlers])
             handler(key, payload);
         const set = handlers.get(key);
         if (!set)
             return;
-        // Copy so a handler unsubscribing (or listenOnce) mid-emit doesn't disturb iteration.
         for (const handler of [...set])
             handler(payload, { isSnapshot: false });
     };
@@ -24,7 +20,6 @@ export const events = (_namespace) => {
             handlers.set(key, set);
         }
         set.add(handler);
-        // Snapshot on subscribe, if one has ever been emitted for this key.
         if (snapshots.has(key))
             handler(snapshots.get(key), { isSnapshot: true });
         return () => {
@@ -32,7 +27,6 @@ export const events = (_namespace) => {
         };
     };
     const listenOnce = (key, handler) => {
-        // A retained snapshot satisfies "once" immediately — deliver and we're done.
         if (snapshots.has(key)) {
             handler(snapshots.get(key), { isSnapshot: true });
             return () => { };

package/dist/{utils → foundation}/format.d.ts

@@ -2,8 +2,7 @@
 export declare const pad: (n: number, width?: number) => string;
 /** A date as `YYYY-MM-DD`. */
 export declare const ymd: (d: Date) => string;
-/**
- * A clock time as `HH<sep>MM<sep>SS`. Default `:` for display; pass `-` for a
- * filesystem-safe form (folder names can't contain colons on every platform).
- */
+/** A clock time as `HH<sep>MM<sep>SS` (`-` for filesystem-safe folder names). */
 export declare const hms: (d: Date, sep?: string) => string;
+/** Render a value for the timeline: strings inline, everything else as JSON. */
+export declare const renderValue: (v: unknown) => string;

package/dist/{utils → foundation}/format.js

@@ -2,8 +2,16 @@
 export const pad = (n, width = 2) => String(n).padStart(width, "0");
 /** A date as `YYYY-MM-DD`. */
 export const ymd = (d) => `${d.getFullYear()}-${pad(d.getMonth() + 1)}-${pad(d.getDate())}`;
-/**
- * A clock time as `HH<sep>MM<sep>SS`. Default `:` for display; pass `-` for a
- * filesystem-safe form (folder names can't contain colons on every platform).
- */
+/** A clock time as `HH<sep>MM<sep>SS` (`-` for filesystem-safe folder names). */
 export const hms = (d, sep = ":") => `${pad(d.getHours())}${sep}${pad(d.getMinutes())}${sep}${pad(d.getSeconds())}`;
+/** Render a value for the timeline: strings inline, everything else as JSON. */
+export const renderValue = (v) => {
+    if (typeof v === "string")
+        return v;
+    try {
+        return JSON.stringify(v);
+    }
+    catch {
+        return String(v);
+    }
+};

package/dist/foundation/fsSafe.d.ts

@@ -0,0 +1,7 @@
+/**
+ * Make one path segment safe to use as a filename on any OS. Windows is the
+ * strictest — it forbids `<>:"/\|?*` (a `:` in an action name like
+ * `TSKB:root:watch:docs` would otherwise crash the log writer). We keep it simple:
+ * collapse every run of non-`[A-Za-z0-9._-]` characters to a single `-`.
+ */
+export declare const fsSafe: (segment: string) => string;

package/dist/foundation/fsSafe.js

@@ -0,0 +1,7 @@
+/**
+ * Make one path segment safe to use as a filename on any OS. Windows is the
+ * strictest — it forbids `<>:"/\|?*` (a `:` in an action name like
+ * `TSKB:root:watch:docs` would otherwise crash the log writer). We keep it simple:
+ * collapse every run of non-`[A-Za-z0-9._-]` characters to a single `-`.
+ */
+export const fsSafe = (segment) => segment.replace(/[^a-zA-Z0-9._-]+/g, "-");

package/dist/foundation/ids.d.ts

@@ -0,0 +1,9 @@
+/** A fresh v4 uuid for a node. */
+export declare const newUuid: () => string;
+/** The short form used in ids/paths — first 8 hex of the uuid. */
+export declare const shortId: (uuid: string) => string;
+/**
+ * A node's id: `${name}_${shortId}` → `chromePage_9f3c`. The root passes its own
+ * plain name (`main`) and skips this.
+ */
+export declare const makeId: (name: string, uuid: string) => string;

package/dist/foundation/ids.js

@@ -0,0 +1,10 @@
+import { randomUUID } from "node:crypto";
+/** A fresh v4 uuid for a node. */
+export const newUuid = () => randomUUID();
+/** The short form used in ids/paths — first 8 hex of the uuid. */
+export const shortId = (uuid) => uuid.slice(0, 8);
+/**
+ * A node's id: `${name}_${shortId}` → `chromePage_9f3c`. The root passes its own
+ * plain name (`main`) and skips this.
+ */
+export const makeId = (name, uuid) => `${name}_${shortId(uuid)}`;

package/dist/index.d.ts

@@ -1,25 +1,14 @@
 /**
- * tswm — the operational/runtime layer to tskb's knowledge layer.
+ * omkit (refactored core) — the ExecutionTree model.
  *
- * The core engine: define typed {@link action}s, launch them under one
- * {@link run}, and share a single append-only log. Reusable actions built on
- * this engine live at the `tswm/actions` entry point.
- *
- * This is a curated public surface — internal helpers (the async queue, the log
- * renderer, marker prefixing) are intentionally not exported.
+ * A curated public surface. `om(body)` runs a linear orchestration as the root of
+ * one run; `action(...)` defines typed units you launch with `.exec()`;
+ * `step(name, fn)` is the inline anonymous action. The run's introspectable output
+ * is the on-disk `result.json` / `raw.jsonl` / `.log` files — the ExecutionTree
+ * engine itself is internal and intentionally not exported.
  */
-export { action } from "./orchestration/action/action.ts";
-export type { Action, ActionBuilder, ActionInstance, AnyActionInstance, ActionContext, SystemGlobal, SystemEvents, InstanceEvents, NoEvents, Awaitable, Outcome, } from "./orchestration/action/types.ts";
-export { AssertionError } from "./orchestration/assert.ts";
-export type { Assert } from "./orchestration/assert.ts";
-export { spin } from "./orchestration/spin/spin.ts";
-export type { Nod, SpinContext, SpinBody } from "./orchestration/spin/types.ts";
-export { events } from "./orchestration/events/events.ts";
-export type { Emitter, EventHandler, EventMeta } from "./orchestration/events/events.ts";
-export { createProc } from "./system/process/process.ts";
-export type { Proc } from "./system/process/process.ts";
-export { LogsCollector } from "./output/log/LogsCollector.ts";
-export type { Logger, LogEntry, LogInput, SubscribeOptions } from "./output/log/LogsCollector.ts";
-export { Output } from "./output/index.ts";
-export type { SnapshotRef } from "./output/index.ts";
-export { FolderCache } from "./system/fs/FolderCache.ts";
+export { om } from "./core/om.ts";
+export { action } from "./core/action.ts";
+export { step } from "./core/step.ts";
+export { CancelledError, isCancelled } from "./foundation/CancelledError.ts";
+export type { Action, ActionInstance, ActionContext, OmContext, RunHandle, Outcome, } from "./core/types.ts";

package/dist/index.js

@@ -1,33 +1,13 @@
 /**
- * tswm — the operational/runtime layer to tskb's knowledge layer.
+ * omkit (refactored core) — the ExecutionTree model.
  *
- * The core engine: define typed {@link action}s, launch them under one
- * {@link run}, and share a single append-only log. Reusable actions built on
- * this engine live at the `tswm/actions` entry point.
- *
- * This is a curated public surface — internal helpers (the async queue, the log
- * renderer, marker prefixing) are intentionally not exported.
+ * A curated public surface. `om(body)` runs a linear orchestration as the root of
+ * one run; `action(...)` defines typed units you launch with `.exec()`;
+ * `step(name, fn)` is the inline anonymous action. The run's introspectable output
+ * is the on-disk `result.json` / `raw.jsonl` / `.log` files — the ExecutionTree
+ * engine itself is internal and intentionally not exported.
  */
-// ── Actions ────────────────────────────────────────────────────────────────
-export { action } from "./orchestration/action/action.js";
-export { AssertionError } from "./orchestration/assert.js";
-// ── Spin (linear orchestration) ──────────────────────────────────────────────
-export { spin } from "./orchestration/spin/spin.js";
-// ── Events ─────────────────────────────────────────────────────────────────
-export { events } from "./orchestration/events/events.js";
-// ── Child processes ────────────────────────────────────────────────────────
-export { createProc } from "./system/process/process.js";
-// ── The log ────────────────────────────────────────────────────────────────
-export { LogsCollector } from "./output/log/LogsCollector.js";
-// ── Snapshots & artifacts ────────────────────────────────────────────────────
-// The output subsystem is owned per-run by the spin and reached through context —
-// `ctx.output` (folder / snapshots / runLog) inside an action, `ctx.snapshot` and
-// `ctx.artifactsFolder` inside a spin body. The classes are exported for typing and
-// advanced use; there is no process-global singleton or free-function form.
-export { Output } from "./output/index.js";
-// ── Folder cache ─────────────────────────────────────────────────────────────
-// Backs the `.withCache(...inputs)` method on instances (fingerprints an
-// action's input files/folders, not its outputs); exposed for scripts that want
-// to inspect or manually invalidate the cache — `FolderCache.fingerprint(...)`,
-// `FolderCache.dir`.
-export { FolderCache } from "./system/fs/FolderCache.js";
+export { om } from "./core/om.js";
+export { action } from "./core/action.js";
+export { step } from "./core/step.js";
+export { CancelledError, isCancelled } from "./foundation/CancelledError.js";

package/dist/output/LiveRenderer.d.ts

@@ -0,0 +1,13 @@
+import type { LogStore } from "./log/LogStore.ts";
+/**
+ * Renders a **curated** stream of milestones to the terminal, live — action
+ * launches, completions, and errors, plus events, asserts, and snapshots. The bulk
+ * output (console lines, proc stdout/stderr) is intentionally *not* shown live; it
+ * lives in the per-action `.log` files. Writes through the pre-patch terminal
+ * writer (so it can't feed back into console capture).
+ */
+export declare class LiveRenderer {
+    private readonly write;
+    constructor(write: (line: string) => void);
+    run(store: LogStore): Promise<void>;
+}

package/dist/output/LiveRenderer.js

@@ -0,0 +1,56 @@
+/**
+ * Renders a **curated** stream of milestones to the terminal, live — action
+ * launches, completions, and errors, plus events, asserts, and snapshots. The bulk
+ * output (console lines, proc stdout/stderr) is intentionally *not* shown live; it
+ * lives in the per-action `.log` files. Writes through the pre-patch terminal
+ * writer (so it can't feed back into console capture).
+ */
+export class LiveRenderer {
+    write;
+    constructor(write) {
+        this.write = write;
+    }
+    async run(store) {
+        for await (const entry of store.subscribe({ replay: true })) {
+            const line = format(entry);
+            if (line !== null)
+                this.write(line);
+        }
+    }
+}
+const firstLine = (message) => message.split("\n", 1)[0] ?? message;
+/** ✓ ok · ⊘ cancelled (a clean stop) · ✗ failed. */
+const doneIcon = (status) => status === "ok" ? "✓" : status === "cancelled" ? "⊘" : "✗";
+/** Map a curated entry to a terminal line, or `null` to drop it from the live view. */
+const format = (e) => {
+    // Action launch — bubbled onto the parent as `→ <childId> · <log>`.
+    if (e.level === "child" && e.source === "launch") {
+        const child = e.message.replace(/^→\s*/, "").split(" · ")[0];
+        return `▶ ${e.path}/${child}`;
+    }
+    // Lifecycle events: `launched` is already shown via the launch pointer above, so
+    // drop the duplicate; `done · <status>` renders with the status icon.
+    if (e.level === "event" && e.source === "lifecycle") {
+        if (e.message === "launched")
+            return null;
+        const status = e.message.replace(/^done · /, "");
+        return `${doneIcon(status)} ${e.path} · ${status}`;
+    }
+    // Run milestones (started / tearing down / finished).
+    if (e.level === "run")
+        return `· ${e.message}`;
+    // An action's *own* failure — not proc stderr (source = proc name), console.error,
+    // or a teardown cancellation (which is a clean stop, not an error).
+    if (e.level === "error" && e.source === "error") {
+        return `✗ ${e.path} · ${firstLine(e.message)}`;
+    }
+    // User-emitted events.
+    if (e.level === "event")
+        return `⚡ ${e.path} · ${e.message}`;
+    if (e.level === "assert")
+        return `  ${e.path} · ${e.message}`;
+    if (e.level === "snapshot")
+        return `📸 ${e.path} · ${e.message}`;
+    // Everything else (info / console / proc output / tag / bubbled child events) → files only.
+    return null;
+};

package/dist/output/console/ConsoleCapture.d.ts

@@ -0,0 +1,20 @@
+import type { ActionRef } from "../../foundation/ActionRef.ts";
+import type { LogStore } from "../log/LogStore.ts";
+/** Resolves the action a console call should be attributed to (the ALS current node). */
+export type AttributionProvider = () => ActionRef | undefined;
+/**
+ * Folds every `console.*` call made during the run into the log, attributed to the
+ * action it was called in. Uses `patch-console`, which swaps the whole console
+ * surface (`log`/`table`/`trace`/`group`/…) over a captured `Console`, so native
+ * formatting is preserved. Level is stream-granular: stdout → `info`, stderr →
+ * `error`. The `AttributionProvider` (injected by `core`, wired to the ALS) keeps
+ * this layer ignorant of the execution tree.
+ */
+export declare class ConsoleCapture {
+    private readonly store;
+    private readonly attribution;
+    private restore;
+    constructor(store: LogStore, attribution: AttributionProvider);
+    install(): void;
+    uninstall(): void;
+}

package/dist/output/console/ConsoleCapture.js

@@ -0,0 +1,47 @@
+import { Console as NodeConsole } from "node:console";
+import patchConsole from "patch-console";
+/**
+ * Folds every `console.*` call made during the run into the log, attributed to the
+ * action it was called in. Uses `patch-console`, which swaps the whole console
+ * surface (`log`/`table`/`trace`/`group`/…) over a captured `Console`, so native
+ * formatting is preserved. Level is stream-granular: stdout → `info`, stderr →
+ * `error`. The `AttributionProvider` (injected by `core`, wired to the ALS) keeps
+ * this layer ignorant of the execution tree.
+ */
+export class ConsoleCapture {
+    store;
+    attribution;
+    restore;
+    constructor(store, attribution) {
+        this.store = store;
+        this.attribution = attribution;
+    }
+    install() {
+        // patch-console does `new console.Console(...)`; some runners (vitest) swap the
+        // global console for one without `.Console`, so fill it from node:console.
+        const globalConsole = console;
+        if (typeof globalConsole.Console !== "function")
+            globalConsole.Console = NodeConsole;
+        this.restore = patchConsole((stream, data) => {
+            const ref = this.attribution();
+            if (!ref)
+                return;
+            const level = stream === "stderr" ? "error" : "info";
+            for (const line of data.split("\n")) {
+                if (line.length === 0)
+                    continue;
+                this.store.append({
+                    nodeId: ref.id,
+                    path: ref.path,
+                    level,
+                    source: "console",
+                    message: line,
+                });
+            }
+        });
+    }
+    uninstall() {
+        this.restore?.();
+        this.restore = undefined;
+    }
+}

package/dist/output/folder/RunFolder.d.ts

@@ -1,29 +1,18 @@
 /**
- * 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.
+ * Owns this run's single output directory — `logs/<name>/<date>/<time>/` — where
+ * `raw.jsonl`, the per-action `.log` files, rollups, and `result.json` all live.
+ * The path is computed once, lazily, and always returned absolute so links written
+ * into logs resolve regardless of cwd.
  */
 export declare class RunFolder {
     private dir;
-    private made;
-    private ensuredSync;
-    /** The entry script's base name (the run's name), e.g. "tskb-build". */
+    private ensured;
+    /** The entry script's base name — the run's folder name. */
     name(): string;
-    /** The run's output directory, `logs/<name>/<date>/<time>/` — computed once, lazily. */
+    /** The absolute run directory, computed once and created on first access. */
     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;
+    /** Absolute path to `name` inside the run folder; ensures the folder exists. */
+    file(name: string): string;
+    /** Create the run folder synchronously (idempotent). */
+    ensure(): void;
 }

package/dist/output/folder/RunFolder.js

@@ -1,56 +1,38 @@
 import { mkdirSync } from "node:fs";
-import { mkdir } from "node:fs/promises";
 import path from "node:path";
-import { ymd, hms } from "../../utils/format.js";
+import { ymd, hms } from "../../foundation/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.
+ * Owns this run's single output directory — `logs/<name>/<date>/<time>/` — where
+ * `raw.jsonl`, the per-action `.log` files, rollups, and `result.json` all live.
+ * The path is computed once, lazily, and always returned absolute so links written
+ * into logs resolve regardless of cwd.
  */
 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". */
+    ensured = false;
+    /** The entry script's base name — the run's folder name. */
     name() {
         const entry = process.argv[1];
-        return entry ? path.basename(entry, path.extname(entry)) : "pipeline";
+        return entry ? path.basename(entry, path.extname(entry)) : "om";
     }
-    /** The run's output directory, `logs/<name>/<date>/<time>/` — computed once, lazily. */
+    /** The absolute run directory, computed once and created on first access. */
     path() {
         if (this.dir)
             return this.dir;
         const now = new Date();
-        this.dir = path.join("logs", this.name(), ymd(now), hms(now, "-"));
+        this.dir = path.resolve("logs", this.name(), ymd(now), hms(now, "-"));
         return this.dir;
     }
-    /** A path inside the run folder — `join(path(), name)`. */
-    resolve(name) {
+    /** Absolute path to `name` inside the run folder; ensures the folder exists. */
+    file(name) {
+        this.ensure();
         return path.join(this.path(), name);
     }
-    /** Create the folder, memoized — every caller awaits the same underlying mkdir. */
+    /** Create the run folder synchronously (idempotent). */
     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;
+        if (this.ensured)
+            return;
+        mkdirSync(this.path(), { recursive: true });
+        this.ensured = true;
     }
 }

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

@@ -0,0 +1,22 @@
+import type { LogEntry, LogInput, ReadableLog } from "../../foundation/LogEntry.ts";
+/**
+ * The run's single append-only timeline. Owns the run-global `sequence`, keeps the
+ * full history (for replay + finalize projections), and fans live entries out to
+ * subscribers. It holds no presentation — headers/prefixes are applied by writers
+ * at read time. Actions receive it only as {@link ReadableLog}.
+ */
+export declare class LogStore implements ReadableLog {
+    private seq;
+    private readonly history;
+    private readonly subscribers;
+    private ended;
+    /** Append one entry; stamps `sequence`/`ts`, retains it, fans it out. */
+    append(input: LogInput): LogEntry;
+    subscribe({ replay }?: {
+        replay?: boolean | undefined;
+    }): AsyncIterable<LogEntry>;
+    /** EOF for readers: end every live subscription and refuse new ones. Called once at finalize. */
+    close(): void;
+    /** The complete history — the source for finalize-time projections (per-node logs, rollups). */
+    entries(): readonly LogEntry[];
+}