@grida/fx 0.0.0-stage → 0.1.0-alpha.2

package/dist/errors.js

@@ -0,0 +1,27 @@
+/** Errors of `@grida/fx`. */
+/**
+ * The engine stopped with an error (exit status 2: unreadable input or a usage mistake), would
+ * not run (`refused: …`), was interrupted (130), or could not be found or started. `message` is
+ * the engine's own message, without its `grida-fx: ` prefix.
+ */
+export class FxError extends Error {
+    /** The engine's exit status; `null` when it never started or ended by a signal. */
+    exitCode;
+    /** The signal that ended the engine, if one did. */
+    signal;
+    /** What the engine wrote on stderr. */
+    stderr;
+    /** What the engine wrote on stdout. */
+    stdout;
+    /** The arguments the engine was given (after the binary). */
+    args;
+    constructor(message, details = {}) {
+        super(message, details.cause === undefined ? undefined : { cause: details.cause });
+        this.name = "FxError";
+        this.exitCode = details.exitCode ?? null;
+        this.signal = details.signal ?? null;
+        this.stderr = details.stderr ?? "";
+        this.stdout = details.stdout ?? "";
+        this.args = details.args ?? [];
+    }
+}

package/dist/index.d.ts

@@ -0,0 +1,15 @@
+/**
+ * Grida FX for JavaScript. The engine is the `grida-fx` command (this package installs it, with
+ * 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 { 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 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";
+export { type Platform, platformFor, platforms } from "./platforms.js";
+export type { PlanOptions, RunOptions } from "./request.js";
+export { type Assertion, type Budget, type Expression, expr, type GroupStep, type InputDeclaration, type InputField, type InputRef, type JsonValue, type KeepBest, type NodeStep, type Regeneration, type Step, type WorkflowDocument, workflow, } from "./workflow.js";
+export { needsQuotes, toYaml } from "./yaml.js";

package/dist/index.js

@@ -0,0 +1,12 @@
+/**
+ * Grida FX for JavaScript. The engine is the `grida-fx` command (this package installs it, with
+ * 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 { engineVersion, expand, identity, inspect, Plan, PlanRefused, plan, price, project, RunFile, RunResult, run, } from "./api.js";
+export { BINARY_VARIABLE, binary } from "./binary.js";
+export { FxError } from "./errors.js";
+export { platformFor, platforms } from "./platforms.js";
+export { expr, workflow, } from "./workflow.js";
+export { needsQuotes, toYaml } from "./yaml.js";

package/dist/platforms.d.ts

@@ -0,0 +1,31 @@
+/**
+ * The platforms the preview ships the engine for, one optional npm package each (as esbuild
+ * does). `@grida/fx` depends on all four as optional dependencies; npm installs the one whose
+ * `os`, `cpu` (and on Linux `libc`) fields match the machine. `tools/build_npm.mjs` reads this
+ * table to make those packages, so it is the one list of them.
+ *
+ * Windows is not in the preview: the engine's runner relies on Unix process groups and signals.
+ */
+/** One platform the engine is built for. */
+export interface Platform {
+    /** The Rust target triple the binary is built for. */
+    readonly triple: string;
+    /** The npm package that carries the binary, at `bin/grida-fx`. */
+    readonly package: string;
+    /** `process.platform` on that machine, and the package's `os` field. */
+    readonly os: "darwin" | "linux";
+    /** `process.arch` on that machine, and the package's `cpu` field. */
+    readonly cpu: "arm64" | "x64";
+    /** The package's `libc` field, for Linux: the binary links glibc (2.28 or later). */
+    readonly libc: "glibc" | null;
+    /** For people: what the platform is. */
+    readonly label: string;
+}
+/** Every platform of the preview. */
+export declare const platforms: readonly Platform[];
+/** The platform for `process.platform` and `process.arch`, or `null` when the preview has none. */
+export declare function platformFor(os: string, cpu: string): Platform | null;
+/** The platform built for a Rust target triple, or `null`. */
+export declare function platformForTriple(triple: string): Platform | null;
+/** Why the preview has no engine for this machine, in a sentence. */
+export declare function unsupportedReason(os: string, cpu: string): string;

package/dist/platforms.js

