omkit 0.0.15 → 0.1.0

package/dist/core/ExecutionTree.js

@@ -0,0 +1,320 @@
+import path from "node:path";
+import { newUuid, makeId } from "../foundation/ids.js";
+import { fsSafe } from "../foundation/fsSafe.js";
+import { defer } from "../foundation/Deferred.js";
+import { LogStore } from "../output/log/LogStore.js";
+import { RunFolder } from "../output/folder/RunFolder.js";
+import { RawStream } from "../output/log/RawStream.js";
+import { SnapshotStore } from "../output/snapshot/SnapshotStore.js";
+import { ConsoleCapture } from "../output/console/ConsoleCapture.js";
+import { LiveRenderer } from "../output/LiveRenderer.js";
+import { writeNodeLogs } from "../output/writers/NodeLogWriter.js";
+import { writeRollup } from "../output/writers/RollupWriter.js";
+import { writeResult } from "../output/writers/ResultWriter.js";
+import { ActionRun } from "./ActionRun.js";
+import { procRegistry } from "../system/proc.js";
+import { currentNode } from "./context.js";
+/**
+ * The run: a module singleton that owns the log store, the run folder, the node
+ * registry, and the process-wide teardown. `launch` creates a child node under the
+ * ambient current action and runs it; `runRoot` runs the `om` body as the root and
+ * drives the whole thing to `finalize`, which always produces the artifacts.
+ */
+export class ExecutionTree {
+    static current = null;
+    /** The most recent run — kept for test/debug introspection (not nulled at finalize). */
+    static last = null;
+    /** The ambient-run guard: an action can only run inside a root `om(...)`. */
+    static require() {
+        if (!ExecutionTree.current) {
+            throw new Error("no active om() run — an action can only run inside a root om(...)");
+        }
+        return ExecutionTree.current;
+    }
+    /** For tests: drop the singleton so the next `om(...)` starts clean. */
+    static reset() {
+        ExecutionTree.current = null;
+    }
+    store = new LogStore();
+    folder = new RunFolder();
+    root;
+    rawStream;
+    consoleCapture;
+    snapshotStore = new SnapshotStore(this.folder);
+    registry = [];
+    unsettled = new Set();
+    originalLog = console.log.bind(console);
+    streaming;
+    liveRendering;
+    assertionsPassed = 0;
+    assertionsFailed = 0;
+    faults = [];
+    static graceMs = 5000; // teardown waits this long for nodes to settle, then finalizes anyway
+    phase = "open";
+    // Memoizes the in-flight finalize work so the grace timer's fire-and-forget call
+    // and runRoot's awaited call share (and both wait on) the same execution — a plain
+    // boolean guard would let the second caller return early while the first is still
+    // mid-flight (writes/uninstall not yet done), resolving `om()` too soon.
+    finalizing;
+    graceTimer;
+    teardownGrace = defer();
+    onSigint = () => this.teardown("interrupted (SIGINT)");
+    // Process hooks — installed at run start, removed at finalize (they must not outlive the run).
+    onUncaught = (e) => this.onFatal("uncaughtException", e);
+    onUnhandled = (e) => this.onFatal("unhandledRejection", e);
+    constructor() {
+        this.folder.ensure();
+        this.root = new ActionRun({
+            ...this.nodeDeps(),
+            name: "main",
+            uuid: newUuid(),
+            id: "main",
+            path: "main",
+            parentId: null,
+            parentSignal: null,
+            bubble: () => { }, // the root has no parent to bubble into
+        });
+        this.registry.push(this.root);
+        this.rawStream = new RawStream(this.rawStreamPath());
+        this.consoleCapture = new ConsoleCapture(this.store, () => (currentNode.getStore() ?? this.root).toRef());
+        ExecutionTree.last = this;
+    }
+    /** Launch an instance under the ambient current node (or the root). */
+    launch(spec) {
+        if (this.phase !== "open") {
+            throw new Error(`cannot launch ${spec.name}: the run is "${this.phase}", not "open"`);
+        }
+        const parent = currentNode.getStore() ?? this.root;
+        const uuid = newUuid();
+        const id = makeId(spec.name, uuid);
+        const nodePath = `${parent.path}/${id}`;
+        const node = new ActionRun({
+            ...this.nodeDeps(),
+            name: spec.name,
+            uuid,
+            id,
+            path: nodePath,
+            parentId: parent.id,
+            parentSignal: parent.signal,
+            // The child folds its milestones (events/asserts/snapshots/done, icon-prefixed)
+            // into the parent's log, attributed to this child's id.
+            bubble: (message) => this.append(parent, "child", id, message),
+        });
+        parent.children.push(node);
+        this.registry.push(node);
+        // Launch reference — the parent's pointer to the child's own (absolute) log.
+        this.append(parent, "child", "launch", `→ ${id} · ${this.logFile(nodePath)}`);
+        for (const t of spec.tags)
+            node.tag(t);
+        const promise = currentNode.run(node, () => node.run(spec.body, spec.args));
+        this.trackNode(promise);
+        return node;
+    }
+    append(node, level, source, message) {
+        this.store.append({ nodeId: node.id, path: node.path, level, source, message });
+    }
+    /** The shared services every node is built with (log store, snapshots, assert tally). */
+    nodeDeps() {
+        return {
+            store: this.store,
+            snapshots: this.snapshotStore,
+            artifactsFolder: this.folder.path(),
+            onAssert: (pass, actionPath, message) => this.recordAssert(pass, actionPath, message),
+            onUnhandledFailure: (actionPath, error) => {
+                this.recordFault(actionPath, error);
+                this.teardown(`${actionPath} failed`);
+            },
+        };
+    }
+    recordFault(action, error) {
+        this.faults.push({ action, error: messageOf(error) });
+    }
+    recordAssert(pass, actionPath, message) {
+        if (pass) {
+            this.assertionsPassed++;
+            return;
+        }
+        this.assertionsFailed++;
+        // A failure during teardown is cascade, not a real fault.
+        if (!this.root.signal.aborted) {
+            this.recordFault(actionPath, `assertion failed: ${message}`);
+        }
+    }
+    /** Tear the whole run down (aborts the root, cascading to every node). Idempotent. */
+    cancel() {
+        this.teardown("cancelled");
+    }
+    /**
+     * The sole teardown path: `open → closing`, narrate the reason once, abort the root
+     * (cascading to every node — procs killed, waits unblocked, daemons stopped). Later
+     * calls are no-ops. A single grace timer guarantees finalize even if a node's cleanup
+     * wedges after its proc is already dead, so the run always writes its log.
+     */
+    teardown(reason) {
+        if (this.phase !== "open")
+            return;
+        this.phase = "closing";
+        this.narrate(`tearing down · ${reason}`);
+        this.root.cancel();
+        // Not unref'd: it must hold the process alive long enough to finalize.
+        this.graceTimer = setTimeout(() => {
+            this.teardownGrace.resolve(); // break drive()'s wait on a node that won't settle
+            void this.finalize(); // …and finalize even if drive() was never reached (hung body)
+        }, ExecutionTree.graceMs);
+    }
+    /** An escaped throw/rejection: log it, record it (unless already tearing down), tear down. */
+    onFatal(kind, error) {
+        this.store.append({
+            nodeId: "process",
+            path: "process",
+            level: "error",
+            source: kind,
+            message: messageOf(error),
+        });
+        if (!this.root.signal.aborted)
+            this.recordFault(kind, error);
+        this.teardown(kind);
+    }
+    /** Run the `om` body as the root node, then drive to finalize. */
+    async runRoot(body) {
+        this.narrate(`run started · ${this.folder.name()}`);
+        this.consoleCapture.install();
+        // `on`, not `once`: SIGINT must stay caught for the life of the run so it can't
+        // fall through to Node's hard-kill default before finalize writes the log.
+        process.on("SIGINT", this.onSigint);
+        process.on("uncaughtException", this.onUncaught);
+        process.on("unhandledRejection", this.onUnhandled);
+        this.streaming = this.rawStream.run(this.store);
+        // Live, curated milestones to the terminal, through the pre-patch writer.
+        this.liveRendering = new LiveRenderer(this.originalLog).run(this.store);
+        const rootPromise = currentNode.run(this.root, () => this.root.run(body, []));
+        this.trackNode(rootPromise);
+        await rootPromise;
+        await this.drive();
+        await this.finalize();
+    }
+    /**
+     * Track a launched node's `run()` promise until it settles (drives `drive()`'s
+     * wait). `run()` itself never rejects — the node's own constructor already
+     * swallows its settled rejection (via the private field, not the `.result` getter,
+     * so it doesn't mark the node observed and defeat the unobserved-failure check).
+     */
+    trackNode(promise) {
+        const tracked = promise.finally(() => this.unsettled.delete(tracked));
+        this.unsettled.add(tracked);
+    }
+    async drive() {
+        // Drain every launched node. Teardown aborts them (procs reaped, waits unblocked),
+        // so they settle and this returns. The grace timer resolves `teardownGrace` if a
+        // node's own cleanup wedges — the OS process is already dead by then.
+        while (this.unsettled.size > 0) {
+            const graced = await Promise.race([
+                Promise.allSettled([...this.unsettled]).then(() => false),
+                this.teardownGrace.promise.then(() => true),
+            ]);
+            if (graced)
+                break;
+        }
+    }
+    finalize() {
+        if (!this.finalizing)
+            this.finalizing = this.finalizeOnce();
+        return this.finalizing;
+    }
+    async finalizeOnce() {
+        if (this.phase === "open")
+            this.teardown("completed");
+        this.phase = "closed";
+        if (this.graceTimer)
+            clearTimeout(this.graceTimer);
+        // Reap any Windows grandchild a mashed Ctrl+C orphaned before killTree could reach it
+        // (no-op elsewhere, and when nothing was tracked).
+        procRegistry.sweep();
+        this.narrate("finished");
+        this.store.close();
+        await this.streaming;
+        await this.liveRendering;
+        const flat = this.registry.map((node) => this.nodeView(node));
+        const entries = this.store.entries();
+        const at = (name) => path.join(this.folder.path(), name);
+        const assertSummary = `⊨ ${this.assertionsPassed} passed · ⊭ ${this.assertionsFailed} failed`;
+        await writeNodeLogs(flat, entries);
+        await writeRollup(at("events.log"), flat, entries, (e) => e.level === "event");
+        await writeRollup(at("asserts.log"), flat, entries, (e) => e.level === "assert", assertSummary);
+        await writeRollup(at("snapshots.log"), flat, entries, (e) => e.level === "snapshot");
+        await writeResult(at("result.json"), this.runView());
+        // Only now let go of the process hooks — a Ctrl+C during the writes must still be
+        // caught (as a no-op) so it can't fall through to Node's kill-without-log default.
+        process.off("SIGINT", this.onSigint);
+        process.off("uncaughtException", this.onUncaught);
+        process.off("unhandledRejection", this.onUnhandled);
+        this.consoleCapture.uninstall();
+        ExecutionTree.current = null;
+        this.printSummary(at, assertSummary);
+        if (!this.verdictOk())
+            process.exitCode = 1;
+    }
+    /** The end-of-run links + assert summary, to the terminal (files are already written). */
+    printSummary(at, assertSummary) {
+        const term = this.originalLog;
+        term("");
+        term(`om → ${this.folder.path()}`);
+        term(`  main log  → ${at("main.log")}`);
+        term(`  events    → ${at("events.log")}`);
+        term(`  asserts   → ${at("asserts.log")}   ${assertSummary}`);
+        term(`  snapshots → ${at("snapshots.log")}`);
+    }
+    verdictOk() {
+        return this.faults.length === 0;
+    }
+    nodeView(node) {
+        return {
+            id: node.id,
+            uuid: node.uuid,
+            name: node.name,
+            path: node.path,
+            parentId: node.parentId,
+            tags: [...node.tags],
+            args: [...node.args],
+            status: node.status,
+            startedAt: node.startedAt,
+            endedAt: node.endedAt,
+            duration: node.duration,
+            logFile: this.logFile(node.path),
+            children: node.children.map((child) => this.nodeView(child)),
+        };
+    }
+    /** Test seam: the projected run view (same object written to result.json). */
+    runViewForTest() {
+        return this.runView();
+    }
+    runView() {
+        return {
+            ok: this.faults.length === 0,
+            failures: [...this.faults],
+            assertions: { passed: this.assertionsPassed, failed: this.assertionsFailed },
+            startedAt: this.root.startedAt,
+            endedAt: this.root.endedAt,
+            duration: this.root.duration,
+            rawStream: this.rawStreamPath(),
+            root: this.nodeView(this.root),
+        };
+    }
+    /**
+     * Absolute `.log` path for a node — root is `main.log`, children drop the `main/`
+     * prefix. Each id segment is sanitized so names with filesystem-illegal characters
+     * (e.g. `TSKB:root:watch:docs`) still produce a valid path.
+     */
+    logFile(nodePath) {
+        const rel = nodePath === "main" ? "main" : nodePath.slice("main/".length);
+        const safe = rel.split("/").map(fsSafe).join(path.sep);
+        return path.join(this.folder.path(), `${safe}.log`);
+    }
+    rawStreamPath() {
+        return path.join(this.folder.path(), "raw.jsonl");
+    }
+    narrate(message) {
+        this.store.append({ nodeId: "run", path: "run", level: "run", source: "run", message });
+    }
+}
+const messageOf = (error) => error instanceof Error ? (error.stack ?? error.message) : String(error);

