@evoke-build/evoke 0.6.0

package/dist/reflex.d.ts

@@ -0,0 +1,85 @@
+import type { Flag, Option, Pick, Value, Values, Word } from "./decision.ts";
+import type { Reflex } from "./runtime.ts";
+import type { Effect, Recognizer } from "./types.ts";
+/** `reflex.toml` as an object: no `run`, no `config` — a body closes over what it needs — no `reflex` key. */
+export interface InlineManifest {
+    description: string;
+    not_for?: string[];
+    tags?: string[];
+    /** Absent means destructive: every decision confirms. */
+    effect?: Effect;
+    /** The one-line template a person confirms, naming required arguments only. */
+    confirm: string;
+    args?: Record<string, InlineArg>;
+    /** What the body's `data` yields for a later step to take: per field, the recognizer that reads it, or a list of
+     *  records with such fields. */
+    yields?: Record<string, Recognizer | {
+        each: Record<string, Recognizer>;
+    }>;
+    examples?: InlineRecords;
+    tests?: InlineRecords;
+}
+/** An argument: its question and exactly one source; a flag is optional by nature. */
+export type InlineArg = {
+    ask: string;
+} & ({
+    options: Record<string, string>;
+    optional?: boolean;
+} | {
+    vocab: string;
+    optional?: boolean;
+} | {
+    pick: "number" | "duration";
+    range?: [number, number];
+    optional?: boolean;
+} | {
+    pick: "email" | "url" | "quoted";
+    optional?: boolean;
+} | {
+    flag: true;
+});
+/** Utterances with what they assert: a record per argument — the text, or `false` for unstated, `true` for a flag —
+ *  or `false` for never this reflex. */
+export type InlineRecords = Record<string, Record<string, string | boolean> | false>;
+type Typed<A> = A extends {
+    options: infer O;
+} ? Option<keyof O & string> : A extends {
+    vocab: string;
+} ? Word : A extends {
+    pick: infer P extends "number" | "duration";
+} ? Pick<P, number> : A extends {
+    pick: infer P extends "email" | "url" | "quoted";
+} ? Pick<P, string> : A extends {
+    flag: true;
+} ? Flag : never;
+type Absent<A> = A extends {
+    optional: true;
+} | {
+    flag: true;
+} ? true : false;
+type Flat<T> = {
+    [K in keyof T]: T[K];
+} & {};
+type ArgsOf<M extends InlineManifest> = NonNullable<M["args"]> extends Record<string, InlineArg> ? NonNullable<M["args"]> : Record<never, InlineArg>;
+/** What a decision carries for a reflex handed as code: its arguments as the wire types them, optional ones optional. */
+export type Carried<M extends InlineManifest> = Flat<{
+    [N in keyof ArgsOf<M> as Absent<ArgsOf<M>[N]> extends true ? never : N]: Typed<ArgsOf<M>[N]>;
+} & {
+    [N in keyof ArgsOf<M> as Absent<ArgsOf<M>[N]> extends true ? N : never]?: Typed<ArgsOf<M>[N]>;
+}>;
+/** What decisions carry for a map of reflexes handed as code: `load<Reflexes & ReflexesOf<typeof own>>` when a
+ *  project has installed reflexes beside them. */
+export type ReflexesOf<I> = {
+    [K in keyof I]: I[K] extends Inline<infer S> ? S : never;
+};
+/** The body's arguments, plain: what `reflex`'s body receives. */
+export type Args<M extends InlineManifest> = Values<Carried<M>>;
+/** What `reflex` returns and `load` takes; `shape` never holds a value — it is what a decision carries, for inference. */
+export interface Inline<S = Record<string, Value>> {
+    readonly manifest: InlineManifest;
+    readonly body: Reflex<Record<string, unknown>, Record<never, string>>;
+    readonly shape?: S | undefined;
+}
+/** A reflex as code: its body runs in-process, its arguments typed from the manifest. */
+export declare function reflex<const M extends InlineManifest>(manifest: M, body: Reflex<Args<M>, Record<never, string>>): Inline<Carried<M>>;
+export {};

package/dist/reflex.js

