@grida/fx 0.1.0-alpha.2 → 0.2.0

package/dist/control.js

@@ -0,0 +1,160 @@
+/** Exact-target run control through the engine's public command line (spec/control.md).
+ * The engine resolves and authenticates the owner and verifies cleanup. */
+import { call, failure } from "./engine.js";
+import { FxError } from "./errors.js";
+/** A structured control failure, retaining its stable code and complete result.
+ * Unsupported binaries and malformed responses reject with ordinary FxError. */
+export class RunControlError extends FxError {
+    result;
+    code;
+    constructor(result, done) {
+        super(result.message ?? `run control failed: ${result.code}`, {
+            exitCode: done.status,
+            signal: done.signal,
+            stdout: done.stdout,
+            stderr: done.stderr,
+            args: done.args,
+        });
+        this.name = "RunControlError";
+        this.result = result;
+        this.code = result.code ?? "";
+    }
+}
+const MAX_RESULT_BYTES = 16 * 1024;
+const REQUIRED = [
+    "kind", "operation", "invocation_id", "outcome", "request_status", "recorded_state",
+    "cleanup", "external_completion",
+];
+const OPTIONAL = ["code", "message", "availability", "can_cancel"];
+const ERROR_STATUS = {
+    unavailable: 1,
+    wait_timeout: 1,
+    owner_lost: 1,
+    acknowledgment_unknown: 1,
+    completion_unverified: 1,
+    invalid_target: 2,
+    ambiguous_target: 2,
+    invocation_mismatch: 2,
+    unsupported_version: 2,
+    unauthorized: 2,
+    record_error: 2,
+};
+const ENUMS = {
+    outcome: ["inspected", "accepted", "already_requested", "already_terminal", "finishing", "completed", "error"],
+    request_status: ["accepted", "not_accepted", "unknown"],
+    recorded_state: ["planned", "unfinished", "succeeded", "failed", "cancelled", "unknown"],
+    cleanup: ["pending", "complete", "unknown"],
+    external_completion: ["not_verified"],
+};
+function target(run) {
+    if (typeof run !== "string" || run === "" || run.startsWith("-") || run.includes("\0")) {
+        throw new TypeError("run is a nonempty explicit run folder or exact WORKFLOW_ID/NAME, without a leading '-' or NUL");
+    }
+    return run;
+}
+function cancelOptions(options) {
+    if (options.wait !== undefined && typeof options.wait !== "boolean") {
+        throw new TypeError("wait is true or false");
+    }
+    const args = ["--source=sdk"];
+    if (options.invocation !== undefined) {
+        if (typeof options.invocation !== "string" || options.invocation === "" || options.invocation.includes("\0")) {
+            throw new TypeError("invocation is a nonempty invocation ID");
+        }
+        args.push(`--invocation=${options.invocation}`);
+    }
+    if (options.wait === true) {
+        args.push("--wait");
+    }
+    if (options.timeout !== undefined) {
+        if (options.wait !== true) {
+            throw new TypeError("timeout requires wait: true");
+        }
+        if (typeof options.timeout !== "string" || !/^[0-9]+[smh]$/.test(options.timeout) || /^0+[smh]$/.test(options.timeout)) {
+            throw new TypeError("timeout is a positive integer followed by s, m or h");
+        }
+        args.push(`--timeout=${options.timeout}`);
+    }
+    return args;
+}
+function parseResult(done, operation, wait) {
+    if (Buffer.byteLength(done.stdout, "utf8") > MAX_RESULT_BYTES) {
+        throw new Error("oversized result");
+    }
+    const value = JSON.parse(done.stdout);
+    if (typeof value !== "object" || value === null || Array.isArray(value)) {
+        throw new Error("not an object");
+    }
+    const data = value;
+    if (!REQUIRED.every((name) => name in data)) {
+        throw new Error("missing fields");
+    }
+    for (const [name, field] of Object.entries(data)) {
+        if (![...REQUIRED, ...OPTIONAL].includes(name))
+            continue;
+        if (name === "can_cancel") {
+            if (typeof field !== "boolean")
+                throw new Error("can_cancel is not boolean");
+        }
+        else if (name !== "invocation_id" || field !== null) {
+            if (typeof field !== "string" || field === "" || field.length > (name === "invocation_id" ? 256 : 4096)) {
+                throw new Error(`invalid ${name}`);
+            }
+        }
+    }
+    if (data.kind !== "fx-run-control-v1" || data.operation !== operation) {
+        throw new Error("incompatible result");
+    }
+    if (Object.entries(ENUMS).some(([name, values]) => !values.includes(data[name]))) {
+        throw new Error("unknown result enum");
+    }
+    if (data.outcome === "completed" && (data.invocation_id === null || data.cleanup !== "complete"
+        || !["succeeded", "failed", "cancelled"].includes(data.recorded_state))) {
+        throw new Error("completion lacks invocation, cleanup or terminal evidence");
+    }
+    if (operation === "inspect") {
+        if (!["available", "unavailable", "unsupported", "unknown"].includes(data.availability) || typeof data.can_cancel !== "boolean") {
+            throw new Error("missing or unknown inspection fields");
+        }
+    }
+    else if ("availability" in data || "can_cancel" in data) {
+        throw new Error("inspection fields on cancellation");
+    }
+    if (data.outcome === "error") {
+        if (ERROR_STATUS[data.code] !== done.status || !("message" in data)) {
+            throw new Error("unknown code or mismatched error status");
+        }
+    }
+    else {
+        const allowed = operation === "inspect" ? ["inspected"] : wait ? ["completed"] : ["accepted", "already_requested", "already_terminal", "finishing"];
+        if (done.status !== 0 || !allowed.includes(data.outcome) || "code" in data || "message" in data) {
+            throw new Error("mismatched success outcome or status");
+        }
+    }
+    return data;
+}
+async function control(operation, run, options, args, wait = false) {
+    const verb = operation === "inspect" ? "inspect" : "cancel";
+    const done = await call([verb, target(run), ...args, "--json"], options);
+    let result;
+    try {
+        result = parseResult(done, operation, wait);
+    }
+    catch {
+        throw failure(verb, done);
+    }
+    if (result.outcome === "error") {
+        throw new RunControlError(result, done);
+    }
+    return result;
+}
+/** Inspect one exact target's invocation and authenticated control availability. A bare
+ * workflow ID is refused by the engine; no latest-run selection is implied. */
+export async function inspectControl(run, options = {}) {
+    return control("inspect", run, options, ["--control"]);
+}
+/** Request cancellation of one invocation. Aborting this control client only ends its wait;
+ * an accepted cancellation remains effective in the separately owned runner. */
+export async function cancel(run, options = {}) {
+    return control("cancel", run, options, cancelOptions(options), options.wait === true);
+}