package/dist/core/action.d.ts

@@ -0,0 +1,6 @@
+import type { ActionBuilderEvents, NoEvents } from "./types.ts";
+/**
+ * Define an action. Provide the impl via `.run(…)`, optionally after declaring
+ * events (`.emits<…>()`) and/or an imperative handle (`.ref<…>()`).
+ */
+export declare function action(name: string): ActionBuilderEvents<NoEvents, void>;

package/dist/core/action.js

@@ -0,0 +1,72 @@
+import { ExecutionTree } from "./ExecutionTree.js";
+import { FolderCache } from "../system/fs/FolderCache.js";
+/**
+ * A constructed-but-not-yet-run action. Inert: it only holds the name, body, args,
+ * and any tags buffered before launch. `exec()` hands it to the tree, which creates
+ * the node under the ambient current action and runs it.
+ */
+class Instance {
+    name;
+    body;
+    args;
+    tags = [];
+    constructor(name, body, args) {
+        this.name = name;
+        this.body = body;
+        this.args = args;
+    }
+    tag(name) {
+        this.tags.push(name);
+        return this;
+    }
+    withCache(...paths) {
+        // Validate + canonicalize eagerly here (fails fast on a relative path).
+        const targets = FolderCache.resolvePaths(paths);
+        const innerBody = this.body;
+        const innerArgs = this.args;
+        // Wrap in a fresh instance that keeps this action's name/tags and, at run time,
+        // fingerprints the inputs — skipping (return undefined) on a hit, else running
+        // the inner body and recording the fingerprint on success.
+        const body = (async (ctx, ...args) => {
+            const fp = await FolderCache.fingerprint(targets);
+            if ((await FolderCache.read(targets)) === fp) {
+                console.log("cached, skipping");
+                return undefined;
+            }
+            const result = (await innerBody(ctx, ...args));
+            await FolderCache.write(targets, fp);
+            return result;
+        });
+        const cached = new Instance(this.name, body, innerArgs);
+        cached.tags.push(...this.tags);
+        return cached;
+    }
+    exec() {
+        return ExecutionTree.require().launch(this);
+    }
+}
+/** The builder returned by `action(name)`: declare events/handle, then bind the impl. */
+class Builder {
+    name;
+    constructor(name) {
+        this.name = name;
+    }
+    emits() {
+        return new Builder(this.name);
+    }
+    ref() {
+        return new Builder(this.name);
+    }
+    run(body) {
+        const name = this.name;
+        const create = (...args) => new Instance(name, body, args);
+        return Object.assign(create, { actionName: name });
+    }
+}
+/**
+ * Define an action. Provide the impl via `.run(…)`, optionally after declaring
+ * events (`.emits<…>()`) and/or an imperative handle (`.ref<…>()`).
+ */
+export function action(name) {
+    return new Builder(name);
+}

