omkit 0.0.8 → 0.0.10

package/dist/actions/chrome-page.d.ts

@@ -41,4 +41,4 @@ export interface ChromePageOptions {
  * teardown it closes the CDP connection *only* when it opened one — a handed-in
  * browser or window is left untouched for its owner to close.
  */
-export declare const chromePage: import("../core/action.ts").Action<[source: ChromePageSource | Promise<ChromePageSource>, opts?: ChromePageOptions | undefined], void, ChromePageEvents, Page>;
+export declare const chromePage: import("../index.ts").Action<[source: ChromePageSource | Promise<ChromePageSource>, opts?: ChromePageOptions | undefined], void, ChromePageEvents, Page>;

package/dist/actions/chrome-page.js

@@ -1,5 +1,5 @@
 import { chromium } from "playwright-core";
-import { action } from "../core/action.js";
+import { action } from "../orchestration/action/action.js";
 // Playwright's classes are structurally distinct by these methods; only Browser
 // has `contexts()`, only Page has `mainFrame()`, and a BrowserContext has
 // `newPage()` without either — enough to tell a handed-in handle apart.

package/dist/actions/command.d.ts

@@ -1,4 +1,4 @@
-import { type AnyActionInstance } from "../core/action.ts";
+import type { AnyActionInstance } from "../orchestration/action/types.ts";
 /** Tunes an action built with {@link command}. */
 export interface CommandOptions {
     /**

package/dist/actions/command.js

@@ -1,8 +1,7 @@
 import { spawn } from "node:child_process";
 import path from "node:path";
-import { action } from "../core/action.js";
-import { killTree } from "../core/process.js";
-import { captureSnapshot } from "../core/output.js";
+import { action } from "../orchestration/action/action.js";
+import { killTree } from "../system/process/process.js";
 /**
  * Build the literal part of a zx tagged template from a command string, so it
  * runs verbatim. zx only quotes interpolated args, not the template's `pieces` —
@@ -15,7 +14,7 @@ export function command(name, cmdOrFile, argsOrOptions, maybeOptions) {
     const direct = Array.isArray(argsOrOptions);
     const options = (direct ? maybeOptions : argsOrOptions) ?? {};
     if (direct) {
-        return action(name).run((ctx) => spawnDirect(ctx.logs, ctx.signal, name, cmdOrFile, argsOrOptions, options))();
+        return action(name).run((ctx) => spawnDirect(ctx.output.snapshots, ctx.logs, ctx.signal, name, cmdOrFile, argsOrOptions, options))();
     }
     return action(name).run(({ proc }) => {
         // path.resolve keeps an absolute cwd as-is and resolves a relative one
@@ -35,7 +34,7 @@ export function command(name, cmdOrFile, argsOrOptions, maybeOptions) {
  * log, and resolves when it exits (0 = ok; a non-zero exit is a genuine failure,
  * unless the run is tearing down, where the abort-kill is the reason).
  */
-const spawnDirect = (logs, signal, name, file, args, options) => {
+const spawnDirect = (snapshots, logs, signal, name, file, args, options) => {
     const cwd = path.resolve(options.cwd ?? ".");
     const source = options.label ?? name;
     // windowsHide keeps a stray console window from flashing for the child.
@@ -43,7 +42,7 @@ const spawnDirect = (logs, signal, name, file, args, options) => {
     const child = spawn(file, args, { cwd, windowsHide: true, env: options.env });
     // Mirror proc's launch line: a filterable milestone on the timeline, with the
     // structured args snapshotted and linked (see process.ts for the rationale).
-    const snap = captureSnapshot(`proc-${name}-start`, { cmd: file, args, cwd });
+    const snap = snapshots.captureJson(`proc-${name}-start`, { cmd: file, args, cwd });
     logs.append({
         source: name,
         level: "event",

package/dist/actions/healthcheck.d.ts

@@ -52,4 +52,4 @@ export interface HealthcheckEvents {
  * stall the loop) and the whole wait by the run's abort signal and an optional
  * `timeoutMs`, so teardown unblocks a pending probe instead of hanging.
  */
-export declare const healthcheck: import("../core/action.ts").Action<[opts?: HealthcheckOptions | undefined], HealthcheckResult, HealthcheckEvents, void>;
+export declare const healthcheck: import("../index.ts").Action<[opts?: HealthcheckOptions | undefined], HealthcheckResult, HealthcheckEvents, void>;

package/dist/actions/healthcheck.js

@@ -1,4 +1,4 @@
-import { action } from "../core/action.js";
+import { action } from "../orchestration/action/action.js";
 /**
  * Gate: polls an HTTP endpoint until it answers in a healthy way (status and,
  * optionally, body), then resolves with that probe and emits `healthy`. The

package/dist/actions/prompt.d.ts

@@ -50,5 +50,5 @@ export interface PromptEvents {
  * `answer` when settled (carrying whether it came from input, the default, or a
  * timeout).
  */
-export declare const prompt: import("../core/action.ts").Action<[opts?: PromptOptions | undefined], string, PromptEvents, string>;
+export declare const prompt: import("../index.ts").Action<[opts?: PromptOptions | undefined], string, PromptEvents, string>;
 export {};

package/dist/actions/prompt.js

@@ -1,5 +1,5 @@
 import { createInterface } from "node:readline/promises";
-import { action } from "../core/action.js";
+import { action } from "../orchestration/action/action.js";
 /** Normalize choices to `{ label, value }`. */
 const asChoices = (choices) => choices.map((c) => (typeof c === "string" ? { label: c, value: c } : c));
 /**

package/dist/actions/tail-log.d.ts

@@ -27,4 +27,4 @@ export interface TailLogOptions {
  * filters by name, like {@link import("./watch.ts").watch}. Runs until the run's
  * signal aborts, then closes the watcher (flushing any trailing partial line).
  */
-export declare const tailLog: import("../core/action.ts").Action<[target: string, opts?: TailLogOptions | undefined], void, import("../core/action.ts").NoEvents, void>;
+export declare const tailLog: import("../index.ts").Action<[target: string, opts?: TailLogOptions | undefined], void, import("../index.ts").NoEvents, void>;

package/dist/actions/tail-log.js

@@ -2,7 +2,7 @@ import { watch as fsWatch } from "node:fs";
 import { open, stat } from "node:fs/promises";
 import { basename, dirname, resolve } from "node:path";
 import { StringDecoder } from "node:string_decoder";
-import { action } from "../core/action.js";
+import { action } from "../orchestration/action/action.js";
 /**
  * Tails a (possibly not-yet-existing) text/log file and streams each appended
  * line into the run's combined log — the way `proc` streams a child's stdout, but

package/dist/actions/until-log.d.ts

@@ -1,4 +1,4 @@
-import type { LogEntry } from "../core/log-collector/LogsCollector.ts";
+import type { LogEntry } from "../output/log/LogsCollector.ts";
 /** Predicate over a log entry — return `true` for the entry to wait for. */
 export type LogMatcher = (entry: LogEntry) => boolean;
 export interface UntilLogOptions {
@@ -21,4 +21,4 @@ export interface UntilLogEvents {
  * run's abort signal (and an optional timeout), so teardown unblocks a pending
  * wait instead of hanging.
  */
-export declare const untilLog: import("../core/action.ts").Action<[matcher: LogMatcher, (UntilLogOptions | undefined)?], LogEntry, UntilLogEvents, void>;
+export declare const untilLog: import("../index.ts").Action<[matcher: LogMatcher, (UntilLogOptions | undefined)?], LogEntry, UntilLogEvents, void>;

package/dist/actions/until-log.js

@@ -1,4 +1,4 @@
-import { action } from "../core/action.js";
+import { action } from "../orchestration/action/action.js";
 /**
  * Gate: resolves with the first log entry the `matcher` accepts (and emits
  * `match`). Subscribes to the injected collector and races each read against the

package/dist/actions/watch-dir.d.ts

@@ -32,4 +32,4 @@ export interface WatchDirEvents {
  * event the *parent* fires for the target's name — when it does and the target
  * still exists, it was replaced (`removed` + `ready`).
  */
-export declare const watchDir: import("../core/action.ts").Action<[target: string, opts?: WatchDirOptions | undefined], void, WatchDirEvents, void>;
+export declare const watchDir: import("../index.ts").Action<[target: string, opts?: WatchDirOptions | undefined], void, WatchDirEvents, void>;

package/dist/actions/watch-dir.js

@@ -1,7 +1,7 @@
 import { existsSync, watch as fsWatch } from "node:fs";
 import { readdir, stat } from "node:fs/promises";
 import { basename, dirname, join, resolve } from "node:path";
-import { action } from "../core/action.js";
+import { action } from "../orchestration/action/action.js";
 /**
  * Watches a directory and emits per-file events on changes, surviving the folder
  * being deleted and recreated (e.g. a build that `rm -rf`s it first).

package/dist/actions/watch.d.ts

@@ -30,4 +30,4 @@ export interface WatchOptions {
  * Assumes the parent directory exists; watching when an ancestor is missing is
  * a later case.
  */
-export declare const watch: import("../core/action.ts").Action<[target: string, opts?: WatchOptions | undefined], void, import("../core/action.ts").NoEvents, void>;
+export declare const watch: import("../index.ts").Action<[target: string, opts?: WatchOptions | undefined], void, import("../index.ts").NoEvents, void>;

package/dist/actions/watch.js

@@ -1,7 +1,7 @@
 import { watch as fsWatch } from "node:fs";
 import { stat } from "node:fs/promises";
 import { basename, dirname, resolve } from "node:path";
-import { action } from "../core/action.js";
+import { action } from "../orchestration/action/action.js";
 /**
  * Watches a single file that may not exist yet, firing callbacks on its
  * transitions. Since `fs.watch` can't watch a missing path, it watches the

package/dist/index.d.ts

@@ -8,20 +8,16 @@
  * This is a curated public surface — internal helpers (the async queue, the log
  * renderer, marker prefixing) are intentionally not exported.
  */
-export { action } from "./core/action.ts";
-export type { Action, ActionBuilder, ActionInstance, AnyActionInstance, ActionContext, SystemGlobal, SystemEvents, InstanceEvents, NoEvents, Awaitable, Outcome, } from "./core/action.ts";
-export { run } from "./core/run.ts";
-export type { Spin, SpinResult, SpinState, ActionFailure } from "./core/run.ts";
-export { spin } from "./core/spin.ts";
-export type { Nod, SpinOptions, SpinContext, SpinBody } from "./core/spin.ts";
-export { events } from "./core/events.ts";
-export type { Emitter, EventHandler, EventMeta } from "./core/events.ts";
-export { createProc } from "./core/process.ts";
-export type { Proc } from "./core/process.ts";
-export { LogsCollector } from "./core/log-collector/LogsCollector.ts";
-export type { Logger, LogEntry, LogInput, SubscribeOptions, } from "./core/log-collector/LogsCollector.ts";
-export { log } from "./core/log-collector/global.ts";
-export { snapshot, captureSnapshot } from "./core/output.ts";
-export type { SnapshotRef } from "./core/output.ts";
-export { artifactsFolder } from "./core/output.ts";
-export { fingerprint, cacheDir } from "./core/folder-cache.ts";
+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 { 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";

package/dist/index.js

@@ -9,26 +9,24 @@
  * renderer, marker prefixing) are intentionally not exported.
  */
 // ── Actions ────────────────────────────────────────────────────────────────
-export { action } from "./core/action.js";
-// ── Spin (the run handle) ────────────────────────────────────────────────────
-export { run } from "./core/run.js";
+export { action } from "./orchestration/action/action.js";
 // ── Spin (linear orchestration) ──────────────────────────────────────────────
-export { spin } from "./core/spin.js";
+export { spin } from "./orchestration/spin/spin.js";
 // ── Events ─────────────────────────────────────────────────────────────────
-export { events } from "./core/events.js";
+export { events } from "./orchestration/events/events.js";
 // ── Child processes ────────────────────────────────────────────────────────
-export { createProc } from "./core/process.js";
+export { createProc } from "./system/process/process.js";
 // ── The log ────────────────────────────────────────────────────────────────
-export { LogsCollector } from "./core/log-collector/LogsCollector.js";
-export { log } from "./core/log-collector/global.js";
-// ── Snapshots ──────────────────────────────────────────────────────────────
-export { snapshot, captureSnapshot } from "./core/output.js";
-// ── Artifacts ────────────────────────────────────────────────────────────────
-// This run's output folder (absolute) — also on the `spin`/action `ctx`. Import
-// it directly for artifact-writing helpers that aren't inside an action.
-export { artifactsFolder } from "./core/output.js";
+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); exported for scripts that
-// want to inspect or manually invalidate the cache.
-export { fingerprint, cacheDir } from "./core/folder-cache.js";
+// 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";

package/dist/orchestration/action/action.d.ts

@@ -0,0 +1,23 @@
+import type { ActionBuilder, AnyActionInstance, NoEvents } from "./types.ts";
+/**
+ * If `value` is some action instance's `.ref` promise, the instance that owns it
+ * (the producer of that handle); otherwise `undefined`. Used by the run to verify
+ * a `.ref` dependency was launched before the action that consumes it.
+ */
+export declare const producerOfRef: (value: unknown) => AnyActionInstance | undefined;
+/**
+ * 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 declare function action(name: string): ActionBuilder<NoEvents, void>;

package/dist/orchestration/action/action.js

@@ -0,0 +1,254 @@
+import { events } from "../events/events.js";
+import { createProc } from "../../system/process/process.js";
+import { FolderCache } from "../../system/fs/FolderCache.js";
+// Maps an instance's `.ref` promise back to the instance that produces it, so the
+// run can catch a consumer launched before (or without) its `.ref` producer —
+// which would otherwise await a handle that never arrives and hang silently.
+const refOwners = new WeakMap();
+/**
+ * If `value` is some action instance's `.ref` promise, the instance that owns it
+ * (the producer of that handle); otherwise `undefined`. Used by the run to verify
+ * a `.ref` dependency was launched before the action that consumes it.
+ */
+export const producerOfRef = (value) => typeof value === "object" && value !== null ? refOwners.get(value) : undefined;
+/**
+ * A constructed-but-not-yet-run action — everything a single launch needs, in one
+ * object: its own event bus, its set-once handle (`ref`) and Outcome (`done`), and
+ * the `start` that runs the impl and settles them. Self-contained: `start()`
+ * resolves with the {@link Outcome} and **never rejects** (a failing action is
+ * data, not a throw), so a launcher just awaits `.done`.
+ */
+class ActionRun {
+    name;
+    args;
+    /** The attached handle, awaited via `.ref` (settled by `attach`, or by `start` on settle). */
+    ref;
+    /** The action's Outcome — resolves (never rejects) once it settles. */
+    done;
+    exec;
+    // The bus covers declared + system events; `ctx.emit` is narrowed to the declared
+    // ones, while the framework emits attached/done/error through the same bus.
+    emitter;
+    handle;
+    settled;
+    attached = false;
+    constructor(name, exec, args) {
+        this.name = name;
+        this.exec = exec;
+        this.args = args;
+        this.emitter = events(name);
+        this.handle = ActionRun.defer();
+        this.settled = ActionRun.defer();
+        this.ref = this.handle.promise;
+        this.done = this.settled.promise;
+        // 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 this.handle.promise.catch(() => { });
+        // Register this instance as the producer of its `.ref`, so the run can catch a
+        // consumer built with this `.ref` that gets launched before this instance.
+        refOwners.set(this.ref, this);
+    }
+    start(system) {
+        // `ctx.emit` is the declared-events view of the same bus.
+        const emit = this.emitter.emit;
+        // The bus is pure pub/sub; logging each emit onto the timeline is layered here,
+        // through this action's *scoped* logger — so an emit's line inherits the action's
+        // path (`parent › child › event`) just like its other output, and the bus stays
+        // free of any global. Registered once per run of this instance.
+        this.emitter.onAny((key, payload) => ActionRun.logEmit(system, this.name, String(key), payload));
+        // `Promise.resolve().then` normalizes a sync result and routes a sync throw to
+        // the `error` path, so exec may be sync or async.
+        return Promise.resolve()
+            .then(() => this.exec({
+            ...system,
+            emit,
+            attach: (value) => this.attach(value),
+            proc: createProc(system.logs, system.signal, system.output.snapshots),
+            artifactsFolder: system.output.folder.artifacts(),
+        }, ...this.args))
+            .then((result) => {
+            const outcome = { ok: true, value: result };
+            this.settled.resolve(outcome);
+            this.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.
+            this.handle.resolve(undefined);
+            return outcome;
+        }, (error) => {
+            const exitCode = ActionRun.exitCodeOf(error);
+            const outcome = exitCode === undefined ? { ok: false, error } : { ok: false, error, exitCode };
+            // Emit `error` (for `.on("error")` handlers), then settle `done` with the
+            // Outcome — the canonical failure signal that `.done`/`once` read.
+            this.systemEmit("error", error);
+            this.settled.resolve(outcome);
+            this.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 already attached.
+            this.handle.reject(error);
+            // Resolve (never rethrow): failure is the Outcome, not a rejection.
+            return outcome;
+        });
+    }
+    on(key, handler) {
+        this.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 (which
+        // resolves `undefined` if the action settles before the event).
+        return (key === "done" ? this.settled.promise : ActionRun.awaitEvent(this.emitter, key));
+    }
+    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 = FolderCache.resolvePaths(paths);
+        const { name } = this;
+        // 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 this inner instance's `start`.
+        return action(name).run(async (ctx) => {
+            const fp = await FolderCache.fingerprint(targets);
+            if ((await FolderCache.read(targets)) === fp) {
+                ctx.logs.append({ source: name, level: "info", message: "cached, skipping" });
+                return undefined;
+            }
+            const outcome = await this.start({
+                logs: ctx.logs,
+                signal: ctx.signal,
+                nod: ctx.nod,
+                output: ctx.output,
+            });
+            // 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 FolderCache.write(targets, fp);
+            return outcome.value;
+        })();
+    }
+    /** One-time lifecycle moment: resolve `ref` and emit `attached`. Guarded (second attach no-ops). */
+    attach(value) {
+        if (this.attached)
+            return;
+        this.attached = true;
+        this.handle.resolve(value);
+        this.systemEmit("attached");
+    }
+    /** The framework's own emits (loosely typed — sidesteps EmitArgs for void results). */
+    systemEmit(key, payload) {
+        this.emitter.emit(key, payload);
+    }
+    static defer() {
+        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). */
+    static exitCodeOf(error) {
+        const code = error?.exitCode;
+        return typeof code === "number" ? code : undefined;
+    }
+    /**
+     * Log one emit onto the run timeline, through the action's scoped `logs` so the
+     * line carries its path. Fields are `·`-delimited — action name · key · payload.
+     * A string payload rides inline; a richer one is written to a snapshot file and
+     * linked (`→ <rel>`) so the durable record keeps it without bloating the line.
+     * This is the sole place emits become log lines — the bus itself does no logging.
+     */
+    static logEmit(system, name, key, payload) {
+        const fields = [name, key];
+        if (typeof payload === "string") {
+            fields.push(payload);
+        }
+        else if (payload !== undefined) {
+            fields.push(`→ ${system.output.snapshots.captureJson(`event-${name}-${key}`, payload).rel}`);
+        }
+        system.logs.append({ source: "event", level: "event", message: fields.join(" · ") });
+    }
+    /**
+     * A promise for the next emit of `key`. It **never rejects**: it resolves with
+     * the event's payload, or with `undefined` if the action settles (`done` — which
+     * always fires) before `key` ever does. A retained snapshot resolves it
+     * immediately. (Not used for `key === "done"`, which reads the settled Outcome.)
+     */
+    static awaitEvent(emitter, key) {
+        return new Promise((resolve) => {
+            const offs = [];
+            let settled = false;
+            // First of [the event | 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 `done` key is always present on an
+            // instance's event map, so reach it through a loosened view.
+            const listen = emitter.listenOnce;
+            offs.push(listen(key, (payload) => settle(() => resolve(payload))));
+            // `done` fires once on any settle (success or failure); if it beats `key`,
+            // the event will never come — resolve `undefined` rather than reject.
+            if (key !== "done") {
+                offs.push(listen("done", () => settle(() => resolve(undefined))));
+            }
+            // 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();
+        });
+    }
+}
+/**
+ * The step between `action(name)` and an {@link Action}: declare typed events
+ * and/or an imperative handle (phantom type transitions — each returns a builder
+ * carrying the same `name`), then `run(exec)` to bind the implementation.
+ */
+class Builder {
+    name;
+    constructor(name) {
+        this.name = name;
+    }
+    emits() {
+        return new Builder(this.name);
+    }
+    ref() {
+        return new Builder(this.name);
+    }
+    run(exec) {
+        const { name } = this;
+        // Invoking the returned callable constructs a fresh instance (deferred — the run
+        // executes it). Each call is its own {@link ActionRun}.
+        const create = (...args) => new ActionRun(name, exec, args);
+        return Object.assign(create, { actionName: name });
+    }
+}
+/**
+ * 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 new Builder(name);
+}

package/dist/{core/action.d.ts → orchestration/action/types.d.ts}

@@ -1,6 +1,7 @@
-import type { Logger } from "./log-collector/LogsCollector.ts";
-import { type Emitter, type EventHandler } from "./events.ts";
-import { type Proc } from "./process.ts";
+import type { Logger } from "../../output/log/LogsCollector.ts";
+import type { Output } from "../../output/Output.ts";
+import type { Emitter, EventHandler } from "../events/events.ts";
+import type { Proc } from "../../system/process/process.ts";
 /** An action that declares no events. */
 export type NoEvents = Record<never, never>;
 /** A value an action's `exec` may return: a result, or a promise of one. */
@@ -9,7 +10,7 @@ export type Awaitable<T> = T | Promise<T>;
  * How an action settles. An action **never throws into the spin body** — its
  * failure is data, not control flow: it completes with `{ ok: false, error }`
  * instead of rejecting. On success it carries the exec's `value`. `exitCode` is
- * present when the failure came from a process (see {@link import("../actions/command.ts").command}).
+ * present when the failure came from a process (see {@link import("../../../actions/command.ts").command}).
  * Await it via `instance.done` or `once("done")`; both resolve, never reject.
  */
 export type Outcome<T> = {
@@ -35,16 +36,41 @@ export interface SystemEvents<Result> {
 }
 /** The full event map a constructed instance exposes: the declared events plus the system ones. */
 export type InstanceEvents<Events extends object, Result> = Events & SystemEvents<Result>;
+/**
+ * Launch an action into the spin and get the same instance back, so you can
+ * `await` its `.done` (its {@link Outcome} — resolves with `{ ok, value } |
+ * { ok, error }`, **never throws**), its `.ref` (the attached handle; rejects on
+ * failure, so it's for data deps consumed inside other actions), or subscribe with
+ * `.on` / `.once`. The spin body waves an action in with a nod; an action nods
+ * **child** actions the same way, and their log output is prefixed with the
+ * parent's path (see `SpinHost`).
+ */
+export type Nod = <I extends AnyActionInstance>(instance: I) => I;
 /** System services the pipeline injects into every action when it runs. */
 export interface SystemGlobal {
     /** A logger bound to this action — feeds it directly or via `proc`. */
     readonly logs: Logger;
     /** The run's abort signal — aborted on teardown/cancel; honor it to stop early. */
     readonly signal: AbortSignal;
+    /**
+     * Launch a **child** action into the same spin (returns it for awaiting/chaining).
+     * The child's log output is prefixed with this action's path (`parent › child`),
+     * and the child lives in the spin — it keeps the run alive until it settles,
+     * independent of when this action finishes. `await ctx.nod(x).done` to wait on it.
+     */
+    readonly nod: Nod;
+    /**
+     * This run's output subsystem — the folder, snapshot store, and run-log writer,
+     * owned by the {@link SpinHost} and threaded to every action (rather than reached
+     * as a module singleton). The framework uses it to place `ctx.artifactsFolder`
+     * and to snapshot event/proc payloads; actions can reach `output.snapshots` to
+     * capture their own artifacts.
+     */
+    readonly output: Output;
 }
 /** What an action's implementation receives: the system bag, plus `emit`, `attach`, and `proc`. */
 export interface ActionContext<Events extends object, Handle = void> extends SystemGlobal {
-    /** Emit one of this action's declared events (also pushed to the global log). */
+    /** Emit one of this action's declared events (also logged onto the timeline under this action's path). */
     readonly emit: Emitter<Events>["emit"];
     /** Publish this action's imperative handle, resolving its instance's `.ref`. */
     readonly attach: (handle: Handle) => void;
@@ -91,12 +117,13 @@ export interface ActionInstance<Result = unknown, Events extends object = NoEven
     /** Subscribe to a declared or system event (`done`/`error`) with a handler. */
     on<K extends keyof InstanceEvents<Events, Result>>(key: K, handler: EventHandler<InstanceEvents<Events, Result>[K]>): void;
     /**
-     * A promise for the next occurrence of an event: resolves with its payload —
-     * or rejects if the action settles first (`error`, or `done` without the
-     * event), so an awaiter never hangs. Use {@link on} for ongoing/handler
-     * subscriptions; `once` is the awaitable, one-value form.
+     * A promise for the next occurrence of an event. It **never rejects**: it
+     * resolves with the event's payload, or with `undefined` if the action settles
+     * (`done`) before the event ever fires — so awaiting it in a spin body can't
+     * throw and can't hang. `once("done")` yields the {@link Outcome}. Use {@link on}
+     * for ongoing/handler subscriptions; `once` is the awaitable, one-value form.
      */
-    once<K extends keyof InstanceEvents<Events, Result>>(key: K): Promise<InstanceEvents<Events, Result>[K]>;
+    once<K extends keyof InstanceEvents<Events, Result>>(key: K): Promise<InstanceEvents<Events, Result>[K] | undefined>;
     /**
      * Gate this action on its **inputs** — the files/folders it *reads* (its
      * sources), **not** what it produces. `paths` (each a file or a folder) are
@@ -139,19 +166,3 @@ export interface ActionBuilder<Events extends object, Handle = void> {
     /** Provide the implementation. `ctx` carries `logs`, `signal`, `emit`, and `attach`. */
     run<Args extends unknown[], Result>(exec: (ctx: ActionContext<Events, Handle>, ...args: Args) => Awaitable<Result>): Action<Args, Result, Events, Handle>;
 }
-/**
- * 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 declare function action(name: string): ActionBuilder<NoEvents, void>;

package/dist/orchestration/action/types.js

@@ -0,0 +1 @@
+export {};