@@ -0,0 +1,61 @@
+/**
+ * The platforms the preview ships the engine for, one optional npm package each (as esbuild
+ * does). `@grida/fx` depends on all four as optional dependencies; npm installs the one whose
+ * `os`, `cpu` (and on Linux `libc`) fields match the machine. `tools/build_npm.mjs` reads this
+ * table to make those packages, so it is the one list of them.
+ *
+ * Windows is not in the preview: the engine's runner relies on Unix process groups and signals.
+ */
+/** Every platform of the preview. */
+export const platforms = [
+    {
+        triple: "aarch64-apple-darwin",
+        package: "@grida/fx-darwin-arm64",
+        os: "darwin",
+        cpu: "arm64",
+        libc: null,
+        label: "macOS on Apple silicon (arm64)",
+    },
+    {
+        triple: "x86_64-apple-darwin",
+        package: "@grida/fx-darwin-x64",
+        os: "darwin",
+        cpu: "x64",
+        libc: null,
+        label: "macOS on Intel (x64)",
+    },
+    {
+        triple: "x86_64-unknown-linux-gnu",
+        package: "@grida/fx-linux-x64-gnu",
+        os: "linux",
+        cpu: "x64",
+        libc: "glibc",
+        label: "Linux on x64 with glibc 2.28 or later",
+    },
+    {
+        triple: "aarch64-unknown-linux-gnu",
+        package: "@grida/fx-linux-arm64-gnu",
+        os: "linux",
+        cpu: "arm64",
+        libc: "glibc",
+        label: "Linux on arm64 with glibc 2.28 or later",
+    },
+];
+/** The platform for `process.platform` and `process.arch`, or `null` when the preview has none. */
+export function platformFor(os, cpu) {
+    return platforms.find((platform) => platform.os === os && platform.cpu === cpu) ?? null;
+}
+/** The platform built for a Rust target triple, or `null`. */
+export function platformForTriple(triple) {
+    return platforms.find((platform) => platform.triple === triple) ?? null;
+}
+/** Why the preview has no engine for this machine, in a sentence. */
+export function unsupportedReason(os, cpu) {
+    const supported = platforms.map((platform) => platform.label).join("; ");
+    const machine = `${os} on ${cpu}`;
+    if (os === "win32") {
+        return (`the preview of grida-fx does not run on Windows (the engine's runner uses Unix process ` +
+            `groups and signals). It runs on: ${supported}. On Windows, use WSL.`);
+    }
+    return `the preview of grida-fx has no engine for ${machine}. It runs on: ${supported}.`;
+}

package/dist/request.d.ts

