@parcha/pi-durable-disk 0.0.0-stage → 0.1.0-beta.13

package/dist/serve.d.ts

@@ -0,0 +1,101 @@
+import type { Context, JsonValue } from "@earendil-works/chord";
+import type { Harness } from "@earendil-works/pi-durable";
+import type { RunRef } from "./claim.js";
+import { PdaError } from "./errors.js";
+import type { DurableRun } from "./run.js";
+import { type EnsureOptions, type EnsureResult, type HostDriver } from "./supervise.js";
+/** 503 codes the client answers by asking the supervisor again and retrying. */
+export declare const RETRY_CODES: readonly ["OPENING", "PARKING", "RELEASED"];
+export type ServeCode = (typeof RETRY_CODES)[number] | "BAD_REQUEST" | "UNAUTHORIZED" | "NOT_FOUND" | "BUSY" | "FAILED";
+export interface ServeOptions {
+    /** Default 0: any free port (the address is in `url` and in run.json's holder). */
+    readonly port?: number;
+    /** Default 127.0.0.1. Any address that is not loopback needs `token`; a wildcard (0.0.0.0, ::) needs `url` too. */
+    readonly host?: string;
+    /**
+     * The address clients reach this server at (`http://` or `https://`), which goes into run.json's holder. Default: the
+     * bound address, which only works for a specific host; a wildcard bind has no address a client can use.
+     */
+    readonly url?: string;
+    /** Every request must carry `authorization: Bearer <token>` (see `readServeToken`). Optional on loopback only. */
+    readonly token?: string;
+    /** How the root conversation is created when absent (pi's `root()` options); a submit without `conversationId` goes there. */
+    readonly root?: Parameters<Harness["root"]>[1];
+    /** Called each time the last open request ends (parking looks again). */
+    readonly onIdle?: () => void;
+    readonly context?: Context;
+}
+export interface RunServer {
+    /** `http://<host>:<port>`. */
+    readonly url: string;
+    /** Open requests: submits waiting for their answer, event streams. */
+    readonly active: number;
+    /** Serve this run (until then every request is 503 OPENING). */
+    attach(run: DurableRun): void;
+    /** Refuse new submissions with 503 PARKING; the returned function admits them again. */
+    pause(): () => void;
+    close(): Promise<void>;
+}
+export type ServeConfigErrorCode = "SERVE_TOKEN_REQUIRED" | "SERVE_TOKEN_INVALID" | "SERVE_URL_REQUIRED" | "SERVE_URL_INVALID";
+/**
+ * A non-loopback address without a token, a token file that is missing, empty or not private, or a wildcard bind
+ * without the URL clients reach it at. Exit 2 (usage).
+ */
+export declare class ServeConfigError extends PdaError {
+    constructor(code: ServeConfigErrorCode, message: string, options?: {
+        cause?: unknown;
+    });
+}
+/** 127.0.0.0/8, ::1 (also as an IPv4-mapped address) and `localhost`; everything else reaches the network. */
+export declare function isLoopback(host: string): boolean;
+/**
+ * The serve token from `path`: a regular file no one but its owner may read or write (0600 or stricter), holding one
+ * token without whitespace. Read from a file so it is never in argv or an environment.
+ */
+export declare function readServeToken(path: string): string;
+/** Start listening; requests are answered once `attach` hands over the open run. */
+export declare function serveRun(options?: ServeOptions): Promise<RunServer>;
+export type ServeErrorCode = "RUN_TERMINAL" | "NOT_SERVED";
+/** The run is done or failed (RUN_TERMINAL), or no instance answered before the deadline (NOT_SERVED). */
+export declare class ServeError extends PdaError {
+    readonly ensured: readonly EnsureResult[];
+    constructor(code: ServeErrorCode, message: string, ensured: readonly EnsureResult[]);
+}
+export interface RequestOptions {
+    readonly host: HostDriver;
+    /** ensureRunning's options; every call here is a demand. */
+    readonly ensure: Omit<EnsureOptions, "demand">;
+    /** Give up after this long; default 120 s. A submit that waits for its answer needs room for the model. */
+    readonly timeoutMs?: number;
+    /**
+     * How long an instance this call started may take to open before the supervisor is asked again; default 60 s. Until
+     * then a second start would only be refused (76): the control API can list the new mount late.
+     */
+    readonly startTimeoutMs?: number;
+    /** The instance's serve token, sent as `authorization: Bearer <token>`. */
+    readonly token?: string;
+    readonly fetch?: typeof fetch;
+}
+export type RunResponse = {
+    readonly status: number;
+    readonly body: JsonValue;
+    /** The instance that answered. */
+    readonly url: string;
+    /** Every ensureRunning result on the way, in order (empty when the instance answered at once). */
+    readonly ensured: readonly EnsureResult[];
+};
+/**
+ * Send one request to run `ref`'s instance, waking it if needed: read run.json (S3) and send the request to the running
+ * holder's `serve` address while its lease is fresh. When there is none, it does not answer, it answers 503 with a
+ * retry code, or its lease lapses while the request is open (a frozen instance accepts connections and never answers;
+ * run.json is read again every third of a lease), ask `ensureRunning` with demand (start a released or lost run) and
+ * try again until `timeoutMs`. After a start, its own or one the supervisor reports `starting`, it waits for that
+ * instance to write its generation (or `startTimeoutMs`) before asking again, and an instance still opening (503
+ * OPENING) is waited for. A submit carries a `requestId`, so
+ * resending it to the next incarnation is safe: pi admits it once.
+ */
+export declare function requestRun(ref: RunRef, request: {
+    readonly method: "GET" | "POST";
+    readonly path: string;
+    readonly body?: JsonValue;
+}, options: RequestOptions): Promise<RunResponse>;