package/dist/core/context.d.ts

@@ -0,0 +1,9 @@
+import { AsyncLocalStorage } from "node:async_hooks";
+import type { ActionRun } from "./ActionRun.ts";
+/**
+ * Holds the **current node** for the duration of an exec. Read by
+ * `instance.exec()` (to find its parent) and by console capture (to attribute a
+ * `console.*` line) — the single ambient mechanism that replaces `nod` and makes
+ * scoping compose without threading anything by hand.
+ */
+export declare const currentNode: AsyncLocalStorage<ActionRun<unknown, object, unknown>>;

package/dist/core/context.js

@@ -0,0 +1,8 @@
+import { AsyncLocalStorage } from "node:async_hooks";
+/**
+ * Holds the **current node** for the duration of an exec. Read by
+ * `instance.exec()` (to find its parent) and by console capture (to attribute a
+ * `console.*` line) — the single ambient mechanism that replaces `nod` and makes
+ * scoping compose without threading anything by hand.
+ */
+export const currentNode = new AsyncLocalStorage();

package/dist/core/om.d.ts

@@ -0,0 +1,9 @@
+import type { Awaitable, OmContext } from "./types.ts";
+/**
+ * Runs a linear orchestration as the root of a fresh {@link ExecutionTree}. The
+ * body runs inside the root node's ambient scope, so any `instance.exec()` /
+ * `step(...)` / `console.*` it reaches attributes correctly. Resolves once the run
+ * has torn down and produced its artifacts; never rejects (failures are recorded in
+ * the tree and set the exit code).
+ */
+export declare function om(body: (ctx: OmContext) => Awaitable<void>): Promise<void>;