package/dist/documents.d.ts

@@ -79,12 +79,16 @@ export interface Graph {
         };
     };
     instances: GraphInstance[];
-    /** Repeats whose instances a later phase expands, with their worst case. */
+    /** Repeats whose instances a later phase expands, with their worst case. `step` is the
+     * declared step's path and `waiting_on` what its list needs; both are absent in documents
+     * written before they existed. */
     pending: {
         path: string;
+        step?: string;
         max: number;
         phase: number;
         high_usd: number;
+        waiting_on?: string[];
     }[];
     estimate: PriceRange & {
         ceiling_usd: number | null;

package/dist/engine.d.ts

@@ -4,7 +4,8 @@
  * The engine runs in the caller's process group, so a Ctrl-C at the terminal reaches it as it
  * reaches the caller, and it stops a run as it would on its own: do not also abort the call on
  * that Ctrl-C (a second interruption makes the engine end at once). An `AbortSignal` stops it from
- * code: the engine gets SIGINT, and SIGKILL if it has not exited 10 seconds later.
+ * code: a run gets one idempotent SIGTERM and retains ownership until engine cleanup ends, without
+ * an automatic force deadline. Other commands retain their ten-second SIGKILL fallback.
  *
  * A call ends when the engine exits, not when the last holder of its pipes closes them: a process
  * a node body started may outlive the engine on purpose.
@@ -18,8 +19,8 @@ export interface CallOptions {
     /** Variables over `process.env` for the engine (`undefined` removes one), e.g.
      * `GRIDA_FX_PYTHON`. `GRIDA_FX_BIN` here also chooses the binary. */
     readonly env?: Environment;
-    /** Stops the engine (SIGINT, then SIGKILL after 10 seconds); the call rejects with the
-     * signal's reason once it has exited. */
+    /** Interrupts the engine once. A run waits for engine cleanup before rejecting with the
+     * signal's reason; other commands retain a ten-second force fallback. */
     readonly signal?: AbortSignal;
 }
 /** How a call ended. */

package/dist/engine.js

@@ -4,7 +4,8 @@
  * The engine runs in the caller's process group, so a Ctrl-C at the terminal reaches it as it
  * reaches the caller, and it stops a run as it would on its own: do not also abort the call on
  * that Ctrl-C (a second interruption makes the engine end at once). An `AbortSignal` stops it from
- * code: the engine gets SIGINT, and SIGKILL if it has not exited 10 seconds later.
+ * code: a run gets one idempotent SIGTERM and retains ownership until engine cleanup ends, without
+ * an automatic force deadline. Other commands retain their ten-second SIGKILL fallback.
  *
  * A call ends when the engine exits, not when the last holder of its pipes closes them: a process
  * a node body started may outlive the engine on purpose.
@@ -16,16 +17,22 @@ import { FxError } from "./errors.js";
 export const USAGE_OR_ERROR = 2;
 /** The exit status of an interrupted command. */
 export const INTERRUPTED = 130;
-/** How long a stopped engine has to exit before it is killed. */
+/** The stop grace for non-run commands. Run cleanup has no automatic force deadline. */
 const STOP_GRACE_MS = 10_000;
 /** How long the pipes are still read once the engine has exited. */
 const DRAIN_MS = 500;
-/** How the engine prefixes an error on stderr. */
+/** How the engine prefixes an error on stderr: the SDK always runs it as the `grida-fx` invoker
+ * (spec/distribution.md §2), whichever command started this process. */
 const ERROR_PREFIX = "grida-fx: ";
 /** Runs the engine with `args` and collects what it prints. */
 export async function call(args, options = {}) {
     const cwd = options.cwd ?? process.cwd();
     const env = mergeEnvironment(options.env);
+    // A value inherited from a launcher (a node body run under `grida fx`) would change the prefix.
+    env.GRIDA_FX_INVOKER = "grida-fx";
+    if (args[0] === "run") {
+        env.GRIDA_FX_CANCEL_SOURCE = "sdk";
+    }
     const engine = findEngine(machineLookup(env, cwd));
     options.signal?.throwIfAborted();
     return new Promise((resolvePromise, reject) => {
@@ -39,13 +46,21 @@ export async function call(args, options = {}) {
         child.stdout.on("data", (chunk) => stdout.push(chunk));
         child.stderr.on("data", (chunk) => stderr.push(chunk));
         let killTimer;
+        let interrupted = false;
         const onAbort = () => {
-            if (child.exitCode === null && child.signalCode === null) {
-                child.kill("SIGINT");
-                killTimer = setTimeout(() => child.kill("SIGKILL"), STOP_GRACE_MS);
+            if (!interrupted && child.exitCode === null && child.signalCode === null) {
+                interrupted = true;
+                child.kill(args[0] === "run" ? "SIGTERM" : "SIGINT");
+                if (args[0] !== "run") {
+                    killTimer = setTimeout(() => child.kill("SIGKILL"), STOP_GRACE_MS);
+                }
             }
         };
         options.signal?.addEventListener("abort", onAbort, { once: true });
+        // An abort between the initial check and listener registration must still stop this child.
+        if (options.signal?.aborted) {
+            onAbort();
+        }
         const finish = () => {
             options.signal?.removeEventListener("abort", onAbort);
             if (killTimer !== undefined) {

package/dist/index.d.ts

@@ -3,9 +3,12 @@
  * the engine package for the machine); this package drives it: plan, price and run workflows,
  * read their runs, and write workflow documents.
  */
-export declare const version = "0.1.0-alpha.2";
+export declare const version = "0.2.0";
 export { engineVersion, expand, identity, type InspectOptions, inspect, Plan, PlanRefused, plan, price, project, RunFile, RunResult, type RunValue, run, } from "./api.js";
 export { BINARY_VARIABLE, type BinaryOptions, binary, type Environment } from "./binary.js";
+export { cancel, type CancelOptions, inspectControl, RunControlError, type RunControlResult } from "./control.js";
+export { loadRun, type ObservedRunEvent, type RunEventBatch, type RunEventsOptions, type RunFollowOptions, RunObservationError, type RunObservationFailure, type RunReadOptions, RunRecord, type RunSnapshot, RunExportError, type RunExportFailure, type RunExportOptions, type RunExportResult, } from "./record.js";
+export { listRuns, type ListRunsOptions, type RemoveRunsOptions, removeRuns, type RunEntry, type RunPlacement, type RunRemoval, type RunRemovalEntry, RunRemovalError, type RunRemovalFailure, type RunRemovalSkip, type RunState, } from "./runs.js";
 export type { Encoded, FileRef, Graph, GraphInstance, Identities, InspectedStep, Inspection, Price, PricePhase, PriceRange, Problem, ProjectedInstance, Projection, RunEvent, RunFinished, WithValue, } from "./documents.js";
 export type { CallOptions } from "./engine.js";
 export { FxError, type FxErrorDetails } from "./errors.js";

package/dist/index.js

@@ -3,9 +3,12 @@
  * the engine package for the machine); this package drives it: plan, price and run workflows,
  * read their runs, and write workflow documents.
  */
-export const version = "0.1.0-alpha.2";
+export const version = "0.2.0";
 export { engineVersion, expand, identity, inspect, Plan, PlanRefused, plan, price, project, RunFile, RunResult, run, } from "./api.js";
 export { BINARY_VARIABLE, binary } from "./binary.js";
+export { cancel, inspectControl, RunControlError } from "./control.js";
+export { loadRun, RunObservationError, RunRecord, RunExportError, } from "./record.js";
+export { listRuns, removeRuns, RunRemovalError, } from "./runs.js";
 export { FxError } from "./errors.js";
 export { platformFor, platforms } from "./platforms.js";
 export { expr, workflow, } from "./workflow.js";

package/dist/record.d.ts

@@ -0,0 +1,107 @@
+/** Saved evidence and independent observation; neither owns execution or a viewer. */
+import type { InspectOptions } from "./api.js";
+import type { Graph, Inspection, RunEvent } from "./documents.js";
+import { type CallOptions, type Exit } from "./engine.js";
+import { FxError } from "./errors.js";
+/** The complete recorded event envelope. Unknown events and fields remain readable. */
+export interface ObservedRunEvent extends RunEvent {
+    kind: "fx-run-events-v1";
+    invocation_id: string;
+    plan: string;
+    offset_ms: number;
+}
+export interface RunSnapshot {
+    kind: "fx-run-snapshot-v1";
+    cursor: string;
+    plan: Graph;
+    events: ObservedRunEvent[];
+    [field: string]: unknown;
+}
+export interface RunEventBatch {
+    kind: "fx-run-event-batch-v1";
+    cursor: string;
+    events: ObservedRunEvent[];
+    has_more: boolean;
+    [field: string]: unknown;
+}
+export interface RunObservationFailure {
+    kind: "fx-run-observation-error-v1";
+    code: string;
+    message: string;
+    [field: string]: unknown;
+}
+/** A reader failure with the engine's stable code and complete public error document. */
+export declare class RunObservationError extends FxError {
+    readonly code: string;
+    readonly document: RunObservationFailure;
+    constructor(document: RunObservationFailure, done: Exit);
+}
+export interface RunReadOptions {
+    /** Stops this reader only; it never cancels the separately owned workflow execution. */
+    readonly signal?: AbortSignal;
+}
+export interface RunExportOptions extends RunReadOptions {
+    /** Include recorded values after deliberate disclosure review. Default: false. */
+    readonly includeValues?: boolean;
+    /** Include recorded diagnostic messages. Default: false. */
+    readonly includeDiagnostics?: boolean;
+}
+/** The engine's wire receipt. Counts cover included artifacts, excluding manifest.json. */
+export interface RunExportResult {
+    kind: "fx-run-export-result-v1";
+    manifest_sha256: string;
+    output: string;
+    files: number;
+    bytes: number;
+    omitted_artifacts: {
+        digest: string;
+        reason: string;
+    }[];
+    [field: string]: unknown;
+}
+export interface RunExportFailure {
+    kind: "fx-run-export-error-v1";
+    code: string;
+    message: string;
+    [field: string]: unknown;
+}
+export declare class RunExportError extends FxError {
+    readonly code: string;
+    readonly document: RunExportFailure;
+    constructor(document: RunExportFailure, done: Exit);
+}
+export interface RunEventsOptions extends RunReadOptions {
+    /** Opaque acknowledged cursor; omit to read from the beginning. */
+    readonly after?: string;
+    /** Maximum events per batch, 1–1024 (default: 256). */
+    readonly limit?: number;
+}
+export interface RunFollowOptions extends RunEventsOptions {
+    /** Poll only after draining readable batches (default: 1000 milliseconds). */
+    readonly pollIntervalMs?: number;
+}
+/** One resolved run folder and its sampled inspection. Reads stay pinned to this folder.
+ * Inspection and later snapshots are independent samples; only each snapshot and its cursor
+ * share one consistent prefix. No exit code or process-liveness claim is synthesized. */
+export declare class RunRecord {
+    readonly runDir: string;
+    readonly inspection: Inspection;
+    private readonly context;
+    constructor(runDir: string, inspection: Inspection, context?: CallOptions);
+    /** Capture the saved plan, complete readable event prefix and matching attachment cursor. */
+    snapshot(options?: RunReadOptions): Promise<RunSnapshot>;
+    /** Export terminal, inactive evidence to a new directory, without execution or publication.
+     * Relative destinations resolve against the caller's current directory. Values and
+     * diagnostics are withheld by default; included media still needs publication review. */
+    export(destination: string, options?: RunExportOptions): Promise<RunExportResult>;
+    /** Read bounded events after a cursor, or from the beginning when after is omitted. */
+    events(options?: RunEventsOptions): Promise<RunEventBatch>;
+    /** Follow nonempty batches continuously, including later resumes, until break or abort.
+     * Terminal events end an invocation, not this reader, and do not certify owner cleanup.
+     * Start after snapshot.cursor to attach without missing events. Reader errors surface;
+     * no missing-run waits, automatic reattachment or execution retries are performed. */
+    follow(options?: RunFollowOptions): AsyncGenerator<RunEventBatch>;
+}
+/** Resolve a folder or recorded selector once, without planning, executing or starting a service.
+ * Later reads use the pinned absolute folder. The loading signal is not retained by the record. */
+export declare function loadRun(target: string, options?: InspectOptions): Promise<RunRecord>;

package/dist/record.js

@@ -0,0 +1,246 @@
+/** Saved evidence and independent observation; neither owns execution or a viewer. */
+import { resolve } from "node:path";
+import { call, failure } from "./engine.js";
+import { FxError } from "./errors.js";
+/** A reader failure with the engine's stable code and complete public error document. */
+export class RunObservationError extends FxError {
+    code;
+    document;
+    constructor(document, done) {
+        super(document.message, {
+            exitCode: done.status, signal: done.signal, stdout: done.stdout,
+            stderr: done.stderr, args: done.args,
+        });
+        this.name = "RunObservationError";
+        this.code = document.code;
+        this.document = document;
+    }
+}
+export class RunExportError extends FxError {
+    code;
+    document;
+    constructor(document, done) {
+        super(document.message, {
+            exitCode: done.status, signal: done.signal, stdout: done.stdout,
+            stderr: done.stderr, args: done.args,
+        });
+        this.name = "RunExportError";
+        this.code = document.code;
+        this.document = document;
+    }
+}
+function object(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function text(value) {
+    return typeof value === "string" && value !== "";
+}
+function cursor(value) {
+    return text(value) && !value.includes("\0");
+}
+function event(value) {
+    return object(value) && value.kind === "fx-run-events-v1" && text(value.event)
+        && text(value.invocation_id) && typeof value.plan === "string"
+        && /^[a-f0-9]{64}$/.test(value.plan) && Number.isSafeInteger(value.offset_ms)
+        && value.offset_ms >= 0;
+}
+function exportResult(done) {
+    let value;
+    try {
+        value = JSON.parse(done.stdout);
+    }
+    catch {
+        throw failure("export", done);
+    }
+    if (done.status === 2 && object(value) && value.kind === "fx-run-export-error-v1"
+        && text(value.code) && text(value.message)) {
+        throw new RunExportError(value, done);
+    }
+    if (done.status !== 0 || !object(value) || value.kind !== "fx-run-export-result-v1"
+        || typeof value.manifest_sha256 !== "string" || !/^[a-f0-9]{64}$/.test(value.manifest_sha256)
+        || !cursor(value.output) || !Number.isSafeInteger(value.files) || value.files < 0
+        || !Number.isSafeInteger(value.bytes) || value.bytes < 0
+        || !Array.isArray(value.omitted_artifacts) || !value.omitted_artifacts.every((item) => object(item) && typeof item.digest === "string" && /^[a-f0-9]{64}$/.test(item.digest) && text(item.reason))) {
+        throw failure("export", done);
+    }
+    return value;
+}
+function response(done, snapshot, options = {}) {
+    let value;
+    try {
+        value = JSON.parse(done.stdout);
+    }
+    catch {
+        throw failure("observe", done);
+    }
+    if (done.status === 2 && object(value) && value.kind === "fx-run-observation-error-v1"
+        && text(value.code) && text(value.message)) {
+        throw new RunObservationError(value, done);
+    }
+    if (done.status !== 0 || !object(value) || !cursor(value.cursor)
+        || !Array.isArray(value.events) || !value.events.every(event)) {
+        throw failure("observe", done);
+    }
+    if (snapshot) {
+        if (value.kind !== "fx-run-snapshot-v1" || !object(value.plan)
+            || value.plan.kind !== "fx-graph-v1")
+            throw failure("observe", done);
+        return value;
+    }
+    if (value.kind !== "fx-run-event-batch-v1" || typeof value.has_more !== "boolean"
+        || value.events.length > (options.limit ?? 256)
+        || (value.events.length === 0 && (value.has_more || (options.after !== undefined && value.cursor !== options.after)))
+        || (value.events.length > 0 && value.cursor === options.after)) {
+        throw failure("observe", done);
+    }
+    return value;
+}
+function eventArgs(options) {
+    const args = [];
+    if (options.after !== undefined) {
+        if (!text(options.after) || options.after.includes("\0")) {
+            throw new TypeError("after is a nonempty opaque cursor without NUL");
+        }
+        args.push(`--after=${options.after}`);
+    }
+    if (options.limit !== undefined) {
+        if (!Number.isInteger(options.limit) || options.limit < 1 || options.limit > 1024) {
+            throw new TypeError("limit is an integer from 1 to 1024");
+        }
+        args.push(`--limit=${options.limit}`);
+    }
+    return args;
+}
+function sleep(milliseconds, signal) {
+    signal?.throwIfAborted();
+    return new Promise((done, reject) => {
+        const finish = () => { signal?.removeEventListener("abort", aborted); done(); };
+        const timer = setTimeout(finish, milliseconds);
+        const aborted = () => {
+            clearTimeout(timer);
+            signal?.removeEventListener("abort", aborted);
+            reject(signal?.reason);
+        };
+        signal?.addEventListener("abort", aborted, { once: true });
+    });
+}
+/** One resolved run folder and its sampled inspection. Reads stay pinned to this folder.
+ * Inspection and later snapshots are independent samples; only each snapshot and its cursor
+ * share one consistent prefix. No exit code or process-liveness claim is synthesized. */
+export class RunRecord {
+    runDir;
+    inspection;
+    context;
+    constructor(runDir, inspection, context = {}) {
+        this.runDir = resolve(context.cwd ?? process.cwd(), runDir);
+        this.inspection = inspection;
+        this.context = {
+            cwd: resolve(context.cwd ?? process.cwd()),
+            ...(context.env !== undefined ? { env: { ...context.env } } : {}),
+        };
+    }
+    /** Capture the saved plan, complete readable event prefix and matching attachment cursor. */
+    async snapshot(options = {}) {
+        const done = await call(["observe", this.runDir, "--snapshot"], {
+            ...this.context, ...(options.signal !== undefined ? { signal: options.signal } : {}),
+        });
+        return response(done, true);
+    }
+    /** Export terminal, inactive evidence to a new directory, without execution or publication.
+     * Relative destinations resolve against the caller's current directory. Values and
+     * diagnostics are withheld by default; included media still needs publication review. */
+    async export(destination, options = {}) {
+        if (!cursor(destination))
+            throw new TypeError("destination is a nonempty filesystem path without NUL");
+        for (const option of [options.includeValues, options.includeDiagnostics]) {
+            if (option !== undefined && typeof option !== "boolean")
+                throw new TypeError("disclosure options are true or false");
+        }
+        const args = ["export", this.runDir, `--out=${resolve(destination)}`, "--json"];
+        if (options.includeValues === true)
+            args.push("--include-values");
+        if (options.includeDiagnostics === true)
+            args.push("--include-diagnostics");
+        const done = await call(args, {
+            ...this.context, ...(options.signal !== undefined ? { signal: options.signal } : {}),
+        });
+        return exportResult(done);
+    }
+    /** Read bounded events after a cursor, or from the beginning when after is omitted. */
+    async events(options = {}) {
+        const args = eventArgs(options);
+        const done = await call(["observe", this.runDir, ...args], {
+            ...this.context, ...(options.signal !== undefined ? { signal: options.signal } : {}),
+        });
+        return response(done, false, options);
+    }
+    /** Follow nonempty batches continuously, including later resumes, until break or abort.
+     * Terminal events end an invocation, not this reader, and do not certify owner cleanup.
+     * Start after snapshot.cursor to attach without missing events. Reader errors surface;
+     * no missing-run waits, automatic reattachment or execution retries are performed. */
+    async *follow(options = {}) {
+        eventArgs(options);
+        const interval = options.pollIntervalMs ?? 1000;
+        if (!Number.isFinite(interval) || interval <= 0 || interval > 2_147_483_647) {
+            throw new TypeError("pollIntervalMs is positive, finite and at most 2147483647");
+        }
+        let after = options.after;
+        for (;;) {
+            options.signal?.throwIfAborted();
+            const batch = await this.events({
+                ...(after !== undefined ? { after } : {}),
+                ...(options.limit !== undefined ? { limit: options.limit } : {}),
+                ...(options.signal !== undefined ? { signal: options.signal } : {}),
+            });
+            // A slow consumer or one mutating its received document cannot change our position.
+            after = batch.cursor;
+            const more = batch.has_more;
+            if (batch.events.length > 0)
+                yield batch;
+            if (!more)
+                await sleep(interval, options.signal);
+        }
+    }
+}
+/** Resolve a folder or recorded selector once, without planning, executing or starting a service.
+ * Later reads use the pinned absolute folder. The loading signal is not retained by the record. */
+export async function loadRun(target, options = {}) {
+    if (!text(target) || target.startsWith("-") || target.includes("\0")) {
+        throw new TypeError("target is a nonempty saved-run selector without a leading '-' or NUL");
+    }
+    if (options.verify !== undefined && typeof options.verify !== "boolean") {
+        throw new TypeError("verify is true or false");
+    }
+    const cwd = resolve(options.cwd ?? process.cwd());
+    const done = await call(["inspect", target, "--json", ...(options.verify === true ? ["--verify"] : [])], {
+        cwd,
+        ...(options.env !== undefined ? { env: options.env } : {}),
+        ...(options.signal !== undefined ? { signal: options.signal } : {}),
+    });
+    if (done.status !== 0 && !(options.verify === true && done.status === 1)) {
+        throw failure("inspect", done);
+    }
+    let inspection;
+    try {
+        inspection = JSON.parse(done.stdout);
+    }
+    catch {
+        throw failure("inspect", done);
+    }
+    if (!object(inspection) || !object(inspection.run))
+        throw failure("inspect", done);
+    if (done.status === 1) {
+        const verification = inspection.verification;
+        if (!object(verification) || verification.verified !== false
+            || !Array.isArray(verification.problems) || verification.problems.length === 0
+            || !verification.problems.every(text))
+            throw failure("inspect", done);
+    }
+    const folder = inspection.run.folder;
+    if (!text(folder) || folder.includes("\0")) {
+        throw failure("inspect", done);
+    }
+    return new RunRecord(resolve(cwd, folder), inspection, {
+        cwd, ...(options.env !== undefined ? { env: options.env } : {}),
+    });
+}

package/dist/request.d.ts

@@ -29,6 +29,10 @@ export interface RunOptions extends PlanOptions {
     /** The run folder, relative to `cwd` (`--run`); a folder holding a run of the same plan is
      * resumed. Default: a new folder under the project's runs folder. */
     readonly runDir?: string;
+    /** Create a named run (`--name`); an existing name is refused by the engine. */
+    readonly name?: string;
+    /** Continue an existing named run (`--resume`) with the same target and inputs. */
+    readonly resume?: string;
     /** Copy outputs out after the run (`--deliver OUTPUT=PATH`): `{ output: path }`, with `{key}`
      * in the path for each element of a collection. */
     readonly deliver?: Readonly<Record<string, string>>;