@@ -0,0 +1,8 @@
+// A reflex as code: the manifest as an object — the file's shape, less `run` and `config` — and its body, whose
+// argument types come from the manifest literal: option keys as a union, a word or a quoted, email or url pick as
+// a string, a number or duration as a number, a flag as `true`, an optional argument optional. In: a manifest
+// literal and a body. Out: an Inline, which `load` takes and runs in-process.
+/** A reflex as code: its body runs in-process, its arguments typed from the manifest. */
+export function reflex(manifest, body) {
+    return { manifest, body: body };
+}

package/dist/runtime.d.ts

@@ -0,0 +1,34 @@
+import { type Layers } from "./contain.ts";
+import type { Contained, Envelope, Refused, Setting } from "./types.ts";
+/** What a body returns: its text, and data when it gives some; for a file or an argv body, whether the machine
+ *  held its declaration. */
+export interface Result {
+    text: string;
+    data?: unknown;
+    contained?: Contained;
+}
+/** A body refused past its declaration, as the loader reported it: the project names the key and the fix. */
+export declare class Refusal extends Error {
+    readonly refused: Refused;
+    constructor(message: string, refused: Refused);
+}
+/** What a body receives beside its arguments. */
+export interface Context<Config> {
+    input: string;
+    config: Config;
+    signal: AbortSignal;
+}
+/** A body's own type: the function a file exports by default, and what `reflex` takes. */
+export type Reflex<Args, Config = Record<never, string>> = (args: Args, context: Context<Config>) => Result | string | Promise<Result | string>;
+/** A function body, in-process: its arguments as the envelope carries them, the deadline as its signal. */
+export declare function inline(what: string, body: Reflex<Record<string, unknown>, Record<string, string>>, envelope: Envelope, signal: AbortSignal | undefined): Promise<Result>;
+/** A file body, in a child: the loader started under the layers in the body's directory, fed the envelope with
+ *  the body's path under it. */
+export declare function child(what: string, dir: string, envelope: Envelope & {
+    run: string;
+}, layers: Layers, signal: AbortSignal | undefined): Promise<Result>;
+/** A program with its argv, under the layers, in the body's directory: config and the input in its
+ *  environment, its stdout the text. */
+export declare function program(what: string, argv: readonly string[], envelope: Envelope, layers: Layers, signal: AbortSignal | undefined): Promise<Result>;
+/** Each config setting as its value; a variable that is not set is the failure it names. */
+export declare function resolved(what: string, config: Record<string, Setting>): Record<string, string>;

package/dist/runtime.js

