@temporalio/agent-harness 0.0.0-stage → 0.2.0

package/dist/src/harness/code-mode/driver.js

@@ -0,0 +1,266 @@
+// The workflow-side host-call driver that runs one Code Mode script to completion.
+//
+// Each step runs in the sandbox as an activity (the worker package's code-mode/monty-stepper.ts):
+// the first type-checks the script and runs it to its first awaited batch of host calls, and each
+// later one resumes the suspended script with that batch's results, until the script finishes. Its
+// output and final value (or a script error) come back as text.
+//
+// The host-call surface is generic: the driver dispatches each call the script makes to the
+// matching harness tool via `runner.runTool`, so every host call inherits that tool's approval
+// policy and tool_start/tool_end lifecycle. A file operation on one of the tool's mounts is carried
+// out the same way, as fs_* tool calls against the mount's backend (see vfs.ts). Calls the script
+// made but has not awaited yet start as soon as a step hands them over, and keep running across
+// steps until the script awaits them.
+//
+// Workflow-safe: the sandbox only runs in activities; this side drives it by name.
+import { ActivityFailure, ApplicationFailure, CancellationScope, ChildWorkflowFailure, TemporalFailure, isCancellation, log, proxyActivities, sleep, uuid4, } from "@temporalio/workflow";
+import { pyRepr } from "./stubs.js";
+import { performFileOp } from "./vfs.js";
+export const CODE_START_BATCH_ACTIVITY = "code_start_batch";
+export const CODE_RESUME_BATCH_ACTIVITY = "code_resume_batch";
+export const CODE_TYPE_CHECK_ACTIVITY = "code_type_check";
+export const DEFAULT_STEP_TIMEOUT = "30 seconds";
+// A step that times out three times won't finish on a fourth.
+export const STEP_RETRY = { maximumAttempts: 3 };
+/** A pending call that is the script's `await asyncio.sleep(seconds)`, answered with a durable timer. */
+export const SLEEP_CALL = "asyncio.sleep";
+// Python's built-in exceptions a host failure keeps as its own type inside the script.
+const PYTHON_EXCEPTIONS = new Set([
+    "ArithmeticError",
+    "AssertionError",
+    "AttributeError",
+    "BufferError",
+    "ConnectionError",
+    "EOFError",
+    "Exception",
+    "FileExistsError",
+    "FileNotFoundError",
+    "FloatingPointError",
+    "ImportError",
+    "IndexError",
+    "IsADirectoryError",
+    "KeyError",
+    "LookupError",
+    "MemoryError",
+    "ModuleNotFoundError",
+    "NameError",
+    "NotADirectoryError",
+    "NotImplementedError",
+    "OSError",
+    "OverflowError",
+    "PermissionError",
+    "RecursionError",
+    "RuntimeError",
+    "TimeoutError",
+    "TypeError",
+    "UnicodeError",
+    "ValueError",
+    "ZeroDivisionError",
+]);
+// The errors a filesystem raises across a Temporal boundary as an ApplicationFailure of that type,
+// which the script sees as the built-in exception of that name.
+const OS_ERRORS = new Set([
+    "OSError",
+    "FileNotFoundError",
+    "FileExistsError",
+    "IsADirectoryError",
+    "NotADirectoryError",
+    "PermissionError",
+]);
+/**
+ * What a failed host call is to a script, as in the Python harness: a failed activity is unwrapped
+ * to its cause, which carries the tool's own message. A Python built-in keeps its type: an error
+ * named for one, or an ApplicationFailure of that type raised in workflow code (Python raises the
+ * built-in itself there). Anything else, an activity's failure included, arrives as
+ * `Exception("TypeName: message")` under its Python SDK name (`ApplicationError`, ...).
+ */
+function scriptError(e) {
+    const fromActivity = e instanceof ActivityFailure && e.cause !== undefined;
+    const error = fromActivity ? e.cause : e;
+    if (!(error instanceof Error))
+        return { error: String(error), error_type: "Exception" };
+    const builtin = error instanceof ApplicationFailure
+        ? fromActivity
+            ? undefined
+            : error.type
+        : error instanceof TemporalFailure
+            ? undefined
+            : error.name;
+    if (builtin && PYTHON_EXCEPTIONS.has(builtin))
+        return { error: error.message, error_type: builtin };
+    // Temporal's failures are Python's `*Error`s: ApplicationFailure is ApplicationError.
+    const name = error instanceof TemporalFailure ? error.name.replace(/Failure$/, "Error") : error.name;
+    return { error: `${name}: ${error.message}`, error_type: "Exception" };
+}
+/**
+ * A failed file operation as the script sees it: an OS error its filesystem raised across an
+ * activity or child workflow boundary is the built-in of that name, as in Python; anything else
+ * is any host call's failure.
+ */
+function fileOpError(e) {
+    let cause = e;
+    while (cause instanceof ActivityFailure || cause instanceof ChildWorkflowFailure)
+        cause = cause.cause;
+    if (cause instanceof ApplicationFailure && OS_ERRORS.has(cause.type ?? ""))
+        return { error: cause.message, error_type: cause.type };
+    return scriptError(e);
+}
+/** A host call's positional and keyword arguments, bound to the tool's parameter names. */
+function bindArgs(tool, { args, kwargs }) {
+    const names = Object.keys(tool.parameters.properties ?? {});
+    if (args.length > names.length) {
+        throw ApplicationFailure.create({
+            type: "HostCallBinding",
+            nonRetryable: true,
+            message: `host call '${tool.name}': too many positional arguments`,
+        });
+    }
+    const bound = {};
+    args.forEach((value, i) => (bound[names[i]] = value));
+    for (const [k, v] of Object.entries(kwargs)) {
+        if (k in bound)
+            throw ApplicationFailure.create({
+                type: "HostCallBinding",
+                nonRetryable: true,
+                message: `host call '${tool.name}': multiple values for '${k}'`,
+            });
+        bound[k] = v;
+    }
+    return bound;
+}
+/**
+ * Runs a Code Mode script to completion, dispatching its host calls to real harness tools.
+ *
+ * Constructed per invocation by the `codeModeTool` closure, with the live runner. `toolsByName` is
+ * validated once by the factory; `stubs` are the generated stubs the sandbox type-checks the
+ * script against before running it.
+ */
+export class CodeModeDriver {
+    #runner;
+    #toolsByName;
+    #injections;
+    #stubs;
+    #mounts;
+    #acts;
+    // Every call starts as soon as its step stops, so one awaited in a later step is already
+    // running, and calls the script never awaits are cancelled when it ends.
+    #running = new Map();
+    constructor(runner, toolsByName, options) {
+        this.#runner = runner;
+        this.#toolsByName = toolsByName;
+        this.#injections = options.injections;
+        this.#stubs = options.stubs;
+        this.#mounts = options.mounts;
+        this.#acts = proxyActivities({
+            startToCloseTimeout: options.stepTimeout,
+            retry: STEP_RETRY,
+        });
+    }
+    /** Drive `script` to completion; return its output and final value (or the error) as text. */
+    async runScript(script) {
+        const files = this.#mounts.length > 0;
+        log.info(`code_mode: starting batch run (script_len=${script.length})`);
+        // The script reads the workflow's clock and a seed drawn from the workflow's randomness.
+        const seed = Math.floor(Math.random() * 2 ** 32);
+        const clock = () => ({ now: Date.now(), seed });
+        const stdout = [];
+        let step = await (files
+            ? this.#acts.code_start_batch(script, this.#stubs, clock(), true)
+            : this.#acts.code_start_batch(script, this.#stubs, clock()));
+        try {
+            for (;;) {
+                stdout.push(step.stdout);
+                if (step.done)
+                    break;
+                for (const call of step.calls)
+                    if (!this.#running.has(call.call_id))
+                        this.#start(call);
+                let results;
+                if (step.file_op) {
+                    // A file operation: the calls made before it have started, and the operation runs now.
+                    results = [await this.#runFileOp(step.file_op)];
+                }
+                else {
+                    results = await Promise.all(step.awaiting.map((id) => {
+                        const entry = this.#running.get(id);
+                        if (entry === undefined)
+                            throw ApplicationFailure.create({
+                                type: "UnsupportedMontyFuture",
+                                nonRetryable: true,
+                                message: `the script awaits call ${id}, which it never made`,
+                            });
+                        this.#running.delete(id);
+                        return entry.result;
+                    }));
+                }
+                step = await this.#acts.code_resume_batch({
+                    snapshot: step.snapshot,
+                    results,
+                    type_names: this.#stubs.type_names,
+                    clock: clock(),
+                    ...(files ? { files } : {}),
+                });
+            }
+        }
+        finally {
+            // Calls the script made but never awaited before it ended.
+            for (const { scope } of this.#running.values())
+                scope.cancel();
+        }
+        if (step.error)
+            return `Script error (${step.error})`;
+        const parts = [];
+        const combined = stdout.join("").trim();
+        if (combined)
+            parts.push(`output:\n${combined}`);
+        parts.push(`result: ${pyRepr(step.output_json ? JSON.parse(step.output_json) : null)}`);
+        return parts.join("\n");
+    }
+    #start(call) {
+        const scope = new CancellationScope();
+        const result = scope.run(() => this.#runCall(call));
+        result.catch(() => undefined);
+        this.#running.set(call.call_id, { scope, result });
+    }
+    async #runCall(call) {
+        if (call.function_name === SLEEP_CALL) {
+            await sleep(Number(call.args[0]) * 1000);
+            return { call_id: call.call_id, return_value: null };
+        }
+        try {
+            const target = this.#toolsByName.get(call.function_name);
+            if (target === undefined) {
+                // Type-checking against the stubs should already reject an unknown name; if not, the
+                // script sees the failure at its await, as in Python.
+                throw ApplicationFailure.create({
+                    type: "UnknownHostFunction",
+                    nonRetryable: true,
+                    message: `script called unknown host function ${pyRepr(call.function_name)}`,
+                });
+            }
+            const result = await this.#runner.runTool(uuid4(), target, bindArgs(target, call), { injections: this.#injections });
+            return {
+                call_id: call.call_id,
+                return_value: JSON.parse(JSON.stringify(result ?? null)),
+            };
+        }
+        catch (e) {
+            if (isCancellation(e))
+                throw e;
+            return { call_id: call.call_id, return_value: null, ...scriptError(e) };
+        }
+    }
+    async #runFileOp(op) {
+        try {
+            const value = await performFileOp(this.#mounts, op, (t, input, backend) => this.#runner.runTool(uuid4(), t, input, {
+                injections: { backend },
+            }));
+            return { call_id: op.call_id, return_value: value };
+        }
+        catch (e) {
+            if (isCancellation(e))
+                throw e;
+            return { call_id: op.call_id, return_value: null, ...fileOpError(e) };
+        }
+    }
+}

