@grida/fx 0.1.0 → 0.2.0

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

package/dist/request.js

@@ -59,6 +59,16 @@ export function planningArgs(request, inputsFile) {
 /** The options of `run` alone. */
 export function runArgs(options) {
     const args = [];
+    const selected = ["runDir", "name", "resume"];
+    if (selected.filter((name) => options[name] !== undefined).length > 1) {
+        throw new TypeError("runDir, name and resume are mutually exclusive");
+    }
+    for (const name of selected) {
+        const value = options[name];
+        if (value !== undefined && (typeof value !== "string" || value === "" || value.includes("\0"))) {
+            throw new TypeError(`${name} is a nonempty string without NUL`);
+        }
+    }
     if (options.live !== undefined && typeof options.live !== "boolean") {
         throw new TypeError(`live is true or false, not ${JSON.stringify(options.live)}`);
     }
@@ -69,11 +79,12 @@ export function runArgs(options) {
         args.push(`--yes-up-to=${amountText("yesUpTo", options.yesUpTo)}`);
     }
     if (options.runDir !== undefined) {
-        if (typeof options.runDir !== "string" || options.runDir === "") {
-            throw new TypeError("runDir is a folder path");
-        }
         args.push(`--run=${options.runDir}`);
     }
+    if (options.name !== undefined)
+        args.push(`--name=${options.name}`);
+    if (options.resume !== undefined)
+        args.push(`--resume=${options.resume}`);
     for (const [name, path] of Object.entries(options.deliver ?? {})) {
         if (typeof path !== "string" || name === "" || path === "") {
             throw new TypeError(`deliver.${name} is a path`);

package/dist/runs.d.ts

@@ -0,0 +1,100 @@
+/** A project's runs through the engine's public command line (spec/store.md §8 and §9): listing
+ * them, and removing named ones. The engine finds the project from cwd, selects, locks and
+ * removes; this module only reads what it prints. */
+import { type CallOptions, type Exit } from "./engine.js";
+import { FxError } from "./errors.js";
+/** Where a run sits: `allocated` (`<runs>/<id>/<YYYY-MM-DD>-<n>`), `named`, `explicit`
+ * (elsewhere in the runs tree) or `external` (outside it, known from the run index or catalog). */
+export type RunPlacement = "allocated" | "named" | "explicit" | "external";
+/** A run's state as the listing reads its log. `empty`: no plan.json at a run's position;
+ * `removing`: a removal's tombstone; `missing`: an external folder that is gone. Recorded
+ * `unfinished` is not evidence that a process is alive. */
+export type RunState = "planned" | "unfinished" | "succeeded" | "failed" | "incomplete" | "cancelled" | "empty" | "removing" | "missing";
+/** One run of fx-run-list-v1. Wire fields retain lower_snake_case names. */
+export interface RunEntry {
+    /** The run folder as the engine printed it: relative to cwd, or absolute. */
+    readonly folder: string;
+    /** `folder` resolved once against cwd. */
+    readonly runDir: string;
+    /** The recorded workflow id, or the one its position gives; null when neither is known. */
+    readonly workflow: string | null;
+    /** The recorded workflow source; null for a folder without a plan. */
+    readonly source: string | null;
+    /** The run's name: recorded, or given by a named position. */
+    readonly name: string | null;
+    readonly placement: RunPlacement;
+    readonly state: RunState;
+    /** The first start's creation time (RFC 3339); null for a folder without a plan. */
+    readonly created_at: string | null;
+    /** What the run was charged; null before it ended. */
+    readonly charged_usd: number | null;
+    readonly stand_in: boolean;
+    /** Why an incomplete run stopped. */
+    readonly stopped?: string;
+}
+/** What removing one run did, or would do in a preview. */
+export interface RunRemovalEntry extends RunEntry {
+    /** `would_*`: a preview. `forgotten`: a missing external folder's index and catalog entries
+     * removed. `refused`: nothing of this run was removed. `partial`: the run is gone as a run but
+     * its tombstone remains; removing it again finishes it. */
+    readonly outcome: "would_remove" | "would_forget" | "removed" | "forgotten" | "refused" | "partial";
+    /** Present when refused or partial. */
+    readonly code?: "active" | "holds_pick" | "changed" | "not_removable" | "io";
+    /** Present when refused or partial. */
+    readonly message?: string;
+    /** Bytes of files whose every link was inside the run folder. */
+    readonly freed_bytes: number;
+    /** Bytes of files still linked from elsewhere (the store, other runs); not freed. */
+    readonly cache_bytes: number;
+}
+/** Why a selection passed a run over. Explicit runs are never passed over, so a removal by
+ * this SDK normally reports none. */
+export type RunRemovalSkip = "named" | "explicit" | "external" | "holds_pick" | "young" | "holds_runs";
+/** fx-run-removal-v1: what a removal did, or would do when `applied` is false. */
+export interface RunRemoval {
+    /** False for a preview: nothing was removed. */
+    readonly applied: boolean;
+    readonly runs: readonly RunRemovalEntry[];
+    /** How many runs a selection passed over, by reason. */
+    readonly skipped: Readonly<Partial<Record<RunRemovalSkip, number>>>;
+    readonly freed_bytes: number;
+    readonly cache_bytes: number;
+}
+/** The fx-run-removal-v1 error document: a RUN the engine would not resolve. Nothing was removed. */
+export interface RunRemovalFailure {
+    readonly kind: "fx-run-removal-v1";
+    readonly applied: false;
+    readonly error: {
+        readonly code: "invalid_target" | "ambiguous_target" | "not_a_run";
+        readonly message: string;
+        readonly run: string | null;
+    };
+}
+/** A removal the engine refused before removing anything, with its stable code, the RUN it
+ * names and the complete error document. Usage mistakes and malformed output reject with
+ * ordinary FxError; a refused or partial run does not reject (read each entry's `outcome`). */
+export declare class RunRemovalError extends FxError {
+    readonly code: RunRemovalFailure["error"]["code"];
+    readonly run: string | null;
+    readonly result: RunRemovalFailure;
+    constructor(result: RunRemovalFailure, done: Exit);
+}
+/** Options of listRuns. */
+export interface ListRunsOptions extends CallOptions {
+    /** Only the runs of this workflow id. */
+    readonly workflow?: string;
+}
+/** Options of removeRuns. */
+export interface RemoveRunsOptions extends CallOptions {
+    /** Report what would be removed and remove nothing (default: false). */
+    readonly preview?: boolean;
+}
+/** The runs of the project found from cwd, newest first. Reads only: no lock, no writes.
+ * Folders the engine could not read are left out. */
+export declare function listRuns(options?: ListRunsOptions): Promise<RunEntry[]>;
+/** Remove exactly the named runs: run folders (relative to cwd) or `WORKFLOW_ID/NAME` of named
+ * runs; select them with {@link listRuns} first. Every RUN is resolved before anything is removed,
+ * and one that is not a run rejects with {@link RunRemovalError}. A run that is active, or the last
+ * holding a pick, is refused without rejecting: read each entry's `outcome`. Aborting a removal
+ * may leave a run `partial`; removing it again finishes it. */
+export declare function removeRuns(runs: readonly string[], options?: RemoveRunsOptions): Promise<RunRemoval>;