@@ -0,0 +1,254 @@
+// A body run, three ways: a function in-process under the deadline's signal; a file body in a child through the
+// same loader.mjs the CLI embeds, under the layers, in its own directory with a private TMPDIR, the envelope on
+// its stdin held open until it exits; a program spawned with an argv under the same layers, config as
+// EVOKE_CONFIG_<KEY> and the input as EVOKE_INPUT. Config is resolved from the environment here and only here; a
+// secret reaches the body and nothing else. In: the envelope, where the body lives, the layers, a signal. Out:
+// what the body returned, or a FailureError; a refusal, which the project names; the caller's abort passes
+// through as its own reason.
+import { spawn } from "node:child_process";
+import { fileURLToPath } from "node:url";
+import { flags, under } from "./contain.js";
+import { command } from "./core.js";
+import { FailureError } from "./errors.js";
+/** A body refused past its declaration, as the loader reported it: the project names the key and the fix. */
+export class Refusal extends Error {
+    refused;
+    constructor(message, refused) {
+        super(message);
+        this.name = "Refusal";
+        this.refused = refused;
+    }
+}
+/** The loader beside the package: the CLI's own file. */
+const LOADER = fileURLToPath(new URL("../runtime/loader.mjs", import.meta.url));
+/** What the scrubbed environment keeps. */
+const KEPT = ["PATH", "HOME", "TMPDIR", "LANG", "TERM"];
+/** What a body gets to settle after its signal aborts, and a group after SIGTERM before SIGKILL, in milliseconds. */
+const GRACE = 1000;
+/** A function body, in-process: its arguments as the envelope carries them, the deadline as its signal. */
+export async function inline(what, body, envelope, signal) {
+    signal?.throwIfAborted();
+    const config = resolved(what, envelope.config);
+    // Referenced timers: a body that hangs holding no handle cannot let the process exit before the deadline.
+    const timeout = new AbortController();
+    const timer = setTimeout(() => timeout.abort(new DOMException(`no answer within ${envelope.deadline} ms`, "TimeoutError")), envelope.deadline);
+    const own = signal === undefined ? timeout.signal : AbortSignal.any([signal, timeout.signal]);
+    let grace;
+    const abandoned = new Promise(resolve => {
+        const later = () => (grace = setTimeout(() => resolve({ abandoned: true }), GRACE));
+        if (own.aborted)
+            later();
+        else
+            own.addEventListener("abort", later, { once: true });
+    });
+    const settled = Promise.resolve()
+        .then(() => body(envelope.args, { input: envelope.input, config, signal: own }))
+        .then(returned => ({ ok: returned }), (error) => ({ threw: error }));
+    try {
+        const outcome = await Promise.race([settled, abandoned]);
+        if (signal?.aborted)
+            throw signal.reason;
+        if ("abandoned" in outcome)
+            throw failed(what, `did not finish within ${envelope.deadline} ms`);
+        if ("threw" in outcome) {
+            throw failed(what, outcome.threw instanceof Error ? outcome.threw.message : String(outcome.threw), undefined, outcome.threw);
+        }
+        return result(what, outcome.ok);
+    }
+    finally {
+        clearTimeout(timer);
+        if (grace !== undefined)
+            clearTimeout(grace);
+    }
+}
+/** A file body, in a child: the loader started under the layers in the body's directory, fed the envelope with
+ *  the body's path under it. */
+export async function child(what, dir, envelope, layers, signal) {
+    signal?.throwIfAborted();
+    const fed = {
+        run: `${dir}/${envelope.run}`,
+        args: envelope.args,
+        input: envelope.input,
+        config: resolved(what, envelope.config),
+        deadline: envelope.deadline,
+    };
+    // The loader warms Node's type stripper through an API still marked experimental: its warning is off, so a
+    // body's stderr is the body's.
+    const { file, args } = under(process.execPath, ["--disable-warning=ExperimentalWarning", ...flags(layers), LOADER], layers);
+    const started = spawn(file, args, {
+        cwd: dir,
+        detached: true,
+        env: scrubbed(layers.facts.tmp),
+        stdio: ["pipe", "pipe", "inherit"],
+    });
+    // A loader gone before it read is reported by its exit, not by the pipe.
+    started.stdin?.on("error", () => { });
+    started.stdin?.write(`${JSON.stringify(fed)}\n`);
+    // Stdin stays open until the child is gone: a body's life is bounded by its parent's.
+    const { output, code, timedOut, error } = await collected(started, envelope.deadline + 2 * GRACE, signal);
+    if (signal?.aborted)
+        throw signal.reason;
+    if (error !== undefined)
+        throw failed(what, error.message);
+    if (timedOut)
+        throw failed(what, `did not finish within ${envelope.deadline} ms`);
+    const line = output.split("\n")[0] ?? "";
+    let parsed;
+    try {
+        parsed = JSON.parse(line);
+    }
+    catch {
+        throw failed(what, line === "" ? (refusedProfile(code) ?? `${ended(code)} without a result`) : `the result line is not JSON: ${line}`);
+    }
+    if (parsed !== null && typeof parsed === "object" && "error" in parsed) {
+        const refused = "refused" in parsed ? parsed.refused : undefined;
+        if (refused !== null && typeof refused === "object" && "what" in refused && "path" in refused) {
+            throw new Refusal(String(parsed.error), { what: String(refused.what), path: String(refused.path) });
+        }
+        throw failed(what, String(parsed.error));
+    }
+    return result(what, parsed);
+}
+/** `sandbox-exec`'s own exit, when the code is one: a profile it refused before the program ran. */
+function refusedProfile(code) {
+    if (process.platform === "linux")
+        return undefined;
+    if (code === 65)
+        return "sandbox-exec refused the profile (exit 65)";
+    if (code === 71)
+        return "sandbox-exec is too old for the profile (exit 71)";
+    return undefined;
+}
+/** A program with its argv, under the layers, in the body's directory: config and the input in its
+ *  environment, its stdout the text. */
+export async function program(what, argv, envelope, layers, signal) {
+    signal?.throwIfAborted();
+    const [program, ...rest] = argv;
+    if (program === undefined)
+        throw failed(what, "the argv is empty");
+    const env = scrubbed(layers.facts.tmp);
+    for (const [key, value] of Object.entries(resolved(what, envelope.config))) {
+        env[`EVOKE_CONFIG_${key.toUpperCase()}`] = value;
+    }
+    env.EVOKE_INPUT = envelope.input;
+    const { file, args } = under(program, rest, layers);
+    const started = spawn(file, args, { cwd: layers.facts.body_dir, detached: true, env, stdio: ["ignore", "pipe", "inherit"] });
+    const { output, code, timedOut, error } = await collected(started, envelope.deadline, signal);
+    if (signal?.aborted)
+        throw signal.reason;
+    if (error !== undefined)
+        throw failed(what, error.message);
+    if (timedOut)
+        throw failed(what, `did not finish within ${envelope.deadline} ms`);
+    if (code !== 0)
+        throw failed(what, refusedProfile(code) ?? ended(code));
+    return { text: output.endsWith("\n") ? output.slice(0, -1) : output };
+}
+/** Each config setting as its value; a variable that is not set is the failure it names. */
+export function resolved(what, config) {
+    const values = {};
+    for (const [key, setting] of Object.entries(config)) {
+        if (setting.type === "plain") {
+            values[key] = setting.value;
+            continue;
+        }
+        const value = process.env[setting.var];
+        if (value === undefined) {
+            throw failed(what, `${setting.var} is not set`, { type: "export_key", var: setting.var });
+        }
+        values[key] = value;
+    }
+    return values;
+}
+/** The environment a body runs under: five variables, nothing else, `TMPDIR` the private folder made for the run. */
+function scrubbed(tmp) {
+    const env = {};
+    for (const name of KEPT) {
+        const value = process.env[name];
+        if (value !== undefined)
+            env[name] = value;
+    }
+    env.TMPDIR = tmp;
+    return env;
+}
+/** Everything the child writes until it exits — a grace for what is still in the pipe, so a grandchild that keeps
+ *  stdout cannot hold the run — then its code; past the wait, or on abort, the group is ended: SIGTERM, a grace,
+ *  SIGKILL. A child that could not start is the error it raised. */
+function collected(started, wait, signal) {
+    return new Promise(resolve => {
+        let output = "";
+        let timedOut = false;
+        let error;
+        let done = false;
+        let drain;
+        started.stdout?.setEncoding("utf8");
+        started.stdout?.on("data", (chunk) => {
+            output += chunk;
+        });
+        const settle = (code) => {
+            if (done)
+                return;
+            done = true;
+            clearTimeout(timer);
+            if (drain !== undefined)
+                clearTimeout(drain);
+            signal?.removeEventListener("abort", end);
+            resolve(error === undefined ? { output, code, timedOut } : { output, code, timedOut, error });
+        };
+        const end = () => {
+            timedOut = true;
+            if (started.pid === undefined)
+                return;
+            try {
+                process.kill(-started.pid, "SIGTERM");
+            }
+            catch {
+                return;
+            }
+            setTimeout(() => {
+                try {
+                    process.kill(-started.pid, "SIGKILL");
+                }
+                catch {
+                    // The group is already gone.
+                }
+            }, GRACE).unref();
+        };
+        const timer = setTimeout(end, wait);
+        if (signal?.aborted)
+            end();
+        else
+            signal?.addEventListener("abort", end, { once: true });
+        started.on("error", raised => {
+            error = raised;
+            settle(null);
+        });
+        started.on("exit", code => {
+            drain = setTimeout(() => settle(code), GRACE);
+        });
+        started.on("close", code => settle(code));
+    });
+}
+/** A body's return as a result: a string is the text; `{ text, data? }` passes; anything else is a failure. */
+function result(what, returned) {
+    if (typeof returned === "string")
+        return { text: returned };
+    if (returned !== null && typeof returned === "object" && "text" in returned && typeof returned.text === "string") {
+        return "data" in returned && returned.data !== undefined ? { text: returned.text, data: returned.data } : { text: returned.text };
+    }
+    throw failed(what, `the body returned ${describe(returned)}, not text or { text, data }`);
+}
+function describe(value) {
+    if (value === null)
+        return "null";
+    if (Array.isArray(value))
+        return "an array";
+    return typeof value === "object" ? "an object without text" : typeof value;
+}
+/** How a child ended: its code, or a signal. */
+function ended(code) {
+    return code === null ? "was killed" : `exited ${code}`;
+}
+function failed(what, why, fix = { type: "rerun" }, cause) {
+    return new FailureError(what, why, fix, command(fix, `run(d)`), cause === undefined ? undefined : { cause });
+}