package/dist/src/harness/code-mode/index.d.ts

@@ -0,0 +1,4 @@
+export * from "./driver.ts";
+export * from "./tool.ts";
+export { CodeModeStubError, pyRepr, renderHostInterface, renderTypeCheckStubs, type TypeCheckStubs, } from "./stubs.ts";
+export { FileTree, FsError, InMemoryFileSystem, Mount, osError, type FileStat, type FileSystem, type OsErrorType, type Seed, } from "./vfs.ts";

package/dist/src/harness/code-mode/index.js

@@ -0,0 +1,6 @@
+// Code Mode (Python's code_mode package): one tool that runs a model-written script over a set of
+// harness tools, the driver that steps it, and the sandbox's virtual filesystem.
+export * from "./driver.js";
+export * from "./tool.js";
+export { CodeModeStubError, pyRepr, renderHostInterface, renderTypeCheckStubs, } from "./stubs.js";
+export { FileTree, FsError, InMemoryFileSystem, Mount, osError, } from "./vfs.js";

package/dist/src/harness/code-mode/mount-decl.d.ts

@@ -0,0 +1,43 @@
+import { z } from "zod";
+import type { StateDecl, StateRef } from "../state/index.ts";
+import { type ActivityFilesystem } from "./activity-fs.ts";
+import { FileIndex } from "./vfs.ts";
+import { InMemoryFileSystem, Mount, type Seed } from "./vfs.ts";
+declare const DeclaredFileTree: z.ZodObject<{
+    files: z.ZodDefault<z.ZodRecord<z.ZodString, z.ZodObject<{
+        content: z.ZodString;
+        encoding: z.ZodDefault<z.ZodEnum<{
+            base64: "base64";
+            "utf-8": "utf-8";
+        }>>;
+        size: z.ZodNumber;
+    }, z.core.$strip>>>;
+    directories: z.ZodDefault<z.ZodArray<z.ZodString>>;
+    kind: z.ZodDefault<z.ZodLiteral<"file_tree">>;
+    mount: z.ZodDefault<z.ZodString>;
+    description: z.ZodDefault<z.ZodString>;
+    read_only: z.ZodDefault<z.ZodBoolean>;
+}, z.core.$strip>;
+type DeclaredFileTree = z.output<typeof DeclaredFileTree>;
+export interface VfsMountDecl<S extends z.ZodType<Record<string, unknown>>, C> extends StateDecl<S> {
+    bind(ref: StateRef<z.output<S>>, config: C, options?: {
+        timeout?: string | number;
+    }): Mount;
+}
+interface MemoryBind {
+    seed?: Seed;
+    maxBytes?: number;
+}
+export declare function vfsMount(path: string, backend: typeof InMemoryFileSystem, options: {
+    description: string;
+    readOnly?: boolean;
+}): VfsMountDecl<typeof DeclaredFileTree, MemoryBind | undefined>;
+export declare function vfsMount<C>(path: string, backend: ActivityFilesystem<C>, options: {
+    description: string;
+    readOnly?: boolean;
+}): VfsMountDecl<typeof FileIndex, C>;
+export declare function okfBundleVfsMount<C>(path: string, backend: ActivityFilesystem<C>, options: {
+    description: string;
+    readOnly?: boolean;
+}): VfsMountDecl<typeof FileIndex, C>;
+export {};

