omkit 0.0.8 → 0.0.10

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;
+}

package/dist/output/snapshot/SnapshotStore.js

@@ -0,0 +1,61 @@
+import { writeFile } from "node:fs/promises";
+import path from "node:path";
+import { pad } from "../../utils/format.js";
+import { serialize } from "../../utils/serialize.js";
+/**
+ * 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 class SnapshotStore {
+    seq = 0;
+    folder;
+    log;
+    constructor(folder, log) {
+        this.folder = folder;
+        this.log = log;
+    }
+    /**
+     * 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, value) {
+        return this.capture(name, "json", `${serialize(value)}\n`);
+    }
+    /**
+     * 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, lines) {
+        return this.capture(name, "log", lines.length ? `${lines.join("\n")}\n` : "");
+    }
+    /**
+     * 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, value) {
+        const { file, rel, written } = this.captureJson(name, value);
+        // Record the pointer synchronously, so it sits at the right spot in the timeline.
+        this.log.append({ source: "snapshot", level: "snapshot", message: `${name}: ${rel}` });
+        return written.then(() => file);
+    }
+    /** Shared writer: sequence + sanitize the name, write in the background, return its refs. */
+    capture(name, ext, body) {
+        const safe = name.replace(/[^\w.-]+/g, "-");
+        const file = this.folder.resolve(`${safe}-${pad(++this.seq)}.${ext}`);
+        const written = this.folder.ensure().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 };
+    }
+}

package/dist/system/fs/FolderCache.d.ts

@@ -0,0 +1,47 @@
+/**
+ * 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.
+ *
+ * Stateless — the cache is the filesystem, so the methods are `static`. Internal
+ * cross-references go through the class name (not `this`), so a caller may pull a
+ * method off the class (`const fp = FolderCache.fingerprint`) without losing it.
+ */
+export declare class FolderCache {
+    /** Where cache entries are written — `node_modules/.cache/omkit/` under the cwd. */
+    static readonly dir: string;
+    /**
+     * 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 FolderCache.fingerprint}).
+     */
+    static resolvePaths(paths: string[]): string[];
+    /**
+     * 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.
+     */
+    static fingerprint(paths: string[]): Promise<string>;
+    /**
+     * Reads the fingerprint stored for these targets, or `undefined` when there's
+     * no cache (absent, unreadable, or malformed — all treated as a miss).
+     */
+    static read(paths: string[]): Promise<string | 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.
+     */
+    static write(paths: string[], fp: string): Promise<void>;
+    /** The on-disk filename for a set of targets — a hash of their absolute paths. */
+    private static entryPath;
+}

package/dist/system/fs/FolderCache.js