package/dist/systemone.d.ts

@@ -0,0 +1,21 @@
+import type { Adapter } from "./adapter.ts";
+import { type Response } from "./https.ts";
+import type { Door, Gate } from "./types.ts";
+export interface DoorOptions {
+    /** The API key; absent, the door's own variable from the environment: `TYPESAFE_API_KEY` for jev, `OPENJEV_API_KEY` for openjev. */
+    key?: string | undefined;
+    /** Floors over the defaults, as `[adapters.<door>] gate = { … }` in evoke.toml. */
+    gate?: Partial<Gate> | undefined;
+}
+/** One POST: what the loop is written over, so a test can stand in for the network. */
+export type Post = (url: string, bearer: string, body: string, signal: AbortSignal, timeout: number) => Promise<Response>;
+/** The door, ready to answer; throws at once when no key is set, an override is not a probability, or the proxy
+ * named in the environment is no proxy address. */
+export declare function through(door: Door, options?: DoorOptions): Adapter;
+/** The proxy the environment names, as the CLI reads it: `https_proxy` before `HTTPS_PROXY`, `no_proxy` before
+ * `NO_PROXY`; an `http` or `https` address, else refused rather than bypassed in silence; and it needs the Node
+ * that carries `proxyEnv`. */
+export declare function proxied(door: Door): {
+    env: Record<string, string>;
+    via: string;
+} | undefined;