package/dist/src/harness/code-mode/mount-decl.js

@@ -0,0 +1,100 @@
+// Declaring a Code Mode mount as agent state. An in-memory mount keeps its files in a FileTree.
+// An activity-backed mount keeps a FileIndex of the paths the session has touched.
+import { z } from "zod";
+import {} from "./activity-fs.js";
+import { FileIndex, indexTrack } from "./vfs.js";
+import { OKF_VERSION } from "./okf.js";
+import { FileTree, InMemoryFileSystem, Mount } from "./vfs.js";
+const DeclaredFileTree = FileTree.extend({
+    kind: z.literal("file_tree").default("file_tree"),
+    mount: z.string().default(""),
+    description: z.string().default(""),
+    read_only: z.boolean().default(false),
+});
+function normalized(path) {
+    const parts = [];
+    for (const part of path.split("/")) {
+        if (part === "" || part === ".")
+            continue;
+        if (part === "..") {
+            if (!parts.length)
+                return path;
+            parts.pop();
+        }
+        else
+            parts.push(part);
+    }
+    return `/${parts.join("/")}`;
+}
+function checkPath(path) {
+    if (!path.startsWith("/") || normalized(path) !== path)
+        throw new TypeError(`mount path '${path}' must be an absolute, normalized POSIX path, like '/workspace'`);
+    if (path === "/")
+        throw new TypeError("a mount cannot be the root '/'; mount at a named directory");
+}
+function readOnlyOnReadOnlyFs(what, path, fs, readOnly) {
+    if (!readOnly && !fs.writable)
+        throw new TypeError(`${what}('${path}'): ${fs.name} is read-only (it implements no write methods); declare the mount with readOnly: true`);
+}
+function isActivityFilesystem(value) {
+    return (typeof value === "object" &&
+        value !== null &&
+        value.kind === "activity-filesystem" &&
+        typeof value.backend === "function");
+}
+export function vfsMount(path, backend, options) {
+    checkPath(path);
+    const readOnly = options.readOnly ?? false;
+    if (backend === InMemoryFileSystem) {
+        const decl = {
+            schema: DeclaredFileTree,
+            initial: () => ({
+                kind: "file_tree",
+                mount: path,
+                description: options.description,
+                read_only: readOnly,
+                files: {},
+                directories: [],
+            }),
+            bind(ref, config = {}) {
+                return new Mount(path, new InMemoryFileSystem({ state: ref, ...config }), {
+                    readOnly,
+                    description: options.description,
+                });
+            },
+        };
+        return decl;
+    }
+    if (!isActivityFilesystem(backend))
+        throw new TypeError(`vfsMount('${path}'): the backend must be InMemoryFileSystem or an ActivityFileSystem`);
+    return activityDecl("vfsMount", path, backend, options.description, readOnly, null);
+}
+export function okfBundleVfsMount(path, backend, options) {
+    checkPath(path);
+    if (!isActivityFilesystem(backend))
+        throw new TypeError(`okfBundleVfsMount('${path}'): the backend must be an ActivityFileSystem`);
+    return activityDecl("okfBundleVfsMount", path, backend, options.description, options.readOnly ?? false, OKF_VERSION);
+}
+function activityDecl(what, path, backend, description, readOnly, okfVersion) {
+    readOnlyOnReadOnlyFs(what, path, backend, readOnly);
+    return {
+        schema: FileIndex,
+        initial: () => ({
+            kind: "file_index",
+            mount: path,
+            description,
+            read_only: readOnly,
+            okf_version: okfVersion,
+            source: null,
+            entries: {},
+        }),
+        bind(ref, config, options) {
+            const fs = backend.backend(config, { timeout: options?.timeout, okfVersion });
+            return new Mount(path, fs, {
+                readOnly,
+                description,
+                tracked: indexTrack(ref, fs.source),
+            });
+        },
+    };
+}

