@parcha/agentrun-pi 0.1.0-beta.2 → 0.1.0-beta.20

package/dist/durable/record.d.ts

@@ -0,0 +1,157 @@
+/** The record a node delivered, or null while it has not, and the delivery attempts it has spent. */
+export type RecordState = {
+    record: unknown;
+    attempts: number;
+};
+/** What the second reading disagrees with in a record: its question, the kind of reading, the verdict and why. */
+export type Disagreement = {
+    id: string;
+    kind: string;
+    verdict: string;
+    reasons: string[];
+};
+/** Whether the second reading's round was spent, and what it still disagreed with in the delivered record. */
+export type GateState = {
+    bounced: boolean;
+    disagreements: Disagreement[];
+};
+/** Delivery attempts a node gets: rejections, the second reading's one bounce and nudges, each once. */
+export declare const DELIVERY_ATTEMPTS = 6;
+/** The most schema violations one rejected delivery lists; the submit tool's description tells the model the number. */
+export declare const VIOLATIONS_SHOWN = 8;
+/** One reviewer's reading of a structurally valid record. `no_verdict` is a reviewer that could not answer. */
+export type Reading = "disagrees" | "agrees" | "no_verdict";
+/** The second reading on one structurally valid submission: it sends the record back only while its round
+ *  is unspent and a reviewer disagrees. A reviewer with no verdict never sends a record back. */
+export declare function gate(bounced: boolean, readings: readonly Reading[]): "accept" | "bounce";
+/** What a node is answered with. Only `delivered` is a delivery; each of the others spends one attempt. */
+export type DeliveryEvent = "rejected" | "bounce" | "nudge" | "delivered";
+/** A node's delivery, as far as the attempts count it. */
+export type DeliveryCount = {
+    attempts: number;
+    delivered: boolean;
+};
+/** Whether a node's delivery has ended: it delivered, or its attempts are spent. */
+export declare const deliveryEnded: (max: number, state: DeliveryCount) => boolean;
+/** One answer applied to the count. An ended delivery takes no further answer; every other answer counts once. */
+export declare function spend(max: number, state: DeliveryCount, event: DeliveryEvent): DeliveryCount;
+/** What makes a schema one no `submit` call can satisfy: a call's arguments are an object, so the schema must be a
+ *  JSON Schema object whose root type, when it names one, admits an object. A node runner refuses such a schema
+ *  before any conversation exists. */
+export declare function lintRecordRoot(schema: unknown): string[];
+/** What an author should fix in a record schema, for a host or a validator to report: the root findings above, and
+ *  a schema that declares its fields and requires one that is not among them, which the tool's shown fields never
+ *  name. A record of the second kind can still be delivered (the tool's parameters are open, and the delivery
+ *  contract that ends the node's task carries the schema with its `required`), so a runner does not refuse it. A
+ *  schema that declares no `properties` is not held to it. */
+export declare function lintRecordSchema(schema: unknown): string[];
+/** Where the schema expects an object or an array and the submitted value is a string that parses to one, the
+ *  parsed value; where it expects a number, an integer, a boolean or null and admits no string, the scalar a
+ *  string spells. Some model families serialise nested tool arguments as strings: the content is valid and
+ *  every submit fails on its spelling. A string that parses to a container the field also admits is read as that
+ *  container; only against a scalar does a field that admits a string keep the string. */
+export declare function parseStringifiedContainers(value: unknown, schema: Record<string, unknown> | undefined, depth?: number, rootDefinitions?: Record<string, unknown>): unknown;
+/** The path of every string that spells "no value" in a field whose schema admits JSON null. */
+export declare function nullSpellings(value: unknown, schema: unknown, root?: unknown, at?: string): string[];
+/** The record with every such string replaced by JSON null, in place. A repair the record as a whole refuses
+ *  (it satisfied its schema before and does not after) is undone in full, so a spelling stays only where null
+ *  is inadmissible; `undo: false` leaves that judgement to a caller that repairs more of the record and judges the
+ *  whole. `""` is a value and stays. */
+export declare function healNullSpellings<T>(record: T, schema: Record<string, unknown>, options?: {
+    undo?: boolean;
+}): T;
+/** A record's transport spellings repaired against its schema, without touching `args`. */
+export declare function repairRecord(args: unknown, schema: Record<string, unknown>): unknown;
+/** The file a submission names and nothing else: `{ <key>: "relative/path.json" }`. */
+export declare function fileSubmission(args: unknown, key: string): string | null;
+/** A submission with fields beside the file key. Fields that form a whole record on their own are that record;
+ *  otherwise the file holds the record, and each field beside it may only restate the file's value. A schema
+ *  that declares the file key as its own field keeps it inline. */
+export declare function mixedFileSubmission(args: unknown, schema: Record<string, unknown> | undefined, key: string): {
+    file: string;
+    extras: Record<string, unknown>;
+} | null;
+/** The fields beside the file key that the file's record does not hold with the same value. */
+export declare function extrasNotInRecord(record: unknown, extras: Record<string, unknown>): string[];
+/** One host check's refusal of a candidate: the problems the model must fix, and the reason they are grouped under. */
+export type Refusal = {
+    problems: string[];
+    reason?: string;
+};
+/** A second reader of a structurally valid record. It returns what it disagrees with (nothing when it agrees or
+ *  has no verdict). `round` says whether a disagreement still sends the record back. A reviewer that throws
+ *  decides nothing, unless the contract's `fatal` claims the error. */
+export type Reviewer = (candidate: unknown, context: {
+    round: boolean;
+}) => Disagreement[] | Promise<Disagreement[]>;
+export type RecordContract = {
+    /** The node's record schema, the `submit` tool's contract. */
+    schema: Record<string, unknown>;
+    /** Delivery attempts the node gets (default `DELIVERY_ATTEMPTS`). */
+    maxAttempts?: number;
+    /** A record may be delivered as a workspace file named under `key`; `read` returns the file's parsed JSON or
+     *  throws (an error whose `code` is `ENOENT` for a file that is not there). Absent, a record is inline only. */
+    file?: {
+        key: string;
+        read(path: string): Promise<unknown>;
+    };
+    /** Contracts the host owns, held before the schema: each problem is said with the core's own findings. */
+    contracts?: (candidate: unknown) => string[] | Promise<string[]>;
+    /** Checks held after the schema, in order; the first refusal is the rejection. One that throws refuses with
+     *  what it threw. */
+    checks?: ReadonlyArray<(candidate: unknown) => Refusal | null | Promise<Refusal | null>>;
+    /** The second reading, in order. */
+    reviewers?: readonly Reviewer[];
+    /** Whether a reviewer's error is the caller's own failure, to be thrown and not absorbed. */
+    fatal?: (error: unknown) => boolean;
+};
+/** The two states behind a node's delivery. Each write is one atomic change; `reject` and `bounce` return the
+ *  attempts spent after it. The bounce spends the round before the model is told, so a crash cannot grant it twice. */
+export type RecordStore = {
+    read(): Promise<{
+        record: RecordState;
+        gate: GateState;
+    }>;
+    reject(): Promise<number>;
+    bounce(): Promise<number>;
+    accept(record: unknown, disagreements: Disagreement[]): Promise<void>;
+};
+/** What one submission came to. `spent` says the delivery attempts are gone and the node's run ends here. */
+export type Delivery = {
+    status: "already";
+} | {
+    status: "rejected";
+    attempts: number;
+    spent: boolean;
+    reason: string;
+    problems: string[];
+} | {
+    status: "bounced";
+    attempts: number;
+    spent: boolean;
+    disagreements: Disagreement[];
+} | {
+    status: "accepted";
+    record: unknown;
+    disagreements: Disagreement[];
+};
+/** Decide one `submit` call. `args` are the call's arguments as the model sent them, or as `repairRecord`
+ *  already repaired them. */
+export declare function deliver(contract: RecordContract, store: RecordStore, args: unknown): Promise<Delivery>;
+/** The `submit` tool's answer to the model for one delivery. */
+export declare function deliveryText(delivery: Delivery, maxAttempts?: number, say?: (disagreement: Disagreement) => string): string;
+/** One disagreement as the model reads it. */
+export declare const disagreementText: (d: Disagreement) => string;
+/** Whether a delivery ends the node's run: a record was delivered, or the attempts are spent. */
+export declare const deliveryTerminates: (delivery: Delivery) => boolean;
+/** The delivery contract a node's task ends with: the label, the file envelope when one is offered, the
+ *  authoritative schema and the host's own delivery instructions. The model sees the exact schema only here. */
+export declare function submitFooter(record: {
+    label: string;
+    schema: Record<string, unknown>;
+    fileKey?: string;
+    instructions?: string;
+    reviewed?: boolean;
+}): string;
+/** What a yield without a record is answered with, when the delivery has an attempt left for it. */
+export declare const nudgeText: (label: string) => string;