package/dist/core/om.js

@@ -0,0 +1,25 @@
+import { ExecutionTree } from "./ExecutionTree.js";
+/**
+ * Runs a linear orchestration as the root of a fresh {@link ExecutionTree}. The
+ * body runs inside the root node's ambient scope, so any `instance.exec()` /
+ * `step(...)` / `console.*` it reaches attributes correctly. Resolves once the run
+ * has torn down and produced its artifacts; never rejects (failures are recorded in
+ * the tree and set the exit code).
+ */
+export function om(body) {
+    if (ExecutionTree.current) {
+        throw new Error("an om() run is already active in this process");
+    }
+    const tree = new ExecutionTree();
+    ExecutionTree.current = tree;
+    const rootBody = (ctx) => body({
+        signal: ctx.signal,
+        logs: ctx.logs,
+        tag: ctx.tag,
+        cancel: () => tree.cancel(),
+        assert: ctx.assert,
+        snapshot: ctx.snapshot,
+        artifactsFolder: ctx.artifactsFolder,
+    });
+    return tree.runRoot(rootBody);
+}

package/dist/core/step.d.ts

@@ -0,0 +1,9 @@
+import type { ActionContext, Awaitable } from "./types.ts";
+/**
+ * An inline anonymous action: creates a child node under the ambient current
+ * action and runs `fn` as that node — own id/path/log, tags, error boundary — with
+ * no reusable definition. `await step("seed-db", async () => …)` resolves the
+ * result (throws on failure/cancel). For reusable, typed, event/handle-bearing
+ * units use `action(...)`.
+ */
+export declare function step<Result>(name: string, fn: (ctx: ActionContext) => Awaitable<Result>): Promise<Result>;