package/dist/src/harness/code-mode/okf-tool.d.ts

@@ -0,0 +1,10 @@
+import { codeModeTool, type CodeModeTool } from "./tool.ts";
+import type { Mount } from "./vfs.ts";
+export declare function okfCodeModeTool(bundle: Mount, options: {
+    name: string;
+    tools?: Parameters<typeof codeModeTool>[0];
+    mounts?: readonly Mount[];
+    injections?: Record<string, unknown>;
+    inherentlySafe?: boolean;
+    autoApprovalCriteria?: string;
+}): CodeModeTool;

package/dist/src/harness/code-mode/okf-tool.js

@@ -0,0 +1,89 @@
+// A Code Mode tool for one OKF bundle: the mount, three host functions, and a contract section
+// that explains the format. Reads and writes stay ordinary file operations, so they are indexed.
+import { workflowInfo } from "@temporalio/workflow";
+import { z } from "zod";
+import { injected, tool } from "../agent.js";
+import { ActivityBackend } from "./activity-fs.js";
+import { codeModeTool } from "./tool.js";
+import { OKFConcept, OKFLinks, renderConcept } from "./okf.js";
+const BUNDLE = "okf_bundle";
+const bundleInjection = { [BUNDLE]: injected() };
+const okfConcepts = tool({
+    name: "okf_concepts",
+    description: 'Every concept in the OKF bundle, from its frontmatter, without reading bodies. `prefix` limits it to the concepts under a folder, by concept id (e.g. "trips"). Each concept\'s `path` is the file to read; `problem` says what is wrong with a concept whose frontmatter is missing or broken.',
+    inputSchema: z.object({ prefix: z.string().default("") }),
+    outputSchema: z.array(OKFConcept),
+    inherentlySafe: true,
+    injected: bundleInjection,
+    execute: async ({ prefix }, { okf_bundle }) => {
+        const stripped = prefix.replace(/^\/+|\/+$/g, "");
+        const graph = await okf_bundle.backend.okfGraph(stripped === "" ? "." : stripped, false);
+        return graph.concepts.map((concept) => ({
+            ...concept,
+            path: `${okf_bundle.mount}/${concept.path}`,
+        }));
+    },
+});
+const okfLinks = tool({
+    name: "okf_links",
+    description: "The concepts the concept `id` links to, and the concepts that link to it (by concept id). `dangling` marks a link to a concept that doesn't exist yet.",
+    inputSchema: z.object({ id: z.string() }),
+    outputSchema: OKFLinks,
+    inherentlySafe: true,
+    injected: bundleInjection,
+    execute: async ({ id }, { okf_bundle }) => {
+        const graph = await okf_bundle.backend.okfGraph(".", true);
+        const conceptId = id.replace(/^\/+|\/+$/g, "").replace(/\.md$/, "");
+        return {
+            id: conceptId,
+            links_to: graph.links.filter((link) => link.source === conceptId),
+            cited_by: graph.links.filter((link) => link.target === conceptId),
+        };
+    },
+});
+const okfRender = tool({
+    name: "okf_render",
+    description: "A concept's full text: `frontmatter` as YAML between `---` lines, then the markdown `body`. Fills in `generated` (who wrote it, and when) unless you give one, and the time of a `verified` entry given without `at`. Write the result to the concept's file with `Path(...).write_text(...)`.",
+    inputSchema: z.object({
+        frontmatter: z.record(z.string(), z.any()),
+        body: z.string(),
+    }),
+    outputSchema: z.string(),
+    inherentlySafe: true,
+    execute: async ({ frontmatter, body }) => renderConcept(frontmatter, body, {
+        by: workflowInfo().workflowType,
+        at: new Date(),
+    }),
+});
+function guide(mount, version) {
+    return `
+Knowledge bundle: \`${mount}\` is an Open Knowledge Format (OKF v${version}) bundle, a folder of markdown files you read and write with \`open()\` and \`pathlib\` like any other.
+
+- Every \`.md\` file is a concept, except \`index.md\` and \`log.md\`. A concept's id is its path in the bundle without \`.md\` (\`${mount}/trips/denver.md\` is \`trips/denver\`).
+- A concept starts with YAML frontmatter between \`---\` lines, then a markdown body. \`type\` is required: a short descriptive kind, such as \`Person\` or \`Plan\`. Also give \`title\` and \`description\` (ONE sentence). Optional: \`tags\` (a list), \`status\` (\`draft\`, \`stable\` or \`deprecated\`), \`stale_after\` (a UTC timestamp after which the concept is out of date), \`verified\` (a list of \`{by}\`, with \`by\` as \`human:<id>\` when a person confirmed it; \`okf_render\` adds the time), and \`sources\` (a list of \`{id, resource, title}\`).
+- Write concepts with \`okf_render(frontmatter, body)\`, which formats the frontmatter and records who wrote the concept and when: \`Path(...).write_text(await okf_render({...}, body))\`.
+- Link related concepts with ordinary markdown links relative to the linking file, e.g. \`[Ana](../people/ana.md)\`. Link only to concepts that exist, never to the concept itself, and once per mention.
+- Each folder has an \`index.md\` listing its concepts, one line each: \`* [Title](slug.md) - description\`, and subfolders as \`* [folder](folder/index.md) - summary\`. Keep it up to date whenever you add, retitle or remove a concept.
+- \`${mount}/log.md\` records changes, newest first, under \`## YYYY-MM-DD\` headings: \`* **Creation**: [Title](path.md) ...\`. Add an entry for every change.
+- To find concepts, call \`okf_concepts()\` rather than reading files one by one; then read the files you need. \`okf_links(id)\` gives a concept's links and backlinks.
+- Treat concepts marked \`stale\` or \`deprecated\` as out of date, and say so when you use them.
+`;
+}
+export function okfCodeModeTool(bundle, options) {
+    const backend = bundle.backend;
+    if (!(backend instanceof ActivityBackend) || !backend.okfVersion || bundle.tracked === null)
+        throw new TypeError(`okfCodeModeTool takes a bound okfBundleVfsMount(...), got '${bundle.path}'`);
+    if (options.injections && Object.hasOwn(options.injections, BUNDLE))
+        throw new TypeError(`injection name '${BUNDLE}' is reserved by okfCodeModeTool`);
+    return codeModeTool([...(options.tools ?? []), okfConcepts, okfLinks, okfRender], {
+        name: options.name,
+        inherentlySafe: options.inherentlySafe,
+        ...(options.autoApprovalCriteria ? { autoApprovalCriteria: options.autoApprovalCriteria } : {}),
+        injections: {
+            ...options.injections,
+            [BUNDLE]: { backend, mount: bundle.path },
+        },
+        mounts: [...(options.mounts ?? []), bundle],
+        guide: guide(bundle.path, backend.okfVersion),
+    });
+}