package/dist/serve.js

@@ -0,0 +1,393 @@
+// The serve mode, a Durable Object stub's fetch over pi's own API. The instance answers `POST /submit` (pi's
+// submit with the caller's `requestId`, which pi deduplicates in the run's store, so a retry that lands on the next
+// incarnation finds the same submission), `POST /abort`, `GET /events` (pi's agent events as server-sent events) and
+// `GET /status`. It listens before the run opens, so its address can go into run.json's holder, and answers 503 with a
+// code while the run opens, parks or is released. `requestRun` is the client: it finds the instance through run.json,
+// starts the run through `ensureRunning` (with demand) when it is released or gone, and retries while it starts.
+// Open requests keep the instance up (parking waits for none). On loopback a bearer token is optional; on any other
+// address it is required, read from a private file, and checked in constant time on every route.
+import { createHash, timingSafeEqual } from "node:crypto";
+import { readFileSync, statSync } from "node:fs";
+import { createServer } from "node:http";
+import { isIP } from "node:net";
+import { BACKGROUND_CONTEXT, withAbortSignal } from "@earendil-works/chord/context";
+import { ConversationBusy, watchEvents } from "@earendil-works/pi-durable";
+import { PdaError } from "./errors.js";
+import { busyState } from "./park.js";
+import { isLeaseFresh } from "./status.js";
+import { CONTROL_TIMEOUT_MS, ensureRunning, LEASE_EXPIRY_MS, readRunStatus, withTimeouts } from "./supervise.js";
+/** 503 codes the client answers by asking the supervisor again and retrying. */
+export const RETRY_CODES = ["OPENING", "PARKING", "RELEASED"];
+const MAX_BODY = 1 << 20;
+const REQUEST_ID = /^[\x21-\x7e]{1,200}$/;
+/**
+ * A non-loopback address without a token, a token file that is missing, empty or not private, or a wildcard bind
+ * without the URL clients reach it at. Exit 2 (usage).
+ */
+export class ServeConfigError extends PdaError {
+    constructor(code, message, options = {}) {
+        super(code, message, { cause: options.cause, exitCode: 2 });
+    }
+}
+/** 127.0.0.0/8, ::1 (also as an IPv4-mapped address) and `localhost`; everything else reaches the network. */
+export function isLoopback(host) {
+    const h = host.toLowerCase();
+    if (h === "localhost" || h === "::1")
+        return true;
+    if (isIP(h) === 4)
+        return h.startsWith("127.");
+    return h.startsWith("::ffff:127.") && isIP(h) === 6;
+}
+/**
+ * The serve token from `path`: a regular file no one but its owner may read or write (0600 or stricter), holding one
+ * token without whitespace. Read from a file so it is never in argv or an environment.
+ */
+export function readServeToken(path) {
+    let mode;
+    try {
+        const st = statSync(path);
+        if (!st.isFile())
+            throw new Error("not a regular file");
+        mode = st.mode & 0o777;
+    }
+    catch (cause) {
+        throw new ServeConfigError("SERVE_TOKEN_INVALID", `cannot use ${path} as the serve token file: ${cause.message}`, { cause });
+    }
+    if (mode & 0o077)
+        throw new ServeConfigError("SERVE_TOKEN_INVALID", `${path} has mode ${mode.toString(8)}; the serve token file must be 0600`);
+    const token = readFileSync(path, "utf8").trim();
+    if (!token || /\s/.test(token))
+        throw new ServeConfigError("SERVE_TOKEN_INVALID", `${path} holds no token, or one with whitespace`);
+    return token;
+}
+const digest = (text) => createHash("sha256").update(text).digest();
+/** 0.0.0.0, :: and their spellings: every address of the host, none of which a client can be told. */
+const isWildcard = (host) => {
+    const h = host.toLowerCase();
+    return h === "0.0.0.0" || h === "::" || h === "[::]" || h === "0:0:0:0:0:0:0:0" || h === "::ffff:0.0.0.0";
+};
+class HttpError extends Error {
+    status;
+    code;
+    constructor(status, code, message) {
+        super(message);
+        this.status = status;
+        this.code = code;
+    }
+}
+const unavailable = (code, message) => new HttpError(503, code, message);
+function send(res, status, body) {
+    const text = JSON.stringify(body);
+    res.writeHead(status, { "content-type": "application/json", "content-length": Buffer.byteLength(text), ...(status === 503 ? { "retry-after": "1" } : {}) });
+    res.end(text);
+}
+async function readJson(req) {
+    let size = 0;
+    const chunks = [];
+    for await (const chunk of req) {
+        size += chunk.length;
+        if (size > MAX_BODY)
+            throw new HttpError(413, "BAD_REQUEST", `body over ${MAX_BODY} bytes`);
+        chunks.push(chunk);
+    }
+    if (size === 0)
+        return {};
+    let value;
+    try {
+        value = JSON.parse(Buffer.concat(chunks).toString("utf8"));
+    }
+    catch {
+        throw new HttpError(400, "BAD_REQUEST", "body is not JSON");
+    }
+    if (typeof value !== "object" || value === null || Array.isArray(value))
+        throw new HttpError(400, "BAD_REQUEST", "body is not a JSON object");
+    return value;
+}
+const optionalId = (value, name) => {
+    if (value === undefined)
+        return undefined;
+    if (!Number.isSafeInteger(value) || value < 0)
+        throw new HttpError(400, "BAD_REQUEST", `${name} must be a non-negative integer`);
+    return value;
+};
+/** The text of an answer entry (an assistant message's text blocks). */
+async function answerOf(conversation, entry, context) {
+    const page = await conversation.entries({ minEntryId: entry, maxEntryId: entry }, 1, undefined, context);
+    const text = (page.items[0]?.model ?? [])
+        .flatMap((m) => (m.role === "assistant" ? m.content.flatMap((b) => (b.type === "text" ? [b.text] : [])) : []))
+        .join("");
+    return { entry, text };
+}
+/** Start listening; requests are answered once `attach` hands over the open run. */
+export async function serveRun(options = {}) {
+    const base = options.context ?? BACKGROUND_CONTEXT;
+    const bind = options.host ?? "127.0.0.1";
+    if (options.token !== undefined && (!options.token || /\s/.test(options.token)))
+        throw new ServeConfigError("SERVE_TOKEN_INVALID", "the serve token is empty or has whitespace");
+    if (options.token === undefined && !isLoopback(bind)) {
+        throw new ServeConfigError("SERVE_TOKEN_REQUIRED", `serving on ${bind}, which is not loopback, needs a bearer token (--serve-token-file)`);
+    }
+    if (options.url !== undefined && !["http:", "https:"].includes(URL.parse(options.url)?.protocol ?? "")) {
+        throw new ServeConfigError("SERVE_URL_INVALID", `${options.url} is not an http:// or https:// address`);
+    }
+    if (options.url === undefined && isWildcard(bind)) {
+        throw new ServeConfigError("SERVE_URL_REQUIRED", `serving on ${bind} binds every address; name the one clients reach (--serve-url)`);
+    }
+    // Both sides are hashed to one length, so the comparison takes the same time whatever the caller sent.
+    const expected = options.token === undefined ? undefined : digest(`Bearer ${options.token}`);
+    const authorized = (req) => expected === undefined || timingSafeEqual(digest(req.headers.authorization ?? ""), expected);
+    let run;
+    let closed = false;
+    let pauses = 0;
+    let active = 0;
+    const hold = () => void active++;
+    const letGo = () => {
+        if (--active === 0)
+            options.onIdle?.();
+    };
+    const harness = () => {
+        if (!run)
+            throw unavailable("OPENING", "the run is still opening");
+        if (closed || run.fenced)
+            throw unavailable("RELEASED", "the run is released or fenced on this instance");
+        return run.harness;
+    };
+    const conversationOf = async (id, context) => {
+        const h = harness();
+        if (id === undefined)
+            return h.root(context, options.root);
+        const conversation = await h.conversation(id, context);
+        if (!conversation)
+            throw new HttpError(404, "NOT_FOUND", `no conversation ${id}`);
+        return conversation;
+    };
+    async function submit(body, context) {
+        const { requestId, content, whenBusy, wait } = body;
+        if (typeof requestId !== "string" || !REQUEST_ID.test(requestId))
+            throw new HttpError(400, "BAD_REQUEST", "requestId must be 1 to 200 printable ASCII characters");
+        if (typeof content !== "string" && !Array.isArray(content))
+            throw new HttpError(400, "BAD_REQUEST", "content must be a string or an array of content blocks");
+        if (whenBusy !== undefined && whenBusy !== "steer" && whenBusy !== "followUp" && whenBusy !== "reject")
+            throw new HttpError(400, "BAD_REQUEST", "whenBusy is steer, followUp or reject");
+        if (pauses > 0)
+            throw unavailable("PARKING", "the run is parking or draining");
+        const conversation = await conversationOf(optionalId(body.conversationId, "conversationId"), context);
+        const submission = await conversation.submit({ type: "input", requestId, content: content, ...(whenBusy === undefined ? {} : { whenBusy }) }, context);
+        let record = await submission.status(context);
+        if (wait === true)
+            record = await submission.wait(context);
+        const answer = record.type === "input" && record.status === "done" ? await answerOf(conversation, record.answer, context) : undefined;
+        return { run: run.ref.id, generation: run.generation, submission: record, ...(answer ? { answer } : {}) };
+    }
+    async function abort(body, context) {
+        const submissionId = optionalId(body.submissionId, "submissionId");
+        const conversationId = optionalId(body.conversationId, "conversationId");
+        if (submissionId !== undefined) {
+            const result = await harness().abortSubmission(submissionId, context, conversationId);
+            if (result === "not_found")
+                throw new HttpError(404, "NOT_FOUND", `no submission ${submissionId}`);
+            return { result };
+        }
+        await (await conversationOf(conversationId, context)).abort(context);
+        return { result: "aborted" };
+    }
+    async function status(context) {
+        const inspection = await harness().inspect(context);
+        return {
+            run: run.ref.id,
+            generation: run.generation,
+            status: run.record.status,
+            busy: busyState(inspection, Date.now(), 0),
+            scheduling: inspection.scheduling,
+            tasks: inspection.tasks.map((t) => ({ id: t.record.id, kind: t.record.kind, state: t.state.kind })),
+            submissions: inspection.submissions.length,
+        };
+    }
+    async function events(req, res, url, context) {
+        const raw = url.searchParams.get("conversationId");
+        const conversation = await conversationOf(raw === null ? undefined : optionalId(Number(raw), "conversationId"), context);
+        const stream = await watchEvents(harness(), conversation.id, base);
+        const write = (event, data) => void res.write(`event: ${event}\ndata: ${JSON.stringify(data)}\n\n`);
+        res.writeHead(200, { "content-type": "text/event-stream", "cache-control": "no-cache", connection: "keep-alive" });
+        hold();
+        write("snapshot", stream.snapshot);
+        stream.start(async (batch) => write("events", batch));
+        req.once("close", () => void stream.stop());
+        void stream.closed.then((end) => {
+            write("end", { reason: end.reason });
+            res.end();
+            letGo();
+        });
+    }
+    const server = createServer((req, res) => {
+        if (!authorized(req)) {
+            res.setHeader("www-authenticate", "Bearer");
+            return send(res, 401, { error: "UNAUTHORIZED", message: "a bearer token is required" });
+        }
+        const abortOnClose = new AbortController();
+        res.once("close", () => abortOnClose.abort());
+        const context = withAbortSignal(abortOnClose.signal, base);
+        const url = new URL(req.url ?? "/", "http://serve");
+        const route = `${req.method} ${url.pathname}`;
+        const answer = async () => {
+            switch (route) {
+                case "POST /submit": {
+                    const body = await readJson(req);
+                    hold();
+                    try {
+                        return send(res, 200, await submit(body, context));
+                    }
+                    finally {
+                        letGo();
+                    }
+                }
+                case "POST /abort":
+                    return send(res, 200, await abort(await readJson(req), context));
+                case "GET /status":
+                    return send(res, 200, await status(context));
+                case "GET /events":
+                    return events(req, res, url, context);
+                default:
+                    throw new HttpError(404, "NOT_FOUND", `no route ${route}`);
+            }
+        };
+        answer().catch((error) => {
+            if (res.headersSent)
+                return void res.end();
+            if (error instanceof HttpError)
+                return send(res, error.status, { error: error.code, message: error.message });
+            if (error instanceof ConversationBusy)
+                return send(res, 409, { error: "BUSY", message: error.message });
+            if (run && (closed || run.fenced))
+                return send(res, 503, { error: "RELEASED", message: error.message });
+            send(res, 500, { error: "FAILED", message: error?.message ?? String(error) });
+        });
+    });
+    await new Promise((resolve, reject) => {
+        server.once("error", reject);
+        server.listen(options.port ?? 0, bind, () => resolve());
+    });
+    const address = server.address();
+    const host = address.family === "IPv6" ? `[${address.address}]` : address.address;
+    return {
+        url: options.url ?? `http://${host}:${address.port}`,
+        get active() {
+            return active;
+        },
+        attach(open) {
+            run = open;
+            open.harness.subscribeClose(() => void (closed = true));
+        },
+        pause() {
+            pauses++;
+            let undone = false;
+            return () => {
+                if (!undone)
+                    (undone = true), pauses--;
+            };
+        },
+        close() {
+            closed = true;
+            return new Promise((resolve) => {
+                server.close(() => resolve());
+                server.closeAllConnections();
+            });
+        },
+    };
+}
+/** The run is done or failed (RUN_TERMINAL), or no instance answered before the deadline (NOT_SERVED). */
+export class ServeError extends PdaError {
+    ensured;
+    constructor(code, message, ensured) {
+        super(code, message);
+        this.ensured = ensured;
+    }
+}
+const sleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
+/** The running holder's serve address while its lease is fresh; otherwise there is no instance to talk to. */
+function servedBy(record, now, leaseMs) {
+    if (record?.status !== "running" || !isLeaseFresh(record, now, leaseMs))
+        return undefined;
+    return typeof record.holder?.serve === "string" ? record.holder.serve : undefined;
+}
+/**
+ * Send one request to run `ref`'s instance, waking it if needed: read run.json (S3) and send the request to the running
+ * holder's `serve` address while its lease is fresh. When there is none, it does not answer, it answers 503 with a
+ * retry code, or its lease lapses while the request is open (a frozen instance accepts connections and never answers;
+ * run.json is read again every third of a lease), ask `ensureRunning` with demand (start a released or lost run) and
+ * try again until `timeoutMs`. After a start, its own or one the supervisor reports `starting`, it waits for that
+ * instance to write its generation (or `startTimeoutMs`) before asking again, and an instance still opening (503
+ * OPENING) is waited for. A submit carries a `requestId`, so
+ * resending it to the next incarnation is safe: pi admits it once.
+ */
+export async function requestRun(ref, request, options) {
+    const fetchFn = options.fetch ?? fetch;
+    const now = options.ensure.now ?? Date.now;
+    const leaseMs = options.ensure.leaseExpiryMs ?? LEASE_EXPIRY_MS;
+    const timeoutMs = options.timeoutMs ?? 120_000;
+    const deadline = Date.now() + timeoutMs;
+    const ensured = [];
+    // Every control call is bounded by the control timeout, and every step of this loop by what is left of `timeoutMs`.
+    const control = withTimeouts(options.ensure.control, options.ensure.controlTimeoutMs ?? CONTROL_TIMEOUT_MS);
+    const notServed = () => new ServeError("NOT_SERVED", `run ${ref.id} did not answer in ${timeoutMs} ms`, ensured);
+    const inTime = (step) => new Promise((resolve, reject) => {
+        const timer = setTimeout(() => reject(notServed()), Math.max(0, deadline - Date.now()));
+        step.then((value) => (clearTimeout(timer), resolve(value)), (error) => (clearTimeout(timer), reject(error)));
+    });
+    const attempt = async (url) => {
+        const stop = new AbortController();
+        let looking = false;
+        const watch = setInterval(() => {
+            if (looking)
+                return;
+            looking = true;
+            readRunStatus(control, ref.id)
+                .then((r) => servedBy(r, now(), leaseMs) !== url && stop.abort(), () => { })
+                .finally(() => (looking = false));
+        }, Math.min(Math.max(1_000, leaseMs / 3), 10_000));
+        try {
+            return await fetchFn(new URL(request.path, url), {
+                method: request.method,
+                headers: {
+                    ...(request.body === undefined ? {} : { "content-type": "application/json" }),
+                    ...(options.token === undefined ? {} : { authorization: `Bearer ${options.token}` }),
+                },
+                ...(request.body === undefined ? {} : { body: JSON.stringify(request.body) }),
+                signal: AbortSignal.any([stop.signal, AbortSignal.timeout(Math.max(1, deadline - Date.now()))]),
+            }).then(async (res) => ({ status: res.status, body: (await res.json().catch(() => null)) }), () => undefined);
+        }
+        finally {
+            clearInterval(watch);
+        }
+    };
+    let pendingStart;
+    for (let pause = 100;; pause = Math.min(pause * 2, 1_000)) {
+        const record = await inTime(readRunStatus(control, ref.id));
+        const url = servedBy(record, now(), leaseMs);
+        let opening = false;
+        if (url) {
+            const r = await attempt(url);
+            const code = r?.body?.error;
+            if (r && !(r.status === 503 && RETRY_CODES.includes(code)))
+                return { ...r, url, ensured };
+            opening = code === "OPENING";
+        }
+        // An instance that is opening, or a start in flight whose instance has not written its generation yet, is left to open.
+        const generation = record?.generation ?? 0;
+        const awaitingStart = pendingStart !== undefined && Date.now() < pendingStart.until && generation < pendingStart.generation;
+        if (!opening && !awaitingStart) {
+            const result = await inTime(ensureRunning(ref, options.host, { ...options.ensure, demand: true }));
+            ensured.push(result);
+            if (result.action === "terminal")
+                throw new ServeError("RUN_TERMINAL", `run ${ref.id} is ${result.status}`, ensured);
+            // A start by this call, or one the supervisor's start grace reports in flight: wait for that generation.
+            if (result.action === "started")
+                pendingStart = { until: Date.now() + (options.startTimeoutMs ?? 60_000), generation: generation + 1 };
+            if (result.action === "starting")
+                pendingStart = { until: Date.now() + (options.startTimeoutMs ?? 60_000), generation: result.generation };
+        }
+        if (Date.now() + pause > deadline)
+            throw notServed();
+        await sleep(pause);
+    }
+}