@@ -0,0 +1,62 @@
+/**
+ * The command line of a request: a target and its options as the engine's planning verbs and
+ * `run` take them (`docs/guide/05-running.md`). Every option goes as `--name=value`, so a value
+ * that looks like a flag stays a value.
+ */
+import type { Environment } from "./binary.js";
+import type { CallOptions } from "./engine.js";
+/** Options of the planning verbs (`plan`, `expand`, `identity`, `price`) and of `run`. */
+export interface PlanOptions extends CallOptions {
+    /** Input values by name. They are written to a temporary inputs file in `cwd` (so relative
+     * paths in them keep their meaning) and given after `inputFiles`, so they win. */
+    readonly inputs?: Readonly<Record<string, unknown>>;
+    /** Inputs YAML files (`--inputs`), relative to `cwd`; later files win. */
+    readonly inputFiles?: readonly string[];
+    /** Route tables (`--routes`, `fx: routes/v1`); giving any leaves the built-in table out. */
+    readonly routes?: readonly string[];
+    /** Arguments of a builder target `file.py:function` (`--arg NAME=VALUE`). */
+    readonly args?: Readonly<Record<string, string | number | boolean>>;
+    /** The ceiling in US dollars (`--max-usd`); a live run needs one (here, in the workflow or in
+     * fx.yaml). */
+    readonly maxUsd?: number | string;
+}
+/** Options of `run`: the planning options, plus the run's own. */
+export interface RunOptions extends PlanOptions {
+    /** Admit paid provider calls (`--live`). Only `true` does; nothing turns it on by default. */
+    readonly live?: boolean;
+    /** Stop before a later phase that may take the run past this amount (`--yes-up-to`). */
+    readonly yesUpTo?: number | string;
+    /** 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;
+    /** 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>>;
+}
+/** A target with its planning options, resolved. */
+export interface PlanRequest {
+    readonly target: string;
+    readonly inputs: Readonly<Record<string, unknown>> | null;
+    readonly inputFiles: readonly string[];
+    readonly routes: readonly string[];
+    readonly args: readonly (readonly [string, string])[];
+    readonly maxUsd: string | null;
+    /** Absolute. */
+    readonly cwd: string;
+    readonly env: Environment | undefined;
+}
+/** The request of `target` and `options`. */
+export declare function makeRequest(target: string, options: PlanOptions): PlanRequest;
+/** The target and the planning options; `inputsFile` holds `request.inputs`. */
+export declare function planningArgs(request: PlanRequest, inputsFile: string | null): string[];
+/** The options of `run` alone. */
+export declare function runArgs(options: RunOptions): string[];
+/**
+ * An amount of US dollars as the command line takes it: decimal digits, never an exponent. A
+ * string is passed as it is; the engine reads it with its money rules and refuses what they do
+ * not allow.
+ */
+export declare function amountText(option: string, value: number | string | bigint): string;
+/** Runs `work` with `request.inputs` in a temporary inputs file in `cwd` (its name, relative);
+ * the file is removed after. */
+export declare function withInputsFile<T>(request: PlanRequest, work: (inputsFile: string | null) => Promise<T>): Promise<T>;

package/dist/request.js

@@ -0,0 +1,142 @@
+/**
+ * The command line of a request: a target and its options as the engine's planning verbs and
+ * `run` take them (`docs/guide/05-running.md`). Every option goes as `--name=value`, so a value
+ * that looks like a flag stays a value.
+ */
+import { randomBytes } from "node:crypto";
+import { unlink, writeFile } from "node:fs/promises";
+import { join, resolve } from "node:path";
+import { toYaml } from "./yaml.js";
+/** The request of `target` and `options`. */
+export function makeRequest(target, options) {
+    if (typeof target !== "string" || target === "") {
+        throw new TypeError("a target is a workflow file, a workflow id or a builder file.py:function, as a string");
+    }
+    if (target.startsWith("-")) {
+        throw new TypeError(`a target cannot start with "-" (${target}): write it as ./${target}`);
+    }
+    const inputs = options.inputs ?? null;
+    if (inputs !== null && (typeof inputs !== "object" || Array.isArray(inputs))) {
+        throw new TypeError("inputs is an object of input names to values");
+    }
+    const args = Object.entries(options.args ?? {}).map(([name, value]) => {
+        if (!["string", "number", "boolean"].includes(typeof value)) {
+            throw new TypeError(`args.${name} is a string, a number or a boolean`);
+        }
+        return [name, String(value)];
+    });
+    return {
+        target,
+        inputs: inputs !== null && Object.keys(inputs).length > 0 ? inputs : null,
+        inputFiles: strings("inputFiles", options.inputFiles),
+        routes: strings("routes", options.routes),
+        args,
+        maxUsd: options.maxUsd === undefined ? null : amountText("maxUsd", options.maxUsd),
+        cwd: resolve(options.cwd ?? process.cwd()),
+        env: options.env,
+    };
+}
+/** The target and the planning options; `inputsFile` holds `request.inputs`. */
+export function planningArgs(request, inputsFile) {
+    const args = [request.target];
+    for (const path of request.inputFiles) {
+        args.push(`--inputs=${path}`);
+    }
+    if (inputsFile !== null) {
+        args.push(`--inputs=${inputsFile}`);
+    }
+    for (const path of request.routes) {
+        args.push(`--routes=${path}`);
+    }
+    for (const [name, value] of request.args) {
+        args.push(`--arg=${name}=${value}`);
+    }
+    if (request.maxUsd !== null) {
+        args.push(`--max-usd=${request.maxUsd}`);
+    }
+    return args;
+}
+/** The options of `run` alone. */
+export function runArgs(options) {
+    const args = [];
+    if (options.live !== undefined && typeof options.live !== "boolean") {
+        throw new TypeError(`live is true or false, not ${JSON.stringify(options.live)}`);
+    }
+    if (options.live === true) {
+        args.push("--live");
+    }
+    if (options.yesUpTo !== undefined) {
+        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}`);
+    }
+    for (const [name, path] of Object.entries(options.deliver ?? {})) {
+        if (typeof path !== "string" || name === "" || path === "") {
+            throw new TypeError(`deliver.${name} is a path`);
+        }
+        args.push(`--deliver=${name}=${path}`);
+    }
+    return args;
+}
+/**
+ * An amount of US dollars as the command line takes it: decimal digits, never an exponent. A
+ * string is passed as it is; the engine reads it with its money rules and refuses what they do
+ * not allow.
+ */
+export function amountText(option, value) {
+    if (typeof value === "string" || typeof value === "bigint") {
+        return String(value);
+    }
+    if (typeof value !== "number" || !Number.isFinite(value)) {
+        throw new TypeError(`${option} is an amount of US dollars, not ${String(value)}`);
+    }
+    const text = Object.is(value, -0) ? "0" : String(value);
+    const exponent = /^(-?)([0-9]+)(?:\.([0-9]+))?e([-+][0-9]+)$/.exec(text);
+    if (exponent === null) {
+        return text;
+    }
+    const [, sign = "", whole = "", fraction = "", power = "0"] = exponent;
+    const digits = whole + fraction;
+    const point = whole.length + Number(power);
+    let written;
+    if (point <= 0) {
+        written = `0.${"0".repeat(-point)}${digits}`;
+    }
+    else if (point >= digits.length) {
+        written = digits + "0".repeat(point - digits.length);
+    }
+    else {
+        written = `${digits.slice(0, point)}.${digits.slice(point)}`;
+    }
+    return sign + written.replace(/^0+(?=[0-9])/, "");
+}
+/** Runs `work` with `request.inputs` in a temporary inputs file in `cwd` (its name, relative);
+ * the file is removed after. */
+export async function withInputsFile(request, work) {
+    if (request.inputs === null) {
+        return work(null);
+    }
+    const text = toYaml(request.inputs);
+    const name = `.grida-fx-inputs-${randomBytes(8).toString("hex")}.yaml`;
+    const path = join(request.cwd, name);
+    await writeFile(path, text, { encoding: "utf8", flag: "wx" });
+    try {
+        return await work(name);
+    }
+    finally {
+        await unlink(path).catch(() => undefined);
+    }
+}
+function strings(option, values) {
+    const list = [...(values ?? [])];
+    for (const value of list) {
+        if (typeof value !== "string" || value === "") {
+            throw new TypeError(`${option} holds paths, as strings`);
+        }
+    }
+    return list;
+}

package/dist/workflow.d.ts

@@ -0,0 +1,190 @@
+/**
+ * Workflow documents (`fx: workflow/v1`, `spec/schemas/fx-workflow-v1.schema.json`) as
+ * TypeScript types, and a small builder. The engine gives the document its meaning and checks
+ * it when it plans; these types only help write one. Write it out with `toYaml` and plan it:
+ *
+ * ```ts
+ * import { writeFile } from "node:fs/promises";
+ * import { expr, plan, toYaml, workflow } from "@grida/fx";
+ *
+ * const icon = workflow({
+ *   id: "icon",
+ *   title: "One item icon",
+ *   inputs: { name: { type: "string", description: "What the item is" } },
+ *   steps: {
+ *     draw: {
+ *       uses: "fx/image.generate@1",
+ *       with: { prompt: `A single ${expr("inputs.name")} game icon`, background: "transparent" },
+ *     },
+ *   },
+ *   outputs: { icon: expr("steps.draw.outputs.image") },
+ * });
+ * await writeFile("workflows/icon.yaml", toYaml(icon));
+ * const planned = await plan("workflows/icon.yaml", { inputs: { name: "copper lantern" } });
+ * ```
+ */
+/** A JSON value as FX holds it (`spec/identity.md` §1). */
+export type JsonValue = null | boolean | number | string | JsonValue[] | {
+    [key: string]: JsonValue;
+};
+/** An expression or a value that holds `${{ … }}` (kept as a string in the document). */
+export type Expression = string;
+/** One input declaration: a typed field, a `$ref` to another workflow's input, or a nested
+ * object of fields. */
+export type InputDeclaration = InputField | InputRef | {
+    [field: string]: InputDeclaration;
+};
+/** A typed input field. */
+export interface InputField {
+    type: "string" | "integer" | "number" | "boolean" | "file" | "files" | "list" | "map";
+    /** `file` and `files`: the file kind, or kind family, the input accepts. */
+    kind?: string;
+    /** `files`: the value is a glob pattern. */
+    glob?: boolean;
+    /** `list`: its items. */
+    items?: InputDeclaration;
+    /** `map`: its values. */
+    values?: InputDeclaration;
+    /** The input may be left out; it is then null. */
+    optional?: boolean;
+    description?: string;
+    default?: JsonValue;
+    enum?: JsonValue[];
+    minimum?: number;
+    maximum?: number;
+    exclusive_minimum?: number;
+    exclusive_maximum?: number;
+    multiple_of?: number;
+    min_length?: number;
+    max_length?: number;
+    pattern?: string;
+    min_items?: number;
+    max_items?: number;
+    unique_items?: boolean;
+    format?: string;
+    examples?: JsonValue[];
+}
+/** Another workflow's input: `<file>#/<json pointer>`. */
+export interface InputRef {
+    $ref: string;
+    optional?: boolean;
+    default?: JsonValue;
+    description?: string;
+}
+/** A spending ceiling. */
+export interface Budget {
+    max_usd: number;
+}
+/** A check made while planning, and again once what it reads exists. */
+export interface Assertion {
+    check: Expression | boolean;
+    message: string;
+    on_fail?: "fail" | "skip";
+}
+/** Which take to keep: the lowest or highest of a fact. */
+export interface KeepBest {
+    by: string;
+    order: "lowest" | "highest";
+}
+/** Redo a judged step, or a group, as further takes. */
+export interface Regeneration {
+    /** Takes in all, the first included: 1 to 12, or an expression known while planning. */
+    max: number | Expression;
+    then?: "fail" | "continue" | "skip" | {
+        keep_best: KeepBest;
+    };
+    until?: Expression | null;
+    feedback?: boolean;
+}
+/** Fields every step may have. */
+interface StepCommon {
+    if?: Expression | boolean | null;
+    needs?: string[];
+    /** Repeat over a list: an expression or a literal list. */
+    for_each?: Expression | JsonValue[] | null;
+    /** The name each repeated item takes (default `item`). */
+    as?: string;
+    key?: Expression | null;
+    max?: number | Expression | null;
+    matrix?: {
+        [name: string]: Expression | JsonValue[];
+    } | null;
+    assert?: Assertion[];
+    budget?: Budget | null;
+    concurrency?: number | null;
+    view?: boolean | string;
+    timeout?: number | null;
+    /** For readers; never part of what the step makes. */
+    title?: string | null;
+    description?: string | null;
+}
+/** A step that runs a node type. */
+export interface NodeStep extends StepCommon {
+    /** `fx/<name>@<major>` (built-in), `./<path>#<attr>` (a project node), or `./<path>.yaml`. */
+    uses: string;
+    /** The type's inputs and params; values holding `${{ }}` are expressions. */
+    with?: {
+        [name: string]: JsonValue;
+    };
+    /** The step this judge gives a verdict on. */
+    judges?: string | null;
+    on_reject?: "fail" | "continue" | "skip" | {
+        regenerate: Regeneration;
+    };
+    takes?: number | null;
+    pick?: "manual" | "first_accepted" | {
+        best: KeepBest;
+    } | null;
+    /** `plan`: a free, local, deterministic step that runs while planning. */
+    at?: "plan" | null;
+    /** The `model@provider` serving the type's one paid capability. */
+    route?: string | null;
+    /** Features the route must support. */
+    requires?: string[];
+    independent_of?: string | string[];
+}
+/** A group of steps, run together, maybe regenerated as a whole. */
+export interface GroupStep extends StepCommon {
+    steps: {
+        [name: string]: Step;
+    };
+    regenerate?: (Regeneration & {
+        until: Expression;
+    }) | null;
+}
+/** One step: a node type (`uses`) or a group (`steps`). */
+export type Step = NodeStep | GroupStep;
+/** A workflow file (`fx: workflow/v1`). */
+export interface WorkflowDocument {
+    fx: "workflow/v1";
+    /** Lower-case words joined by `-`, at most 96 characters. */
+    id: string;
+    title: string;
+    description?: string | null;
+    inputs?: {
+        [name: string]: InputDeclaration;
+    };
+    /** Constant data, read as `tables.<name>`. */
+    tables?: {
+        [name: string]: JsonValue;
+    };
+    /** Named expressions, read as `let.<name>`. */
+    let?: {
+        [name: string]: JsonValue;
+    };
+    budget?: Budget | null;
+    assert?: Assertion[];
+    steps: {
+        [name: string]: Step;
+    };
+    /** What a run returns: expressions over steps and inputs. */
+    outputs?: {
+        [name: string]: JsonValue;
+    };
+    view?: string | null;
+}
+/** A workflow document: `fields` with `fx: workflow/v1`. */
+export declare function workflow(fields: Omit<WorkflowDocument, "fx">): WorkflowDocument;
+/** `${{ <text> }}`: an expression, to write as a value or inside a string. */
+export declare function expr(text: string): Expression;
+export {};

package/dist/workflow.js

@@ -0,0 +1,33 @@
+/**
+ * Workflow documents (`fx: workflow/v1`, `spec/schemas/fx-workflow-v1.schema.json`) as
+ * TypeScript types, and a small builder. The engine gives the document its meaning and checks
+ * it when it plans; these types only help write one. Write it out with `toYaml` and plan it:
+ *
+ * ```ts
+ * import { writeFile } from "node:fs/promises";
+ * import { expr, plan, toYaml, workflow } from "@grida/fx";
+ *
+ * const icon = workflow({
+ *   id: "icon",
+ *   title: "One item icon",
+ *   inputs: { name: { type: "string", description: "What the item is" } },
+ *   steps: {
+ *     draw: {
+ *       uses: "fx/image.generate@1",
+ *       with: { prompt: `A single ${expr("inputs.name")} game icon`, background: "transparent" },
+ *     },
+ *   },
+ *   outputs: { icon: expr("steps.draw.outputs.image") },
+ * });
+ * await writeFile("workflows/icon.yaml", toYaml(icon));
+ * const planned = await plan("workflows/icon.yaml", { inputs: { name: "copper lantern" } });
+ * ```
+ */
+/** A workflow document: `fields` with `fx: workflow/v1`. */
+export function workflow(fields) {
+    return { fx: "workflow/v1", ...fields };
+}
+/** `${{ <text> }}`: an expression, to write as a value or inside a string. */
+export function expr(text) {
+    return `\${{ ${text} }}`;
+}

package/dist/yaml.d.ts

@@ -0,0 +1,21 @@
+/**
+ * Writing YAML that the engine reads: the strict subset of `spec/yaml.md`, written as the engine
+ * writes it ("Writing YAML", `crates/grida-fx-core/src/yaml/write.rs`).
+ *
+ * Block style, two-space indentation, keys in the order the object holds them. A string is
+ * written plain when, read back as a plain scalar, it is that same string; otherwise it is
+ * double-quoted with JSON-style escapes. So `on`, `017`, `2026-10-05`, `1e3`, a digest like
+ * `123e4567…`, `''`, and text with `: `, ` #` or a leading indicator are all quoted. Numbers are
+ * written in their canonical form (ECMAScript's, as JCS writes them). The text ends with one
+ * line feed.
+ *
+ * Only FX values are written (`spec/identity.md` §1): `null`, booleans, finite numbers, strings
+ * without lone surrogates, arrays, and plain objects, nested at most 512 deep. An object member
+ * whose value is `undefined` is left out, as JSON leaves it out; anything else is a `TypeError`
+ * naming where it is. A key longer than 1024 characters cannot be written (YAML's limit for an
+ * implicit key).
+ */
+/** Writes `value` as a YAML document the engine reads back as the same value. */
+export declare function toYaml(value: unknown): string;
+/** Whether a string must be quoted to read back as itself. */
+export declare function needsQuotes(text: string): boolean;