package/dist/src/harness/code-mode/okf.d.ts

@@ -0,0 +1,91 @@
+import { z } from "zod";
+export declare const OKF_VERSION = "0.2";
+export declare const RESERVED_NAMES: Set<string>;
+/** The most a walk reads, so a huge bundle can't stall the activity or the console. */
+export declare const MAX_OKF_CONCEPTS = 1000;
+export declare const MAX_OKF_FILE_BYTES = 256000;
+export declare const MAX_OKF_TOTAL_BYTES = 8000000;
+/** Without links only frontmatter is needed, so a walk reads each file's head first. */
+export declare const OKF_HEAD_BYTES = 8192;
+export declare const UNCLOSED_FRONTMATTER = "frontmatter is never closed with a `---` line";
+export declare const OKFConcept: z.ZodObject<{
+    id: z.ZodString;
+    path: z.ZodString;
+    type: z.ZodString;
+    title: z.ZodString;
+    description: z.ZodDefault<z.ZodString>;
+    tags: z.ZodDefault<z.ZodArray<z.ZodString>>;
+    status: z.ZodDefault<z.ZodString>;
+    trust_tier: z.ZodDefault<z.ZodEnum<{
+        "human-reviewed": "human-reviewed";
+        "machine-confirmed": "machine-confirmed";
+        unverified: "unverified";
+    }>>;
+    stale: z.ZodDefault<z.ZodBoolean>;
+    size: z.ZodNumber;
+    problem: z.ZodDefault<z.ZodNullable<z.ZodString>>;
+}, z.core.$strip>;
+export type OKFConcept = z.output<typeof OKFConcept>;
+export declare const OKFLink: z.ZodObject<{
+    source: z.ZodString;
+    target: z.ZodString;
+    dangling: z.ZodDefault<z.ZodBoolean>;
+}, z.core.$strip>;
+export type OKFLink = z.output<typeof OKFLink>;
+export declare const OKFLinks: z.ZodObject<{
+    id: z.ZodString;
+    links_to: z.ZodArray<z.ZodObject<{
+        source: z.ZodString;
+        target: z.ZodString;
+        dangling: z.ZodDefault<z.ZodBoolean>;
+    }, z.core.$strip>>;
+    cited_by: z.ZodArray<z.ZodObject<{
+        source: z.ZodString;
+        target: z.ZodString;
+        dangling: z.ZodDefault<z.ZodBoolean>;
+    }, z.core.$strip>>;
+}, z.core.$strip>;
+export type OKFLinks = z.output<typeof OKFLinks>;
+export declare const OKFGraph: z.ZodObject<{
+    concepts: z.ZodArray<z.ZodObject<{
+        id: z.ZodString;
+        path: z.ZodString;
+        type: z.ZodString;
+        title: z.ZodString;
+        description: z.ZodDefault<z.ZodString>;
+        tags: z.ZodDefault<z.ZodArray<z.ZodString>>;
+        status: z.ZodDefault<z.ZodString>;
+        trust_tier: z.ZodDefault<z.ZodEnum<{
+            "human-reviewed": "human-reviewed";
+            "machine-confirmed": "machine-confirmed";
+            unverified: "unverified";
+        }>>;
+        stale: z.ZodDefault<z.ZodBoolean>;
+        size: z.ZodNumber;
+        problem: z.ZodDefault<z.ZodNullable<z.ZodString>>;
+    }, z.core.$strip>>;
+    links: z.ZodDefault<z.ZodArray<z.ZodObject<{
+        source: z.ZodString;
+        target: z.ZodString;
+        dangling: z.ZodDefault<z.ZodBoolean>;
+    }, z.core.$strip>>>;
+    truncated: z.ZodDefault<z.ZodBoolean>;
+    walked_at: z.ZodNumber;
+}, z.core.$strip>;
+export type OKFGraph = z.output<typeof OKFGraph>;
+/** `(frontmatter, body, problem)`. `frontmatter` is null when there is none. */
+export declare function splitFrontmatter(text: string): [string | null, string, string | null];
+/**
+ * Concept ids `body` links to, in order, without repeats. Relative targets resolve against
+ * `conceptPath`; a target starting with `/` is relative to the bundle root. Links inside
+ * fenced code blocks, and links to the concept itself, are left out.
+ */
+export declare function linkTargets(body: string, conceptPath: string): string[];
+/**
+ * A concept's full text: `frontmatter` as YAML between `---` lines, then `body`.
+ * Records `generated` unless it is already present, and stamps a `verified` entry that has no `at`.
+ */
+export declare function renderConcept(frontmatter: Record<string, unknown>, body: string, generated: {
+    by: string;
+    at: Date;
+}): string;