package/dist/core/step.js

@@ -0,0 +1,18 @@
+import { action } from "./action.js";
+/**
+ * An inline anonymous action: creates a child node under the ambient current
+ * action and runs `fn` as that node — own id/path/log, tags, error boundary — with
+ * no reusable definition. `await step("seed-db", async () => …)` resolves the
+ * result (throws on failure/cancel). For reusable, typed, event/handle-bearing
+ * units use `action(...)`.
+ */
+export function step(name, fn) {
+    return action(name)
+        .run(fn)()
+        .exec()
+        .result.then((r) => {
+        if (!r.ok)
+            throw r.error;
+        return r.value;
+    });
+}

package/dist/core/types.d.ts

@@ -0,0 +1,128 @@
+import type { Emitter, EventHandler } from "../foundation/events.ts";
+import type { ReadableLog } from "../foundation/LogEntry.ts";
+import type { Proc } from "../system/proc.ts";
+/** A value an action's exec may return: a result, or a promise of one. */
+export type Awaitable<T> = T | Promise<T>;
+/** An action that declares no events. */
+export type NoEvents = Record<never, never>;
+/** An activity's terminal outcome: a value on success, an error on failure/cancel. Never thrown. */
+export type Outcome<T> = {
+    ok: true;
+    value: T;
+} | {
+    ok: false;
+    error: unknown;
+};
+/** A node's lifecycle state, mirrored into `result.json`. */
+export type NodeStatus = "running" | "ok" | "failed" | "cancelled";
+/**
+ * The lifecycle events every action emits on top of its declared ones — so key
+ * moments are first-class signals rather than log-scraping.
+ */
+export interface SystemEvents<Result> {
+    attached: void;
+    done: Result;
+    error: unknown;
+}
+/** The full event map a run exposes: declared events plus the system ones. */
+export type InstanceEvents<Events extends object, Result> = Events & SystemEvents<Result>;
+/** What an action's `exec` receives. `logs` is read-only; output is via `console.*`. */
+export interface ActionContext<Events extends object = NoEvents, Handle = void> {
+    /** This node's abort signal — honor it to stop early. */
+    readonly signal: AbortSignal;
+    /** The combined run log, read-only (subscribe/observe; never append). */
+    readonly logs: ReadableLog;
+    /** Emit one of this action's declared events (also logged onto the timeline). */
+    readonly emit: Emitter<Events>["emit"];
+    /** Publish this action's imperative handle, resolving its run's `.ref`. */
+    readonly attach: (handle: Handle) => void;
+    /** Tag this run (timeline-visible; accumulates onto the node). */
+    readonly tag: (name: string) => void;
+    /** Assert an invariant: logs a `⊨` line and tallies into the verdict. Never throws. */
+    readonly assert: (condition: boolean, message: string) => void;
+    /** Capture a JSON snapshot; drops a timeline line and resolves the file's absolute path. */
+    readonly snapshot: (name: string, value: unknown) => Promise<string>;
+    /** Absolute path to this run's output folder — write artifacts (screenshots, dumps, …) here. */
+    readonly artifactsFolder: string;
+    /** Spawn child processes bound to this action (output → this node's log, killed on teardown). */
+    readonly proc: Proc;
+}
+/** What the `om` body receives — the run-level counterpart to {@link ActionContext}. */
+export interface OmContext {
+    /** The run's (root) abort signal. */
+    readonly signal: AbortSignal;
+    /** Tag the root run. */
+    readonly tag: (name: string) => void;
+    /** Tear the whole run down. */
+    readonly cancel: () => void;
+    /** The combined run log, read-only. */
+    readonly logs: ReadableLog;
+    /** Assert an invariant from the body (attributed to the root). Never throws. */
+    readonly assert: (condition: boolean, message: string) => void;
+    /** Capture a run-level JSON snapshot; resolves the file's absolute path. */
+    readonly snapshot: (name: string, value: unknown) => Promise<string>;
+    /** Absolute path to this run's output folder — write run-level artifacts here. */
+    readonly artifactsFolder: string;
+}
+/**
+ * A launched action: the live node's awaitable/observable surface. `.result` always
+ * resolves an {@link Outcome} (never throws); `.ref` rejects on failure/cancel.
+ */
+export interface RunHandle<Result = unknown, Events extends object = NoEvents, Handle = void> {
+    readonly id: string;
+    /** The terminal outcome; always resolves (never rejects). Reading it observes the failure. */
+    readonly result: Promise<Outcome<Result>>;
+    /** The attached handle; rejects on failure/cancel. */
+    readonly ref: Promise<Handle>;
+    /**
+     * Handle a fire-and-forget activity's failure: attach a handler so a crash runs it
+     * instead of tearing the run down. Observes the failure; chainable; attach in the
+     * same tick as `.exec()`. Not called on cancellation.
+     */
+    handleFailure(handler: (error: unknown) => void): this;
+    /** Subscribe to every emit of a declared/system event (`done`/`error`/`attached`). */
+    on<K extends keyof InstanceEvents<Events, Result>>(key: K, handler: EventHandler<InstanceEvents<Events, Result>[K]>): void;
+    /** Next emit of `key`; resolves `undefined` if the node settles first (never rejects). */
+    once<K extends keyof InstanceEvents<Events, Result>>(key: K): Promise<InstanceEvents<Events, Result>[K] | undefined>;
+    /** Tag this run; chainable. */
+    tag(name: string): this;
+    /** Abort this node and its subtree. */
+    cancel(): void;
+}
+/** A constructed-but-not-yet-run action: what calling an `Action` produces. */
+export interface ActionInstance<Result = unknown, Events extends object = NoEvents, Handle = void> {
+    readonly name: string;
+    readonly args: readonly unknown[];
+    /** Buffer a tag before launch; applied onto the node at creation. Chainable. */
+    tag(name: string): this;
+    /**
+     * Gate this action on its **input** files/folders (absolute paths): skip running
+     * when they're unchanged since the last successful run (a hit resolves
+     * `undefined` and logs `cached, skipping`). Chain before launching.
+     */
+    withCache(...paths: string[]): ActionInstance<Result | undefined, Events, Handle>;
+    /** Launch under the ambient current node; returns the live {@link RunHandle}. */
+    exec(): RunHandle<Result, Events, Handle>;
+}
+/** Any constructed instance, whatever its result/events/handle. */
+export type AnyActionInstance = ActionInstance<unknown, object, unknown>;
+/** A callable produced by `action`: invoking it builds an {@link ActionInstance}. */
+export interface Action<Args extends unknown[], Result, Events extends object = NoEvents, Handle = void> {
+    (...args: Args): ActionInstance<Result, Events, Handle>;
+    readonly actionName: string;
+}
+/** Intermediate step from `action(name)`: declare events/handle, then provide the impl. */
+export interface ActionBuilderEvents<Events extends object, Handle = void> {
+    emits<E extends object>(): ActionBuilderEvents<E, Handle>;
+    ref<H>(): ActionBuilderEvents<Events, H>;
+    run<Args extends unknown[], Result>(body: (ctx: ActionContext<Events, Handle>, ...args: Args) => Awaitable<Result>): Action<Args, Result, Events, Handle>;
+}
+/** The exec signature bound by `.run(...)` (arg types erased at the boundary). */
+export type Exec<Events extends object, Handle, Result> = (ctx: ActionContext<Events, Handle>, ...args: never[]) => Awaitable<Result>;
+/** What the {@link ExecutionTree} needs to launch an instance — the shape an instance satisfies. */
+export interface LaunchSpec {
+    readonly name: string;
+    readonly args: readonly unknown[];
+    readonly tags: readonly string[];
+    readonly body: Exec<object, unknown, unknown>;
+}