package/dist/systemone.js

@@ -0,0 +1,114 @@
+// The System One wire, behind two doors: jev, TypeSafe AI's own address under TYPESAFE_API_KEY, and openjev,
+// OpenJEV, an independent service that forwards requests to Jev, under OPENJEV_API_KEY. The mapping is the
+// core's — systemone.settings, systemone.request and systemone.answers through the module — and the SDK adds
+// the transport: one kept-alive agent for the process, through the proxy the environment names, the bearer key,
+// and the policy loop the settings declare: once more after a connect error or a retried status, never after a
+// client error, and a 429 that names a pause waited out and sent again while the deadline allows. In: a door and
+// its options. Out: an Adapter.
+import { Agent } from "node:https";
+import { call, command, fromCode, reply } from "./core.js";
+import { DiagnosticError, FailureError } from "./errors.js";
+import { Unanswered, post } from "./https.js";
+let shared;
+/** The door, ready to answer; throws at once when no key is set, an override is not a probability, or the proxy
+ * named in the environment is no proxy address. */
+export function through(door, options = {}) {
+    const proxy = proxied(door);
+    // One agent for the process. Through a proxy, the socket timeout is the one bound on the tunnel Node opens for
+    // it — no signal reaches that — so it is the decision's deadline; a direct connection is bounded by the request.
+    shared ??= new Agent({ keepAlive: true, ...(proxy === undefined ? {} : { proxyEnv: proxy.env, timeout: 30_000 }) });
+    const agent = shared;
+    return over(door, options, (url, bearer, body, signal, timeout) => post(url, bearer, body, agent, signal, timeout, proxy?.via));
+}
+/** The proxy the environment names, as the CLI reads it: `https_proxy` before `HTTPS_PROXY`, `no_proxy` before
+ * `NO_PROXY`; an `http` or `https` address, else refused rather than bypassed in silence; and it needs the Node
+ * that carries `proxyEnv`. */
+export function proxied(door) {
+    const [name, value] = process.env.https_proxy ? ["https_proxy", process.env.https_proxy] : ["HTTPS_PROXY", process.env.HTTPS_PROXY];
+    if (!value)
+        return undefined;
+    const url = URL.canParse(value) ? new URL(value) : undefined;
+    if (url === undefined || !/^https?:$/.test(url.protocol)) {
+        const fix = { type: "export_key", var: name };
+        throw new DiagnosticError([{ message: `${name} is not an http or https proxy address`, fix, command: command(fix) }]);
+    }
+    const [major = 0, minor = 0] = process.versions.node.split(".").map(Number);
+    if (major < 24 || (major === 24 && minor < 5)) {
+        throw new FailureError(`connecting through the proxy ${url.host}`, `needs Node 24.5 or newer, and this is ${process.versions.node}`, { type: "rerun" }, `${door}()`);
+    }
+    const bypass = process.env.no_proxy || process.env.NO_PROXY;
+    return { env: { HTTPS_PROXY: value, ...(bypass ? { NO_PROXY: bypass } : {}) }, via: url.host };
+}
+/** @internal The door over any transport; `through` gives it the network. */
+export function over(door, options, send) {
+    const table = options.table ?? (options.gate === undefined ? undefined : { gate: options.gate });
+    const settings = validated(door, table, options.table === undefined);
+    // An empty key is no key.
+    const key = options.key || process.env[settings.credential] || undefined;
+    if (key === undefined) {
+        const fix = { type: "export_key", var: settings.credential };
+        throw new DiagnosticError([{ message: `${door} needs ${settings.credential}, a key from ${settings.issuer}`, fix, command: command(fix) }]);
+    }
+    const { policy, url } = settings;
+    const [lowest, highest] = policy.retry_statuses;
+    const declared = settings.declared;
+    return {
+        id: declared.id,
+        ...(declared.limits === undefined ? {} : { limits: declared.limits }),
+        ...(declared.gate === undefined ? {} : { gate: declared.gate }),
+        async answer(state, questions, signal) {
+            const body = JSON.stringify(call("systemone.request", { request: { state, questions, proposed: [] } }));
+            let retried = 0;
+            for (;;) {
+                const again = retried < policy.retries;
+                let response;
+                try {
+                    response = await send(url, key, body, signal, policy.timeout);
+                }
+                catch (error) {
+                    if (error instanceof Unanswered && again && !error.connected && !signal.aborted) {
+                        retried += 1;
+                        continue;
+                    }
+                    throw error;
+                }
+                if (again && response.status >= lowest && response.status <= highest) {
+                    retried += 1;
+                    continue;
+                }
+                // The service asked for a pause before the next attempt: honoured until the deadline ends the wait.
+                if (response.status === 429 && response.retryAfter !== undefined && !signal.aborted) {
+                    await pausing(response.retryAfter, signal);
+                    if (!signal.aborted)
+                        continue;
+                }
+                return call("systemone.answers", { status: response.status, body: response.body, credential: settings.credential });
+            }
+        },
+    };
+}
+/** A pause the service asked for, ended early by the signal. */
+function pausing(ms, signal) {
+    return new Promise(resolve => {
+        const done = () => {
+            clearTimeout(timer);
+            signal.removeEventListener("abort", done);
+            resolve();
+        };
+        const timer = setTimeout(done, ms);
+        signal.addEventListener("abort", done, { once: true });
+    });
+}
+/** The door's settings from the table: a problem in a table from code ends in `<door>({ gate })`, in a file's in
+ * `evoke check`. */
+function validated(door, table, fromOptions) {
+    const answer = reply("systemone.settings", table === undefined ? { door } : { door, table });
+    if ("ok" in answer)
+        return answer.ok;
+    if ("bug" in answer)
+        throw new Error(`evoke's core hit a bug: ${answer.bug}`);
+    const problems = answer.err;
+    if (fromOptions)
+        throw fromCode(problems, `${door}({ gate })`);
+    throw new DiagnosticError(problems.map(problem => ({ ...problem, command: command(problem.fix, `${door}()`) })));
+}