package/dist/status.d.ts

@@ -0,0 +1,123 @@
+import type { JsonValue } from "@earendil-works/chord";
+import { PdaError } from "./errors.js";
+export declare const RUN_JSON = "run.json";
+/** The temporary file every write goes through; renamed over `run.json` once it is fsynced. */
+export declare const RUN_JSON_TEMP = "run.json.tmp";
+/** Heartbeat period: the instance rewrites `heartbeatAt` this often. */
+export declare const DEFAULT_HEARTBEAT_MS = 20000;
+/** A lease whose last heartbeat is older than this has expired; the supervisor may revoke. */
+export declare const DEFAULT_LEASE_EXPIRY_MS = 90000;
+/** The instance fences itself this long before its lease expires, on its own monotonic clock. */
+export declare const DEFAULT_LEASE_MARGIN_MS = 15000;
+export declare const RUN_STATUSES: readonly ["running", "sleeping", "paused", "done", "failed"];
+export type RunStatus = (typeof RUN_STATUSES)[number];
+/**
+ * The incarnation that wrote the record: the host driver's name and enough to find and stop the process. Fields beyond
+ * the five named here are the host driver's own handle (a unit name, a mountpoint), kept as written so the supervisor
+ * can hand them back to the driver.
+ */
+export interface RunHolder {
+    readonly driver: string;
+    readonly host: string;
+    /** `/proc/sys/kernel/random/boot_id`; null where the platform has none. */
+    readonly bootId: string | null;
+    readonly pid: number;
+    /** When this incarnation claimed the run (ISO 8601). */
+    readonly since: string;
+    readonly [field: string]: JsonValue;
+}
+export interface RunRecord {
+    readonly run: string;
+    readonly status: RunStatus;
+    /** Incremented on every claim, so a log line or receipt can name the incarnation that wrote it. */
+    readonly generation: number;
+    /** The store's last committed sequence at a clean release; null while running and after a crash. */
+    readonly sealedSeq: number | null;
+    /** When a `sleeping` run should be started again (ISO 8601); null otherwise. */
+    readonly wakeAt: string | null;
+    readonly holder: RunHolder | null;
+    /** Wall-clock time at which the last successful heartbeat write started (ISO 8601). */
+    readonly heartbeatAt: string | null;
+    /** Wall-clock time of the last status transition (ISO 8601). */
+    readonly updatedAt: string;
+    readonly detail: JsonValue | null;
+}
+/** `run.json` is missing a field, has one of the wrong type, or is not JSON. Exit 65 (EX_DATAERR): a restart cannot fix it. */
+export declare class RunRecordError extends PdaError {
+    constructor(message: string, options?: {
+        cause?: unknown;
+    });
+}
+/**
+ * Parse and validate the text of a `run.json`. Unknown fields are ignored, so a newer writer stays readable. Throws
+ * RunRecordError on anything else. This is the reader the supervisor uses on the bytes it gets over the S3 API.
+ */
+export declare function parseRunRecord(text: string): RunRecord;
+/** The `run.json` under a run's root on a local mount (or in a claim directory), or undefined when the run has none yet. */
+export declare function readRunRecord(root: string | ClaimDir): Promise<RunRecord | undefined>;
+/**
+ * True while the record's last heartbeat is younger than `expiryMs` on the reader's clock. The supervisor allows for
+ * clock skew between hosts inside the expiry.
+ */
+export declare function isLeaseFresh(record: RunRecord, nowMs?: number, expiryMs?: number): boolean;
+/**
+ * Writes `text` as `<root>/run.json` durably and atomically; replaceable for fault injection. Once `signal` is aborted
+ * the write must not publish: an instance that is fenced never renames a record over `run.json`.
+ */
+export type PersistRecord = (root: string, text: string, signal?: AbortSignal) => Promise<void>;
+/** Write to `run.json.tmp`, fsync it, rename it over `run.json`, fsync the directory. */
+export declare const persistRecord: PersistRecord;
+/**
+ * Write `record`; any error at all is a fence (`ownWriteFenced`), whatever its errno. Into a claim directory, the write
+ * goes through the open directory, after `assertMounted` (its CLAIM_UNMOUNTED fence is rethrown as is). `signal` as in
+ * `PersistRecord`.
+ */
+export declare function writeRunRecord(root: string | ClaimDir, record: RunRecord, persist?: PersistRecord, signal?: AbortSignal): Promise<void>;
+/** The FencedError code of a claim root that is no longer the mount the instance opened (unmounted, lazily or not). */
+export declare const CLAIM_UNMOUNTED = "CLAIM_UNMOUNTED";
+/** The file system type of an Archil mount in the mount table. */
+export declare const ARCHIL_FSTYPE = "fuse.archil";
+/**
+ * A run root held open as a directory for the life of the instance. `at` is `/proc/self/fd/<n>`, a path the kernel
+ * resolves through the open directory and never through the root's path (Node has no openat; the magic link stands in
+ * for it): a file made, written or renamed under `at` is in the directory opened at acquire, or the call fails (ENOTCONN
+ * once the FUSE daemon is gone). It never lands on the local disk under a mountpoint whose mount went away.
+ */
+export interface ClaimDir {
+    /** The root's path, as the claim names it. */
+    readonly root: string;
+    /** `/proc/self/fd/<n>`. Throws once closed: the number may then name another file. */
+    readonly at: string;
+    /**
+     * Resolves while the root's path still resolves to the directory held open (same device, same inode). A mount that was
+     * unmounted (lazily, by an operator, or by its daemon's `auto_unmount`) leaves the path on another device, and a dead
+     * daemon fails the stat: both reject with a FencedError CLAIM_UNMOUNTED. The stat runs off the main thread.
+     */
+    assertMounted(): Promise<void>;
+    /** Resolves while `<root>/<name>` by path is the entry `name` of the directory held open, on its device; else as `assertMounted`. */
+    assertSame(name: string): Promise<void>;
+    /** Close the directory (idempotent). A caller closes it only once nothing can still address `at`. */
+    close(): Promise<void>;
+}
+export interface OpenClaimDirOptions {
+    /**
+     * The root must be the mount point of a mount of this type whose device is the opened directory's (default
+     * `fuse.archil`). Null skips the mount table: a run root on a local directory, for tests.
+     */
+    readonly fstype?: string | null;
+    /** Default `/proc/self/mountinfo`. */
+    readonly mountinfo?: string;
+}
+/** `major:minor` of a device number, as `/proc/self/mountinfo` writes it (glibc's encoding). */
+export declare function deviceName(dev: bigint): string;
+/**
+ * Open `root` as the claim's directory. With an `fstype` (default `fuse.archil`), the mount table must list a mount of
+ * that type at `root` on the device of the directory just opened; otherwise, and when the root cannot be opened, a
+ * FencedError CLAIM_UNMOUNTED (exit 75).
+ */
+export declare function openClaimDir(root: string, options?: OpenClaimDirOptions): Promise<ClaimDir>;
+/**
+ * This process as a holder: the host driver's `handle` (default driver `local`, this machine's host name and boot id)
+ * with this process's pid and `since`. A handle whose named fields have the wrong type is refused (RunRecordError).
+ */
+export declare function currentHolder(handle?: Readonly<Record<string, JsonValue>>, since?: Date): RunHolder;