@@ -0,0 +1,117 @@
+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.
+ *
+ * Stateless — the cache is the filesystem, so the methods are `static`. Internal
+ * cross-references go through the class name (not `this`), so a caller may pull a
+ * method off the class (`const fp = FolderCache.fingerprint`) without losing it.
+ */
+export class FolderCache {
+    /** Where cache entries are written — `node_modules/.cache/omkit/` under the cwd. */
+    static dir = 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 FolderCache.fingerprint}).
+     */
+    static resolvePaths(paths) {
+        return 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.
+     */
+    static async fingerprint(paths) {
+        const targets = FolderCache.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");
+    }
+    /**
+     * Reads the fingerprint stored for these targets, or `undefined` when there's
+     * no cache (absent, unreadable, or malformed — all treated as a miss).
+     */
+    static async read(paths) {
+        try {
+            const raw = await readFile(FolderCache.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.
+     */
+    static async write(paths, fp) {
+        await mkdir(FolderCache.dir, { recursive: true });
+        const target = FolderCache.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);
+    }
+    /** The on-disk filename for a set of targets — a hash of their absolute paths. */
+    static entryPath(paths) {
+        const key = createHash("sha1").update(FolderCache.resolvePaths(paths).sort().join("\0")).digest("hex");
+        return join(FolderCache.dir, `${key}.json`);
+    }
+}

package/dist/system/fs/streams.d.ts

@@ -0,0 +1,11 @@
+import type { createWriteStream } from "node:fs";
+/**
+ * Flush and close a write stream, resolving once its file descriptor is released.
+ *
+ * Resolves on `close` *or* `error` — a stream error still frees the file, and a
+ * caller waiting to re-read or truncate that file must not hang because the write
+ * end failed. The one shared fs primitive behind both `run.jsonl` and `run.log`
+ * writers, where "the bytes are on disk and the fd is closed" is the exact barrier
+ * the finalize step waits on.
+ */
+export declare const closeStream: (stream: ReturnType<typeof createWriteStream>) => Promise<void>;

package/dist/system/fs/streams.js

@@ -0,0 +1,14 @@
+/**
+ * Flush and close a write stream, resolving once its file descriptor is released.
+ *
+ * Resolves on `close` *or* `error` — a stream error still frees the file, and a
+ * caller waiting to re-read or truncate that file must not hang because the write
+ * end failed. The one shared fs primitive behind both `run.jsonl` and `run.log`
+ * writers, where "the bytes are on disk and the fd is closed" is the exact barrier
+ * the finalize step waits on.
+ */
+export const closeStream = (stream) => new Promise((resolve) => {
+    stream.on("close", () => resolve());
+    stream.on("error", () => resolve()); // a stream error still frees the file; don't hang
+    stream.end();
+});

package/dist/{core → system/process}/process.d.ts

@@ -1,5 +1,6 @@
 import { type Options, type ProcessPromise } from "zx";
-import type { Logger } from "./log-collector/LogsCollector.ts";
+import type { Logger } from "../../output/log/LogsCollector.ts";
+import type { SnapshotStore } from "../../output/snapshot/SnapshotStore.ts";
 /**
  * Force-kill a process **and its whole tree, synchronously**.
  *
@@ -24,11 +25,11 @@ export declare const killTree: (pid: number) => void;
  */
 export type Proc = (name: string, opts?: Partial<Options>) => (pieces: TemplateStringsArray, ...args: unknown[]) => ProcessPromise;
 /**
- * Builds a {@link Proc} bound to a specific log sink and abort signal. The action
- * pipeline injects one per action as `ctx.proc`, wired to that action's logger
- * and the run's signal — so actions just describe the command, with no ambient
- * lookup and nothing threaded through. A custom source (e.g. a CDP connection)
- * follows the same shape: take the action's `logs`/`signal`, push into the log,
- * and hook teardown.
+ * Builds a {@link Proc} bound to a specific log sink, abort signal, and the run's
+ * snapshot store. The action pipeline injects one per action as `ctx.proc`, wired
+ * to that action's logger, the run's signal, and the run's `output.snapshots` — so
+ * actions just describe the command, with no ambient lookup and nothing threaded
+ * through. A custom source (e.g. a CDP connection) follows the same shape: take the
+ * action's `logs`/`signal`, push into the log, and hook teardown.
  */
-export declare const createProc: (logs: Logger, signal: AbortSignal) => Proc;
+export declare const createProc: (logs: Logger, signal: AbortSignal, snapshots: SnapshotStore) => Proc;

package/dist/{core → system/process}/process.js

@@ -1,7 +1,6 @@
 import { execFileSync } from "node:child_process";
 import os from "node:os";
 import { $, kill, usePowerShell } from "zx";
-import { captureSnapshot } from "./output.js";
 // zx defaults to bash, which isn't present on a stock Windows box.
 // Use Windows PowerShell there so zx spawns and quotes for the right shell.
 if (os.platform() === "win32")
@@ -32,14 +31,14 @@ export const killTree = (pid) => {
     }
 };
 /**
- * Builds a {@link Proc} bound to a specific log sink and abort signal. The action
- * pipeline injects one per action as `ctx.proc`, wired to that action's logger
- * and the run's signal — so actions just describe the command, with no ambient
- * lookup and nothing threaded through. A custom source (e.g. a CDP connection)
- * follows the same shape: take the action's `logs`/`signal`, push into the log,
- * and hook teardown.
+ * Builds a {@link Proc} bound to a specific log sink, abort signal, and the run's
+ * snapshot store. The action pipeline injects one per action as `ctx.proc`, wired
+ * to that action's logger, the run's signal, and the run's `output.snapshots` — so
+ * actions just describe the command, with no ambient lookup and nothing threaded
+ * through. A custom source (e.g. a CDP connection) follows the same shape: take the
+ * action's `logs`/`signal`, push into the log, and hook teardown.
  */
-export const createProc = (logs, signal) => (name, opts) => {
+export const createProc = (logs, signal, snapshots) => (name, opts) => {
     // quiet: zx must not echo the child's output to our terminal — the collector
     // owns all output (otherwise every line prints twice: raw from zx, formatted
     // from the drain). Caller opts can still override.
@@ -64,7 +63,7 @@ export const createProc = (logs, signal) => (name, opts) => {
         // spread sits before `cwd` so this resolved value wins even when opts omits
         // it). This is the "where" that makes a launch line reproducible.
         const cwd = opts?.cwd ?? process.cwd();
-        const snap = captureSnapshot(`proc-${name}-start`, { cmd: child.cmd, ...safeOpts, cwd });
+        const snap = snapshots.captureJson(`proc-${name}-start`, { cmd: child.cmd, ...safeOpts, cwd });
         logs.append({
             source: name,
             level: "event",

package/dist/utils/format.d.ts

@@ -0,0 +1,9 @@
+/** Zero-pad a number to `width` digits (e.g. `pad(7) → "07"`). */
+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).
+ */
+export declare const hms: (d: Date, sep?: string) => string;

package/dist/utils/format.js

@@ -0,0 +1,9 @@
+/** Zero-pad a number to `width` digits (e.g. `pad(7) → "07"`). */
+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).
+ */
+export const hms = (d, sep = ":") => `${pad(d.getHours())}${sep}${pad(d.getMinutes())}${sep}${pad(d.getSeconds())}`;

package/dist/utils/serialize.d.ts

@@ -0,0 +1,2 @@
+/** Serialize a value for a snapshot file, tolerating circular refs / non-JSON values. */
+export declare const serialize: (value: unknown) => string;

package/dist/utils/serialize.js

@@ -0,0 +1,12 @@
+/** Serialize a value for a snapshot file, tolerating circular refs / non-JSON values. */
+export 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));
+    }
+};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "omkit",
-  "version": "0.0.8",
+  "version": "0.0.10",
   "description": "A tiny runtime for developer workflows: typed actions that pass runtime capabilities and emit typed events, under one run and one shared log. The operational/runtime layer to tskb's knowledge layer.",
   "type": "module",
   "main": "./dist/index.js",