package/dist/testing.d.ts

@@ -0,0 +1,7 @@
+import type { Adapter } from "./adapter.ts";
+export interface ReplayOptions {
+    /** Answers the file lacks are asked of this adapter and written back. */
+    record?: Adapter | undefined;
+}
+/** Answers from a recording; a miss is a fault naming the utterance, or, with `record`, the answer written back. */
+export declare function replay(file: string | URL, options?: ReplayOptions): Adapter;

package/dist/testing.js

@@ -0,0 +1,90 @@
+// @evoke-build/evoke/testing: the recorded adapter. A recording is the CLI's own answers.toml — the declaration,
+// then answers keyed by utterance identity — read and written through the core. With `record`, an utterance the
+// file lacks, or one recorded under fewer questions than are asked now, is asked of that adapter and the file
+// written back whole, so one run records a test suite and every run after is offline and deterministic. In: a
+// file, an adapter to record from. Out: an Adapter. Before each write the file is read again and merged, so two
+// suites recording into one file keep each other's answers.
+import { readFileSync, renameSync, unlinkSync, writeFileSync } from "node:fs";
+import { fileURLToPath } from "node:url";
+import { bug, call, faulted, reply } from "./core.js";
+import { DiagnosticError, FailureError } from "./errors.js";
+/** Answers from a recording; a miss is a fault naming the utterance, or, with `record`, the answer written back. */
+export function replay(file, options = {}) {
+    const path = typeof file === "string" ? file : fileURLToPath(file);
+    const again = `replay(${JSON.stringify(path)}, { record: jev() })`;
+    const recording = read(path, options.record, again);
+    return {
+        id: recording.id,
+        ...(recording.limits === undefined ? {} : { limits: recording.limits }),
+        ...(recording.gate === undefined ? {} : { gate: recording.gate }),
+        ...(recording.plan === undefined ? {} : { plan: recording.plan }),
+        async answer(state, questions, signal) {
+            const request = { state, questions, proposed: [] };
+            const identity = call("identity", { text: state.request });
+            const recorded = recording.answers[identity];
+            if (recorded !== undefined && Object.keys(questions).every(question => Object.hasOwn(recorded, question))) {
+                return call("replay.answer", { recording, request });
+            }
+            if (options.record === undefined) {
+                if (recorded !== undefined)
+                    return call("replay.answer", { recording, request });
+                throw faulted({ type: "unrecorded", identity }, again);
+            }
+            const raw = await options.record.answer(state, questions, signal);
+            // Another recorder may have written since this one read: the file is read again and merged under what
+            // this one holds, so two suites recording into one file lose nothing of each other's.
+            for (const [id, theirs] of Object.entries(read(path, options.record, again).answers)) {
+                recording.answers[id] = { ...theirs, ...recording.answers[id] };
+            }
+            recording.answers[identity] = { ...recording.answers[identity], ...recorded, ...raw };
+            write(path, call("replay.render", { recording }), again);
+            return call("replay.answer", { recording, request });
+        },
+    };
+}
+/** The recording as the file holds it; with `record` and no file yet, an empty one under that adapter's declaration. */
+function read(path, record, again) {
+    let text;
+    try {
+        text = readFileSync(path, "utf8");
+    }
+    catch (error) {
+        if (error.code !== "ENOENT")
+            throw error;
+        if (record === undefined)
+            throw refused(path, "there is no such file", again);
+        return {
+            id: record.id,
+            ...(record.limits === undefined ? {} : { limits: record.limits }),
+            ...(record.gate === undefined ? {} : { gate: record.gate }),
+            answers: {},
+        };
+    }
+    const answer = reply("replay.recording", { toml: text });
+    if ("ok" in answer)
+        return answer.ok;
+    if ("bug" in answer)
+        throw bug(answer.bug);
+    throw refused(path, String(answer.err), again);
+}
+/** Written whole beside the file, then moved into place: a reader never sees half a recording. */
+function write(path, text, again) {
+    const staged = `${path}.${process.pid}.tmp`;
+    try {
+        writeFileSync(staged, text);
+        renameSync(staged, path);
+    }
+    catch (error) {
+        try {
+            unlinkSync(staged);
+        }
+        catch {
+            // Nothing was staged.
+        }
+        throw new FailureError(`recording ${path}`, error instanceof Error ? error.message : String(error), { type: "rerun" }, again);
+    }
+}
+/** A file that is not a recording: the problem names it, and the fix is the call that records one. */
+function refused(path, why, again) {
+    return new DiagnosticError([{ message: `${path}: ${why}`, fix: { type: "rerun" }, command: again }]);
+}