package/dist/durable/record.js

@@ -0,0 +1,402 @@
+// The record core: how one LLM node delivers a typed record through one `submit` call, with no pi import.
+//
+// A submission is repaired as a transport spelling (stringified containers and scalars, a "null" where the
+// field admits null), read from a workspace file when it names one, held to the host's contracts and the
+// schema, and then read a second time by the node's reviewers. Every answer that is not a delivery spends
+// one delivery attempt: a rejection, the second reading's one bounce, a nudge of a yield without a record.
+// The second reading is feedback, once: the first record it disagrees with goes back; the next structurally
+// valid record is delivered with what the reading still disagrees with beside it. A reviewer that cannot
+// answer decides nothing.
+//
+// `deliver` is the whole decision over a `RecordStore`, the two small states a caller keeps durably or in
+// memory. `gate` and `spend` are the rules as pure functions, the ones `spec/lean` proves terminate. `deliver`
+// follows `gate`. It does not hold `spend`'s bound: it decides a submission whatever the count, and a nudge that
+// spends the last attempt still continues the run, so the one submission after it is decided and `attempts` can
+// read one past the limit.
+import { isDeepStrictEqual } from "node:util";
+import { Compile } from "typebox/compile";
+/** Delivery attempts a node gets: rejections, the second reading's one bounce and nudges, each once. */
+export const DELIVERY_ATTEMPTS = 6;
+/** The most schema violations one rejected delivery lists; the submit tool's description tells the model the number. */
+export const VIOLATIONS_SHOWN = 8;
+/** The second reading on one structurally valid submission: it sends the record back only while its round
+ *  is unspent and a reviewer disagrees. A reviewer with no verdict never sends a record back. */
+export function gate(bounced, readings) {
+    return !bounced && readings.includes("disagrees") ? "bounce" : "accept";
+}
+/** Whether a node's delivery has ended: it delivered, or its attempts are spent. */
+export const deliveryEnded = (max, state) => state.delivered || state.attempts >= max;
+/** One answer applied to the count. An ended delivery takes no further answer; every other answer counts once. */
+export function spend(max, state, event) {
+    if (deliveryEnded(max, state))
+        return state;
+    return { attempts: state.attempts + 1, delivered: event === "delivered" };
+}
+// ─── the schema a record is held to ───
+/** What makes a schema one no `submit` call can satisfy: a call's arguments are an object, so the schema must be a
+ *  JSON Schema object whose root type, when it names one, admits an object. A node runner refuses such a schema
+ *  before any conversation exists. */
+export function lintRecordRoot(schema) {
+    if (!schema || typeof schema !== "object" || Array.isArray(schema))
+        return ["the record schema must be a JSON Schema object"];
+    const { type } = schema;
+    const admitsObject = type === undefined || type === "object" || (Array.isArray(type) && type.includes("object"));
+    return admitsObject ? [] : [`the record schema's root type must be "object", not ${JSON.stringify(type)}`];
+}
+/** What an author should fix in a record schema, for a host or a validator to report: the root findings above, and
+ *  a schema that declares its fields and requires one that is not among them, which the tool's shown fields never
+ *  name. A record of the second kind can still be delivered (the tool's parameters are open, and the delivery
+ *  contract that ends the node's task carries the schema with its `required`), so a runner does not refuse it. A
+ *  schema that declares no `properties` is not held to it. */
+export function lintRecordSchema(schema) {
+    const problems = lintRecordRoot(schema);
+    if (!schema || typeof schema !== "object" || Array.isArray(schema))
+        return problems;
+    const { properties, required } = schema;
+    const declared = properties && typeof properties === "object" && !Array.isArray(properties) ? properties : null;
+    const undeclared = Array.isArray(required) && declared ? required.filter((name) => typeof name !== "string" || !Object.hasOwn(declared, name)) : [];
+    if (undeclared.length)
+        problems.push(`the record schema requires ${undeclared.map((name) => JSON.stringify(name)).join(", ")}, which its properties do not declare`);
+    return problems;
+}
+const validators = new WeakMap();
+/** The schema's compiled validator, or null for a schema the compiler refuses. */
+function validatorOf(schema) {
+    if (!schema || typeof schema !== "object")
+        return null;
+    let validator = validators.get(schema);
+    if (validator === undefined) {
+        try {
+            validator = Compile(schema);
+        }
+        catch {
+            validator = null;
+        }
+        validators.set(schema, validator);
+    }
+    return validator;
+}
+// ─── transport repair ───
+/** Where the schema expects an object or an array and the submitted value is a string that parses to one, the
+ *  parsed value; where it expects a number, an integer, a boolean or null and admits no string, the scalar a
+ *  string spells. Some model families serialise nested tool arguments as strings: the content is valid and
+ *  every submit fails on its spelling. A string that parses to a container the field also admits is read as that
+ *  container; only against a scalar does a field that admits a string keep the string. */
+export function parseStringifiedContainers(value, schema, depth = 0, rootDefinitions) {
+    if (depth > 6 || !schema || typeof schema !== "object")
+        return value;
+    // A `$ref` property carries no type of its own: it is read through the root schema's definitions, or the
+    // repair skips exactly the fields it exists for.
+    const definitions = rootDefinitions ?? schema.definitions;
+    const deref = (spec, hops = 0) => {
+        if (hops > 4 || !spec || typeof spec !== "object")
+            return spec;
+        const ref = typeof spec.$ref === "string" ? spec.$ref.match(/^#\/definitions\/(.+)$/) : null;
+        if (ref && definitions && definitions[ref[1]] && typeof definitions[ref[1]] === "object")
+            return deref(definitions[ref[1]], hops + 1);
+        return spec;
+    };
+    const expected = (spec) => {
+        const resolved = deref(spec);
+        const types = Array.isArray(resolved?.type) ? resolved.type : resolved?.type ? [resolved.type] : [];
+        const anyOf = Array.isArray(resolved?.anyOf) ? resolved.anyOf : [];
+        return [...types, ...anyOf.flatMap((variant) => expected(variant))];
+    };
+    const repair = (input, rawSpec) => {
+        const spec = deref(rawSpec);
+        const wants = expected(spec);
+        let current = input;
+        if (typeof current === "string" && (wants.includes("object") || wants.includes("array"))) {
+            const trimmed = current.trim();
+            if ((trimmed.startsWith("{") && trimmed.endsWith("}")) || (trimmed.startsWith("[") && trimmed.endsWith("]"))) {
+                try {
+                    const parsed = JSON.parse(trimmed);
+                    const isObject = parsed && typeof parsed === "object" && !Array.isArray(parsed);
+                    if ((isObject && wants.includes("object")) || (Array.isArray(parsed) && wants.includes("array")))
+                        current = parsed;
+                }
+                catch { /* Not JSON: the string stays for the validator to report. */ }
+            }
+        }
+        // A scalar is coerced only when the field does not accept a string. Integers must be exact; a decimal
+        // becomes the float64 that JSON.parse of the same literal yields, the only value a JSON number can hold.
+        if (typeof current === "string" && !wants.includes("string")) {
+            const trimmed = current.trim();
+            if ((wants.includes("integer") || wants.includes("number")) && /^-?\d+$/.test(trimmed) && Number.isSafeInteger(Number(trimmed)))
+                current = Number(trimmed);
+            else if (wants.includes("number") && /^-?(?:0|[1-9]\d*)\.\d+$/.test(trimmed) && Number.isFinite(Number(trimmed)))
+                current = JSON.parse(trimmed);
+            else if (wants.includes("boolean") && (trimmed === "true" || trimmed === "false"))
+                current = trimmed === "true";
+            else if (wants.includes("null") && trimmed === "null")
+                current = null;
+        }
+        // An `anyOf`-wrapped object's nested fields live under the branch's properties, not the wrapper's.
+        const flattenBranches = (candidate) => [candidate, ...(Array.isArray(candidate?.anyOf) ? candidate.anyOf.flatMap(flattenBranches) : [])];
+        if (current && typeof current === "object" && !Array.isArray(current)) {
+            const objectBranch = flattenBranches(spec).map((branch) => deref(branch)).find((branch) => branch?.properties && typeof branch.properties === "object");
+            if (objectBranch)
+                return parseStringifiedContainers(current, objectBranch, depth + 1, definitions);
+        }
+        if (Array.isArray(current)) {
+            const arrayBranch = flattenBranches(spec).map((branch) => deref(branch)).find((branch) => branch?.items && typeof branch.items === "object");
+            if (arrayBranch)
+                return current.map((item) => repair(item, arrayBranch.items));
+        }
+        return current;
+    };
+    if (!value || typeof value !== "object" || Array.isArray(value))
+        return value;
+    const properties = schema.properties || {};
+    const next = { ...value };
+    for (const [key, spec] of Object.entries(properties))
+        if (key in next)
+            next[key] = repair(next[key], spec);
+    return next;
+}
+/** A local `$ref` (`#/definitions/<name>` or `#/$defs/<name>`) resolved against the record's root schema, so
+ *  the null-spelling walk reads the field schemas the schema check does. One it cannot resolve reads as no schema. */
+function deref(schema, root, hops = 0) {
+    if (!schema || typeof schema !== "object" || Array.isArray(schema))
+        return schema;
+    const ref = schema.$ref;
+    if (typeof ref !== "string")
+        return schema;
+    const match = ref.match(/^#\/(definitions|\$defs)\/([^/]+)$/);
+    const table = match && root && typeof root === "object" ? root[match[1]] : undefined;
+    const target = table && typeof table === "object" ? table[match[2]] : undefined;
+    return target && hops < 16 ? deref(target, root, hops + 1) : undefined;
+}
+function admitsNull(schema, root) {
+    schema = deref(schema, root);
+    if (!schema || typeof schema !== "object" || Array.isArray(schema))
+        return false;
+    const spec = schema;
+    if (spec.type === "null" || (Array.isArray(spec.type) && spec.type.includes("null")))
+        return true;
+    if (spec.const === null || (Array.isArray(spec.enum) && spec.enum.includes(null)))
+        return true;
+    return [spec.anyOf, spec.oneOf].some((branches) => Array.isArray(branches) && branches.some((branch) => admitsNull(branch, root)));
+}
+function propertiesOf(schema, root) {
+    schema = deref(schema, root);
+    if (!schema || typeof schema !== "object" || Array.isArray(schema))
+        return {};
+    const spec = schema;
+    const fieldMap = !("type" in spec) && !("properties" in spec) && !("anyOf" in spec) && !("oneOf" in spec) ? spec : {};
+    const direct = spec.properties && typeof spec.properties === "object" && !Array.isArray(spec.properties) ? spec.properties : fieldMap;
+    const branches = [...(Array.isArray(spec.anyOf) ? spec.anyOf : []), ...(Array.isArray(spec.oneOf) ? spec.oneOf : [])];
+    return Object.assign({}, ...branches.map((branch) => propertiesOf(branch, root)), direct);
+}
+function itemsOf(schema, root) {
+    schema = deref(schema, root);
+    if (!schema || typeof schema !== "object" || Array.isArray(schema))
+        return undefined;
+    const spec = schema;
+    if (spec.items)
+        return spec.items;
+    const branches = [...(Array.isArray(spec.anyOf) ? spec.anyOf : []), ...(Array.isArray(spec.oneOf) ? spec.oneOf : [])];
+    return branches.map((branch) => itemsOf(branch, root)).find(Boolean);
+}
+// The spellings a model uses when it means "no value": one set, read by the finding and by the repair, so a
+// string one recognises the other heals.
+const NULL_SPELLINGS = new Set(["null", "none", "n/a"]);
+const spellsNull = (value) => typeof value === "string" && NULL_SPELLINGS.has(value.trim().toLowerCase());
+/** The path of every string that spells "no value" in a field whose schema admits JSON null. */
+export function nullSpellings(value, schema, root = schema, at = "") {
+    if (spellsNull(value) && admitsNull(schema, root))
+        return [at || "$"];
+    if (Array.isArray(value)) {
+        const items = itemsOf(schema, root);
+        return items ? value.flatMap((item, index) => nullSpellings(item, items, root, `${at}[${index}]`)) : [];
+    }
+    if (!value || typeof value !== "object")
+        return [];
+    const properties = propertiesOf(schema, root);
+    return Object.entries(value).flatMap(([key, child]) => Object.hasOwn(properties, key) ? nullSpellings(child, properties[key], root, at ? `${at}.${key}` : key) : []);
+}
+/** The record with every such string replaced by JSON null, in place. A repair the record as a whole refuses
+ *  (it satisfied its schema before and does not after) is undone in full, so a spelling stays only where null
+ *  is inadmissible; `undo: false` leaves that judgement to a caller that repairs more of the record and judges the
+ *  whole. `""` is a value and stays. */
+export function healNullSpellings(record, schema, options = {}) {
+    if (!record || typeof record !== "object" || Array.isArray(record) || Object.getPrototypeOf(record) !== Object.prototype)
+        return record;
+    if (!nullSpellings(record, schema).length)
+        return record;
+    const validator = options.undo === false ? null : validatorOf(schema);
+    const before = validator?.Check(record) ? structuredClone(record) : null;
+    const heal = (value, spec) => {
+        if (spellsNull(value) && admitsNull(spec, schema))
+            return null;
+        if (Array.isArray(value)) {
+            const items = itemsOf(spec, schema);
+            if (items)
+                value.forEach((item, index) => { value[index] = heal(item, items); });
+            return value;
+        }
+        if (!value || typeof value !== "object")
+            return value;
+        const properties = propertiesOf(spec, schema);
+        for (const [key, child] of Object.entries(value)) {
+            if (Object.hasOwn(properties, key))
+                value[key] = heal(child, properties[key]);
+        }
+        return value;
+    };
+    heal(record, schema);
+    if (before && validator && !validator.Check(record)) {
+        const fields = record;
+        for (const key of Object.keys(fields))
+            delete fields[key];
+        Object.assign(fields, before);
+    }
+    return record;
+}
+/** A record's transport spellings repaired against its schema, without touching `args`. */
+export function repairRecord(args, schema) {
+    if (!args || typeof args !== "object" || Array.isArray(args))
+        return args;
+    return healNullSpellings(structuredClone(parseStringifiedContainers(args, schema)), schema);
+}
+// ─── the file envelope ───
+/** The file a submission names and nothing else: `{ <key>: "relative/path.json" }`. */
+export function fileSubmission(args, key) {
+    if (!args || typeof args !== "object" || Array.isArray(args))
+        return null;
+    const fields = args;
+    return Object.keys(fields).length === 1 && typeof fields[key] === "string" ? fields[key] : null;
+}
+/** A submission with fields beside the file key. Fields that form a whole record on their own are that record;
+ *  otherwise the file holds the record, and each field beside it may only restate the file's value. A schema
+ *  that declares the file key as its own field keeps it inline. */
+export function mixedFileSubmission(args, schema, key) {
+    if (!args || typeof args !== "object" || Array.isArray(args))
+        return null;
+    const { [key]: file, ...extras } = args;
+    if (typeof file !== "string" || !Object.keys(extras).length)
+        return null;
+    const properties = schema && typeof schema.properties === "object" && schema.properties ? schema.properties : {};
+    return Object.hasOwn(properties, key) ? null : { file, extras };
+}
+/** The fields beside the file key that the file's record does not hold with the same value. */
+export function extrasNotInRecord(record, extras) {
+    const held = record && typeof record === "object" && !Array.isArray(record) ? record : {};
+    return Object.keys(extras).filter((key) => !Object.hasOwn(held, key) || !isDeepStrictEqual(held[key], extras[key])).sort();
+}
+const SCHEMA_REASON = "submission does not satisfy the schema";
+const messageOf = (error) => error instanceof Error ? error.message : String(error);
+/** Decide one `submit` call. `args` are the call's arguments as the model sent them, or as `repairRecord`
+ *  already repaired them. */
+export async function deliver(contract, store, args) {
+    const max = contract.maxAttempts ?? DELIVERY_ATTEMPTS;
+    const key = contract.file?.key;
+    const state = await store.read();
+    if (state.record.record != null)
+        return { status: "already" };
+    const reject = async (problems, reason = SCHEMA_REASON) => {
+        const attempts = await store.reject();
+        return { status: "rejected", attempts, spent: attempts >= max, reason, problems };
+    };
+    const validator = validatorOf(contract.schema);
+    let candidate = args;
+    const file = key === undefined ? null : fileSubmission(candidate, key);
+    const mixed = key === undefined ? null : mixedFileSubmission(candidate, contract.schema, key);
+    // Fields beside the file key that are a whole record on their own are that record, as an inline submission.
+    const inlineBeside = mixed ? repairRecord(mixed.extras, contract.schema) : undefined;
+    if (mixed && validator?.Check(inlineBeside))
+        candidate = inlineBeside;
+    else if (mixed) {
+        const exact = `call submit with exactly {"${key}": ${JSON.stringify(mixed.file)}} and nothing beside it`;
+        let record;
+        try {
+            record = await contract.file.read(mixed.file);
+        }
+        catch (error) {
+            if (error?.code === "ENOENT")
+                return reject([`${key} names a file that does not exist in the workspace; write the complete JSON there first, then ${exact}`]);
+            return reject([`${messageOf(error)}; then ${exact}`]);
+        }
+        const stray = extrasNotInRecord(record, mixed.extras);
+        if (stray.length) {
+            return reject([`the record is read from ${mixed.file} alone, and these fields beside ${key} are missing from that file or differ from it: ${stray.join(", ")}. Write every field into the file, then ${exact}`], "the submission mixes a file with inline fields");
+        }
+        candidate = repairRecord(record, contract.schema);
+    }
+    else if (file !== null) {
+        // The file's record takes the same transport repair as an inline one.
+        try {
+            candidate = repairRecord(await contract.file.read(file), contract.schema);
+        }
+        catch (error) {
+            if (error?.code === "ENOENT")
+                return reject([`${key} names a file that does not exist in the workspace; write the complete JSON there first, then resubmit`]);
+            return reject([messageOf(error)]);
+        }
+    }
+    // A "null" the repair could not heal sits where the record's other fields rule null out: the model writes the value.
+    const unhealed = (candidate && typeof candidate === "object" && !Array.isArray(candidate) ? nullSpellings(candidate, contract.schema) : []).map((path) => `${path}: violates "this field cannot be null in this record: the schema admits null for the field alone, but the record's other fields rule it out" — write the real value`);
+    const owned = [...unhealed, ...(contract.contracts ? await contract.contracts(candidate) : [])];
+    if (owned.length)
+        return reject(owned, "the record violates host-owned contracts");
+    if (!validator || !validator.Check(candidate)) {
+        return reject(validator ? [...validator.Errors(candidate)].slice(0, VIOLATIONS_SHOWN).map((error) => `${error.instancePath || error.path || "/"}: ${error.message}`) : ["the record schema does not compile"]);
+    }
+    for (const check of contract.checks ?? []) {
+        let refusal;
+        try {
+            refusal = await check(candidate);
+        }
+        catch (error) {
+            refusal = { problems: [`host validation gate threw: ${messageOf(error)}`] };
+        }
+        if (refusal?.problems.length)
+            return reject(refusal.problems, refusal.reason);
+    }
+    // The second reading, once.
+    const round = !state.gate.bounced;
+    const disagreements = [];
+    for (const reviewer of contract.reviewers ?? []) {
+        try {
+            disagreements.push(...await reviewer(candidate, { round }));
+        }
+        catch (error) {
+            if (contract.fatal?.(error))
+                throw error;
+        }
+    }
+    if (gate(state.gate.bounced, [disagreements.length ? "disagrees" : "agrees"]) === "bounce") {
+        const attempts = await store.bounce();
+        return { status: "bounced", attempts, spent: attempts >= max, disagreements };
+    }
+    await store.accept(candidate, disagreements);
+    return { status: "accepted", record: candidate, disagreements };
+}
+/** The `submit` tool's answer to the model for one delivery. */
+export function deliveryText(delivery, maxAttempts = DELIVERY_ATTEMPTS, say = disagreementText) {
+    const spentLine = "The delivery attempts are spent; the run stops here.";
+    switch (delivery.status) {
+        case "already": return "Already submitted; the first valid record is authoritative.";
+        case "accepted": return "Submitted. You are DONE; end your turn.";
+        case "rejected": return `REJECTED (${delivery.attempts}/${maxAttempts}) — ${delivery.reason}: ${delivery.problems.join("; ")}.${delivery.spent ? ` ${spentLine}` : " Fix exactly those and resubmit."}`;
+        case "bounced": return `${delivery.disagreements.map(say).join("\n")}${delivery.spent ? `\n${spentLine}` : ""}`;
+    }
+}
+/** One disagreement as the model reads it. */
+export const disagreementText = (d) => `${d.id} (${d.kind}): ${d.verdict}${d.reasons.length ? ` - ${d.reasons.join("; ")}` : ""}`;
+/** Whether a delivery ends the node's run: a record was delivered, or the attempts are spent. */
+export const deliveryTerminates = (delivery) => delivery.status === "already" || delivery.status === "accepted" || ((delivery.status === "rejected" || delivery.status === "bounced") && delivery.spent);
+/** The delivery contract a node's task ends with: the label, the file envelope when one is offered, the
+ *  authoritative schema and the host's own delivery instructions. The model sees the exact schema only here. */
+export function submitFooter(record) {
+    return [
+        `When you are done, call the \`submit\` tool ONCE with ${record.label} as its arguments. The arguments are validated against the required schema; if validation fails you get the problems back and may fix and resubmit.`,
+        ...(record.reviewed ? ["A schema-valid record is then reviewed against the procedure that governs this run before it is accepted; violations come back to you, with the rule each one breaks, to fix and resubmit."] : []),
+        ...(record.fileKey ? [`For a large record, write the complete JSON to a fresh file inside the workspace, then call \`submit\` once with {"${record.fileKey}":"relative/path.json"}. The harness reads and validates that file directly; do not paste the record back into the tool call.`] : []),
+        `Required JSON Schema (authoritative): ${JSON.stringify(record.schema)}`,
+        record.instructions || "",
+        "Only a successful `submit` call counts as delivering. Do not answer in plain text.",
+    ].filter(Boolean).join("\n");
+}
+/** What a yield without a record is answered with, when the delivery has an attempt left for it. */
+export const nudgeText = (label) => `You stopped without submitting. Call submit with ${label}, complete.`;

package/dist/durable/recording.d.ts

@@ -0,0 +1,90 @@
+import type { Session, Storage } from "@earendil-works/pi-durable";
+type Json = any;
+type Context = Parameters<Session["commit"]>[1];
+/** Who owns a line's record, by its kind's package prefix; a kind with no package prefix is the host's. */
+export type RecordingSource = "workflow" | "pi" | "browser" | "vision" | "transport" | "host";
+/** One durable line: a document revision (`data` is `{ doc, key?, value, version }`, the whole value after the
+ *  revision), a conversation entry (`data` is the entry as stored), or a task's record (`data` as stored). */
+export type RecordingLine = {
+    channel: "durable";
+    source: RecordingSource;
+    /** The document's kind, the entry's own `kind`, or the task's kind. */
+    kind: string;
+    /** The generation of the latest `agentrun.driver` revision at or before `commit`; absent when there is none. */
+    gen?: number;
+    /** The store's commit sequence. */
+    commit: number;
+    /** The line's place inside its commit: documents by id, then entries by id, then tasks by id. */
+    order: number;
+    /** The workflow execution path the record is about: the one it names, or, for a record in a node attempt's
+     *  conversation (an entry, a conversation's document, a task), the node's. */
+    path?: string;
+    /** The pi conversation the record belongs to, when it belongs to one. */
+    conv?: number;
+    /** Present on a line `recordCommits` wrote: when the process adopted the commit, by the recorder's clock. */
+    t?: number;
+    /** Present on `snapshotLines`' lines: a document's state at `commit`, not a change made there. */
+    snapshot?: true;
+    data: Json;
+};
+/**
+ * Every change the store `file` committed after `after` (default: all), as durable recording lines in `(commit, order)`
+ * order, and `last`, the highest commit returned (`after` when nothing is). For a store no process holds (a disk run's
+ * store admits one connection): read-only, in one read transaction.
+ *
+ * - A document revision is a line of the document's kind, with the whole value after it (each delta applied over its
+ *   base); `key` is the family key as stored, absent for a singleton.
+ * - A conversation entry is a line of the entry's own kind, source `pi`, `conv` its conversation, the entry as stored
+ *   (image blocks included: the recorder moves them to blobs).
+ * - Every task's current record is a line of the task's kind, at the store's last commit, after that commit's other
+ *   lines, by task id: the state at export, since the store keeps no commit for a task's change. Its memos ride in the
+ *   record; there are no memo lines.
+ * - `gen` is the generation of the latest surviving `agentrun.driver` revision at or before the line's commit (it
+ *   counts journal opens, not processes), and absent before the earliest surviving one. No line has `t`: the store
+ *   keeps no commit time.
+ *
+ * This is the store's surviving history: pi deletes a current-only document's older revisions when it writes a new
+ * base. The full history is `recordCommits`', written inside the run's process as each commit lands.
+ */
+export declare function recordingLines(file: string, options?: {
+    after?: number;
+}): {
+    lines: RecordingLine[];
+    last: number;
+};
+/**
+ * Records the run's commits as durable lines inside its process, on pi's commit publications: each commit adopted
+ * after this call becomes the lines `recordingLines` would give it, with tasks at their real commit, `t` the adoption
+ * time (`clock()`, default `Date.now()`), and `gen` the generation of the latest `agentrun.driver` revision at or
+ * before the commit. `from` is the snapshot this recording continues (`snapshotLines`, written before the run
+ * resumed): its driver generation and its nodes' conversations carry on until this process writes its own. `gen` is
+ * only for a run with no driver revision yet; it never overrides a driver generation.
+ *
+ * The listener only maps and queues: it never throws, blocks or calls the Session. `write` receives one commit's lines
+ * at a time, in commit order, after the listener has returned. A `write` that completes synchronously (an append to a
+ * file) runs before pi adopts the next commit, so a process that dies loses at most the commit in flight; one that
+ * completes later leaves the commits after it queued in memory, and a death loses those too. The next process's
+ * `snapshotLines` restores the documents' state; a lost commit's entries stay missing, a gap the viewer shows. The
+ * returned stop ends the subscription, waits for every queued write, and then throws the first write that failed.
+ */
+export declare function recordCommits(session: Pick<Session, "subscribeCommits">, options: {
+    gen?: number;
+    from?: RecordingLine[];
+    write: (lines: RecordingLine[]) => void | Promise<void>;
+    clock?: () => number;
+}): () => Promise<void>;
+/**
+ * Every document of the run as it stands, as whole values marked `snapshot: true` at commit `at`, in document id order:
+ * the state a process records after it opens the run and before it resumes, so the recording is exact after any kill.
+ * `storage` is the store the run's Harness was opened over; `at` is the store's latest commit (pi's `Storage` has no
+ * head query: a disk run reads it with pi-durable-disk's `storeHead`). The reads are of the current state (pi keeps no
+ * past revision of a session or task document), so the snapshot is exact only while nothing commits: take it before
+ * the run resumes. Every line's `gen` is the highest `agentrun.driver` generation in it; `gen` is only for a run with no
+ * driver revision yet, and never overrides one.
+ */
+export declare function snapshotLines(storage: Pick<Storage, "scanConversations" | "scanTasks" | "scanDocuments" | "document">, options: {
+    at: number;
+    gen?: number;
+    context: Context;
+}): Promise<RecordingLine[]>;
+export {};