package/dist/core/action.js

@@ -1,188 +0,0 @@
-import { events } from "./events.js";
-import { createProc } from "./process.js";
-import { fingerprint, read, write, resolvePaths } from "./folder-cache.js";
-import { artifactsFolder } from "./output.js";
-/** A promise paired with its settlers, for the set-once handle. */
-const deferred = () => {
-    let resolve;
-    let reject;
-    const promise = new Promise((res, rej) => {
-        resolve = res;
-        reject = rej;
-    });
-    return { promise, resolve, reject };
-};
-/** Duck-type an exit code off a thrown error (zx's ProcessOutput, command's exit error). */
-const exitCodeOf = (error) => {
-    const code = error?.exitCode;
-    return typeof code === "number" ? code : undefined;
-};
-/**
- * A promise for the next emit of `key`. It races the event against the
- * instance's terminal events: if the action errors first it rejects with that
- * error, and if it completes (`done`) without ever emitting `key` it rejects too
- * — so an awaiter can never hang. A retained snapshot resolves it immediately.
- */
-const awaitEvent = (emitter, name, key) => new Promise((resolve, reject) => {
-    const offs = [];
-    let settled = false;
-    // First of [the event | error | done] to fire wins; the rest are unsubscribed.
-    const settle = (act) => {
-        if (settled)
-            return;
-        settled = true;
-        for (const off of offs)
-            off();
-        act();
-    };
-    // listenOnce is keyed by E; the system keys (error/done) are always present
-    // on an instance's event map, so reach them through a loosened view.
-    const listen = emitter.listenOnce;
-    offs.push(listen(key, (payload) => settle(() => resolve(payload))));
-    if (key !== "error") {
-        offs.push(listen("error", (err) => settle(() => reject(err))));
-    }
-    if (key !== "done") {
-        offs.push(listen("done", () => settle(() => reject(new Error(`${name}: settled before "${String(key)}"`)))));
-    }
-    // A retained snapshot fires a listen synchronously during registration; if
-    // that already settled us, drop any listeners registered afterwards.
-    if (settled)
-        for (const off of offs)
-            off();
-});
-/** Assembles an {@link Action} from a name and its implementation. */
-const build = (name, exec) => {
-    const create = (...args) => {
-        // The emitter covers declared + system events; `ctx.emit` is narrowed to the
-        // declared ones, while the framework emits done/error through the same bus.
-        const emitter = events(name);
-        const emit = emitter.emit;
-        // Loosely typed for the framework's own emits (sidesteps EmitArgs for void results).
-        const systemEmit = emitter.emit;
-        // The handle lives on the instance as a set-once promise: `attach` resolves
-        // it, `instance.ref` awaits it. A second attach is a no-op (promise settled).
-        // If the action settles without ever attaching, `start` below settles it too
-        // (resolve on success, reject on error) so `ref` can't hang.
-        const handle = deferred();
-        // Attaching is a one-time lifecycle moment: resolve `ref` and emit `attached`
-        // (the *fact* the action became controllable — not the handle, which is just
-        // functions). Guarded so a second attach neither re-emits nor re-resolves.
-        let attached = false;
-        const attach = (value) => {
-            if (attached)
-                return;
-            attached = true;
-            handle.resolve(value);
-            systemEmit("attached");
-        };
-        // Most actions have a `void` handle and no one awaits `ref`; mark the promise
-        // handled so a settle-time rejection on such an instance doesn't surface as an
-        // unhandled rejection. Real awaiters of `ref` still receive the rejection.
-        void handle.promise.catch(() => { });
-        // The action's Outcome as a set-once promise. `start` resolves it (success or
-        // failure); `instance.done` / `once("done")` read it. It never rejects.
-        const settled = deferred();
-        const instance = {
-            name,
-            args,
-            ref: handle.promise,
-            done: settled.promise,
-            start: (system) => 
-            // `Promise.resolve().then` normalizes a sync result and routes a sync
-            // throw to the `error` path, so exec may be sync or async.
-            Promise.resolve()
-                .then(() => exec({
-                ...system,
-                emit,
-                attach,
-                proc: createProc(system.logs, system.signal),
-                artifactsFolder: artifactsFolder(),
-            }, ...args))
-                .then((result) => {
-                const outcome = { ok: true, value: result };
-                settled.resolve(outcome);
-                systemEmit("done", outcome);
-                // Settle `ref` if the action finished without attaching, so awaiters
-                // resolve (with `undefined` for the default void handle) rather than
-                // hang. Idempotent — a no-op when a handle was already attached.
-                handle.resolve(undefined);
-                return outcome;
-            }, (error) => {
-                const exitCode = exitCodeOf(error);
-                const outcome = exitCode === undefined ? { ok: false, error } : { ok: false, error, exitCode };
-                // `error` first, so a pending `once(<declaredEvent>)` rejects on it
-                // (settled before its event) rather than resolving on `done`.
-                systemEmit("error", error);
-                settled.resolve(outcome);
-                systemEmit("done", outcome);
-                // The action failed, so its handle will never arrive — reject `ref`
-                // with the same error instead of leaving awaiters hung. No-op if a
-                // handle was already attached before the failure.
-                handle.reject(error);
-                // Resolve (never rethrow): failure is the Outcome, not a rejection.
-                return outcome;
-            }),
-            on(key, handler) {
-                emitter.listen(key, handler);
-            },
-            once(key) {
-                // `done` always fires with the Outcome and never "fails" the await, so it
-                // reads straight from the settled promise; other keys race via awaitEvent.
-                return (key === "done"
-                    ? settled.promise
-                    : awaitEvent(emitter, name, key));
-            },
-            // Wrap this instance in a fresh one (reusing the engine for its own
-            // emitter/ref/on/once) that fingerprints `paths` and either skips or
-            // runs+records. The wrapper keeps this action's `name`, so log lines and
-            // the `launch <name>` line are unchanged. It forwards its injected
-            // logs/signal straight into the inner action's `start`.
-            withCache(...paths) {
-                // Validate + canonicalize eagerly here (at the call site), not lazily
-                // inside the run — a relative path fails fast where it's written, and
-                // the resolved paths give a stable cache key regardless of spelling.
-                const targets = resolvePaths(paths);
-                return action(name).run(async (ctx) => {
-                    const fp = await fingerprint(targets);
-                    if ((await read(targets)) === fp) {
-                        ctx.logs.append({ source: name, level: "info", message: "cached, skipping" });
-                        return undefined;
-                    }
-                    const outcome = await instance.start({ logs: ctx.logs, signal: ctx.signal });
-                    // Re-throw the inner failure so the wrapper fails too (the framework
-                    // re-wraps it into this wrapper's own Outcome); only record on success.
-                    if (!outcome.ok)
-                        throw outcome.error;
-                    await write(targets, fp);
-                    return outcome.value;
-                })();
-            },
-        };
-        return instance;
-    };
-    return Object.assign(create, { actionName: name });
-};
-const builder = (name) => ({
-    emits: () => builder(name),
-    ref: () => builder(name),
-    run: (exec) => build(name, exec),
-});
-/**
- * Defines an action. Always returns a builder; provide the implementation via
- * `.run(…)`, optionally after declaring events and/or a handle:
- *
- *   action("Build").run(async (ctx, opts) => { … })       // no declared events / handle
- *   action("Watch")                                       // typed events + handle
- *     .emits<{ create: string }>()
- *     .ref<{ rescan(): void }>()
- *     .run((ctx, opts) => { ctx.emit(…); ctx.attach(…); … })
- *
- * `.run(…)` yields a callable that, when invoked, constructs an
- * {@link ActionInstance} (deferred — the run executes it). Instances expose
- * chainable `.on` / `.once` (declared events plus `done`/`error`); the attached
- * handle is awaited via `instance.ref`.
- */
-export function action(name) {
-    return builder(name);
-}

package/dist/core/folder-cache.d.ts

@@ -1,39 +0,0 @@
-/**
- * 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 declare const cacheDir: string;
-/**
- * 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 declare const resolvePaths: (paths: string[]) => string[];
-/**
- * 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 declare const fingerprint: (paths: string[]) => Promise<string>;
-/**
- * Reads the fingerprint stored for these targets, or `undefined` when there's
- * no cache (absent, unreadable, or malformed — all treated as a miss).
- */
-export declare const read: (paths: string[]) => Promise<string | 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 declare const write: (paths: string[], fp: string) => Promise<void>;