package/dist/foundation/ActionRef.d.ts

@@ -0,0 +1,18 @@
+/**
+ * The identity carried wherever an action is pointed to — a log file's header, a
+ * rollup chunk header, a log-file reference. A plain data shape (no behavior) so
+ * both the `output` and `core` layers can use it without depending on each other.
+ * Rendered compactly as `name · path · [tags]`.
+ */
+export interface ActionRef {
+    /** `${name}_${shortId}`, or `main` for the root. */
+    readonly id: string;
+    /** The action's declared name. */
+    readonly name: string;
+    /** Ancestry of ids joined by `/` — `main/chromePage_9f3c/debug_77d1`. */
+    readonly path: string;
+    /** Accumulated tags at the point of reference. */
+    readonly tags: readonly string[];
+}
+/** Render an {@link ActionRef} for a header/reference line: `name · path · [a, b]`. */
+export declare const renderRef: (ref: ActionRef) => string;

package/dist/foundation/ActionRef.js

@@ -0,0 +1,5 @@
+/** Render an {@link ActionRef} for a header/reference line: `name · path · [a, b]`. */
+export const renderRef = (ref) => {
+    const tags = ref.tags.length ? ` · [${ref.tags.join(", ")}]` : "";
+    return `${ref.name} · ${ref.path}${tags}`;
+};

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

@@ -1,12 +1,10 @@
+/** A single-consumer async queue: `push` feeds it, `for await` drains it, `close` ends it. */
 export declare class AsyncQueue<T> implements AsyncIterable<T> {
     private readonly items;
     private readonly resolvers;
     private closed;
     push(item: T): void;
-    /**
-     * 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(): void;
     private next;
     [Symbol.asyncIterator](): AsyncIterator<T>;