agentfootprint 12.2.0 → 13.0.0

package/dist/esm/core/agent/scripts/match.js

@@ -0,0 +1,226 @@
+/**
+ * scripts/match — is a fenced block the program ONE call of this turn
+ * submitted? Identity against the record, never evidence for a value.
+ *
+ * Pattern: pure function over the answer and this turn's rows.
+ * Role:    core/ layer. Asked inside the ONE judge closure the Route decider
+ *          builds (`stages/route.ts` · `judgeEvidence`, through `judge.ts`),
+ *          before the names-and-numbers extractor reads the text — so the
+ *          draft and the delivered candidate are read alike. Only under
+ *          `.namesAndNumbersFromEvidence({ code: 'match' })`.
+ * Emits:   N/A.
+ *
+ * ## The match rule: exact, after removing only the wrapper (design § 5.2)
+ *
+ * A block matches a call only when its content (`../evidence/codeRegions.ts`)
+ * equals the program the call SUBMITTED to the tool, byte for byte. Nothing is
+ * transformed: no trailing-space strip, no line-ending rewrite, no Unicode
+ * normalization, no shape, no edit distance — each can change a literal and so
+ * the program (`print(len("""A  \nB"""))` prints 5, its copy without the two
+ * spaces 3; `"é"` written with a combining mark is one more character than its
+ * NFC form). The strings are compared as they hold the text (UTF-16 code
+ * units): for well-formed text that is UTF-8 byte equality, and for a lone
+ * surrogate it is stricter, the safe direction.
+ *
+ * - Against the rows of the CURRENT TURN only; earlier turns are counted
+ *   (`earlierTurnRows`), never compared, and a miss says "no submission of
+ *   this turn", never "no submission".
+ * - A block over `MAX_SCRIPT_BYTES` is `over-size`: no row keeps a program
+ *   that long, so it is never compared.
+ * - Two calls that submitted byte-identical programs: the block names the
+ *   LATEST, counts the rest (`alsoMatches`) and carries its label.
+ * - No nearest submission is ever named: a near match is a different program.
+ *
+ * WHAT A MATCH YIELDS. The block is script content: it is cut out of the text
+ * the extractor reads, so it yields no value candidates — and it grounds
+ * nothing: the evidence corpus is untouched, so a value in the prose that also
+ * sits in the script still needs a result. A MISS stays in the text and is
+ * checked as prose, exactly as today.
+ *
+ * COST. One linear scan of the answer (`codeRegionsOf`); each of at most
+ * `MAX_CODE_REGIONS` blocks is looked up once among at most `MAX_SCRIPT_ROWS`
+ * programs of at most `MAX_SCRIPT_BYTES` — within the 512 comparisons per
+ * judged answer of design § 4.4. Earlier turns add nothing.
+ */
+import { codeRegionsOf, MAX_CODE_REGIONS } from '../evidence/codeRegions.js';
+import { utf8Length } from '../../../lib/utf8.js';
+import { exitCodeFits, SCRIPT_LABELS } from './label.js';
+import { MAX_SCRIPT_BYTES } from './rows.js';
+/** The text with `cut` regions removed, whole lines each (fence lines included). */
+function without(text, cut) {
+    if (cut.length === 0)
+        return text;
+    const parts = [];
+    let from = 0;
+    for (const region of cut) {
+        parts.push(text.slice(from, region.start));
+        from = region.end;
+    }
+    parts.push(text.slice(from));
+    return parts.join('');
+}
+/** Whether a block's content is over the per-script bound — never compared then. */
+function overSize(content) {
+    // Every UTF-16 unit is at least one UTF-8 byte: a long string is over at once.
+    return content.length > MAX_SCRIPT_BYTES || utf8Length(content) > MAX_SCRIPT_BYTES;
+}
+/**
+ * Read `answer`'s fenced blocks against this turn's submissions. Pure; the
+ * rows are `rows.ts` · `scriptRowsOfTurn`'s reading (last row per call).
+ */
+export function readShownScripts(answer, turn, scriptsDropped) {
+    const { regions, dropped } = codeRegionsOf(answer);
+    // The programs this turn submitted, each with every call that submitted it,
+    // in the order the calls were made — the last is "the latest".
+    const byProgram = new Map();
+    for (const row of turn.current) {
+        if (row.text === undefined)
+            continue;
+        const calls = byProgram.get(row.text);
+        if (calls === undefined)
+            byProgram.set(row.text, [row]);
+        else
+            calls.push(row);
+    }
+    const blocks = [];
+    const matched = [];
+    for (const region of regions) {
+        if (overSize(region.content)) {
+            blocks.push({ block: region.block, label: 'unmatched', reason: 'over-size' });
+            continue;
+        }
+        const calls = byProgram.get(region.content);
+        if (calls === undefined) {
+            blocks.push({ block: region.block, label: 'unmatched', reason: 'no-submission-this-turn' });
+            continue;
+        }
+        const latest = calls[calls.length - 1];
+        matched.push(region);
+        blocks.push({
+            block: region.block,
+            label: latest.outcome,
+            ...(latest.exitCode !== undefined && { exitCode: latest.exitCode }),
+            toolCallId: latest.toolCallId,
+            tool: latest.tool,
+            dispatch: latest.dispatch,
+            ...(calls.length > 1 && { alsoMatches: calls.length - 1 }),
+        });
+    }
+    return {
+        prose: without(answer, matched),
+        outsideCode: without(answer, regions),
+        verdict: {
+            blocks,
+            earlierTurnRows: turn.earlier,
+            regionsDropped: dropped,
+            ...(scriptsDropped !== undefined && scriptsDropped > 0 && { scriptsDropped }),
+        },
+    };
+}
+/**
+ * A verdict as detached plain data — field by field, never a reference into
+ * state (a value read back through a TypedScope is a live view, and an event
+ * payload must be plain data).
+ */
+export function copyScriptsVerdict(verdict) {
+    return {
+        blocks: verdict.blocks.map((b) => b.label === 'unmatched'
+            ? { block: b.block, label: 'unmatched', reason: b.reason }
+            : {
+                block: b.block,
+                label: b.label,
+                ...(b.exitCode !== undefined && { exitCode: b.exitCode }),
+                toolCallId: b.toolCallId,
+                tool: b.tool,
+                dispatch: b.dispatch,
+                ...(b.alsoMatches !== undefined && { alsoMatches: b.alsoMatches }),
+            }),
+        earlierTurnRows: verdict.earlierTurnRows,
+        regionsDropped: verdict.regionsDropped,
+        ...(verdict.scriptsDropped !== undefined && { scriptsDropped: verdict.scriptsDropped }),
+    };
+}
+// ─── Reading a record back ────────────────────────────────────────────
+//
+// A saved verdict is JSON a reader is handed, not a value this library holds.
+// ONE rule reads its fields for every reader of the shape — the answer
+// account (`evidence_checked.scripts`) and the checkpoint door's
+// `script-shown` witness row (`assessment/witness.ts`) — and it refuses
+// exactly what no writer of this library files.
+/** Every reason a block can be unmatched for. */
+export const UNMATCHED_REASONS = Object.freeze([
+    'no-submission-this-turn',
+    'over-size',
+    'kept-out',
+]);
+const isObject = (value) => value !== null && typeof value === 'object' && !Array.isArray(value);
+const isPositive = (value) => typeof value === 'number' && Number.isInteger(value) && value >= 1;
+/**
+ * One block verdict's fields, checked as {@link readShownScripts} writes them
+ * — a fresh copy, or `undefined` when any field is one no writer of this
+ * library files: a position or a dispatch that is not a whole number from 1,
+ * a label outside the vocabulary, an exit code its label does not carry
+ * (`label.ts` · `exitCodeFits`), an unmatched block that names a call, a
+ * matched one without its call. Fields beside these (a witness row's `kind`,
+ * `turn`, `iteration`) are not read.
+ */
+export function blockVerdictOf(value) {
+    if (!isObject(value))
+        return undefined;
+    const { block, label, reason, toolCallId, tool, dispatch, exitCode, alsoMatches } = value;
+    if (!isPositive(block))
+        return undefined;
+    if (label === 'unmatched') {
+        const named = toolCallId !== undefined ||
+            tool !== undefined ||
+            dispatch !== undefined ||
+            exitCode !== undefined ||
+            alsoMatches !== undefined;
+        if (named || !UNMATCHED_REASONS.includes(reason))
+            return undefined;
+        return { block, label: 'unmatched', reason: reason };
+    }
+    if (reason !== undefined || !SCRIPT_LABELS.includes(label)) {
+        return undefined;
+    }
+    if (!exitCodeFits(label, exitCode))
+        return undefined;
+    if (typeof toolCallId !== 'string' || typeof tool !== 'string')
+        return undefined;
+    if (!isPositive(dispatch))
+        return undefined;
+    if (alsoMatches !== undefined && !isPositive(alsoMatches))
+        return undefined;
+    return {
+        block,
+        label: label,
+        ...(exitCode !== undefined && { exitCode: exitCode }),
+        toolCallId,
+        tool,
+        dispatch,
+        ...(alsoMatches !== undefined && { alsoMatches }),
+    };
+}
+/**
+ * A saved `evidence_checked.scripts` — THE reader of the shape for a reader
+ * of a record. `undefined` when the event carries no scripts arm. Bounded by
+ * the writer's cap: no reader iterates more verdicts than a writer files.
+ */
+export function recordedBlocks(value) {
+    if (value === undefined)
+        return undefined;
+    if (!isObject(value) || !Array.isArray(value.blocks))
+        return { blocks: [], unread: 1 };
+    const all = value.blocks;
+    const blocks = [];
+    let unread = Math.max(0, all.length - MAX_CODE_REGIONS);
+    for (let index = 0; index < Math.min(all.length, MAX_CODE_REGIONS); index++) {
+        const verdict = blockVerdictOf(all[index]);
+        if (verdict === undefined)
+            unread += 1;
+        else
+            blocks.push({ index, verdict });
+    }
+    return { blocks, unread };
+}
+//# sourceMappingURL=match.js.map

package/dist/esm/core/agent/scripts/match.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"match.js","sourceRoot":"","sources":["../../../../../src/core/agent/scripts/match.ts"],"names":[],"mappings":"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"}

package/dist/esm/core/agent/scripts/recovery.d.ts

@@ -0,0 +1,54 @@
+/**
+ * scripts/recovery — the one clause the evidence revision request gains under
+ * `code: 'match'`: keep the script, fix the values.
+ *
+ * Pattern: Lens — a library sentence about a FINISHED call, composed from the
+ *          match's verdict, in the past tense, naming no tool as where to go
+ *          next (`core/agent/README.md`, the correction law). Request-only:
+ *          it rides the internal recovery instruction (`../evidence/recovery.ts`
+ *          · `buildEvidenceRecovery`), never history.
+ * Role:    core/ layer. Composed by the Route decider, which holds this turn's
+ *          rows, and carried to the recheck stage on `evidenceUnsupported`.
+ * Emits:   N/A.
+ *
+ * Two clauses, chosen by what the verdict holds (design § 7):
+ *
+ * - a block that matched no submission, and a flagged value that sat only in
+ *   such a block — its contents were checked as prose: keep a script, show it
+ *   exactly as submitted, or say the code shown is not the one submitted, and
+ *   fix the values in the prose;
+ * - a block that matched a call, with values flagged in the prose — the
+ *   script was not checked: keep it; the listed values were in the prose.
+ *
+ * The parenthesis carries the call's ACTUAL label in its words
+ * (`label.ts` · `labelWords`) — never a fixed "executed", never an exit
+ * number the record does not hold.
+ *
+ * WHAT IT CANNOT DO, stated: deleting an unmatched block removes its
+ * candidates and the `script-unmatched` reason, so a draft without the script
+ * can pass the check. No sentence makes a model keep a script; mandatory
+ * display comes from `.scriptTravelsWithTheAnswer()`, which needs no
+ * cooperation from the model.
+ *
+ * @example
+ * ```ts
+ * scriptRecoveryClause({ blocks: [{ block: 1, label: 'completed-with-failure', exitCode: 7,
+ *   toolCallId: 'c1', tool: 'run_code' }], earlierTurnRows: 0, regionsDropped: 0 },
+ *   [{ value: '1200', shape: 'number', region: 'prose' }], ['run_code']);
+ * // 'The script shown is the one submitted to `run_code` on call c1 (completed with failure,
+ * //  exit 7) and was not checked. Keep it. The listed values were in the prose around it.'
+ * ```
+ */
+import type { ScriptsVerdict } from './types.js';
+/** A flagged value as the clause reads it — its region under `code: 'match'`. */
+interface FlaggedValue {
+    readonly region?: 'prose' | 'code';
+}
+/**
+ * The clause(s) for one rejected draft — `''` when the verdict calls for
+ * none (no fenced block, or no flagged value the blocks bear on).
+ * `toolsThisTurn` names the code-running tools this turn's calls submitted
+ * to, in first-call order.
+ */
+export declare function scriptRecoveryClause(scripts: ScriptsVerdict, unsupported: readonly FlaggedValue[], toolsThisTurn: readonly string[]): string;
+export {};

package/dist/esm/core/agent/scripts/recovery.js

@@ -0,0 +1,77 @@
+/**
+ * scripts/recovery — the one clause the evidence revision request gains under
+ * `code: 'match'`: keep the script, fix the values.
+ *
+ * Pattern: Lens — a library sentence about a FINISHED call, composed from the
+ *          match's verdict, in the past tense, naming no tool as where to go
+ *          next (`core/agent/README.md`, the correction law). Request-only:
+ *          it rides the internal recovery instruction (`../evidence/recovery.ts`
+ *          · `buildEvidenceRecovery`), never history.
+ * Role:    core/ layer. Composed by the Route decider, which holds this turn's
+ *          rows, and carried to the recheck stage on `evidenceUnsupported`.
+ * Emits:   N/A.
+ *
+ * Two clauses, chosen by what the verdict holds (design § 7):
+ *
+ * - a block that matched no submission, and a flagged value that sat only in
+ *   such a block — its contents were checked as prose: keep a script, show it
+ *   exactly as submitted, or say the code shown is not the one submitted, and
+ *   fix the values in the prose;
+ * - a block that matched a call, with values flagged in the prose — the
+ *   script was not checked: keep it; the listed values were in the prose.
+ *
+ * The parenthesis carries the call's ACTUAL label in its words
+ * (`label.ts` · `labelWords`) — never a fixed "executed", never an exit
+ * number the record does not hold.
+ *
+ * WHAT IT CANNOT DO, stated: deleting an unmatched block removes its
+ * candidates and the `script-unmatched` reason, so a draft without the script
+ * can pass the check. No sentence makes a model keep a script; mandatory
+ * display comes from `.scriptTravelsWithTheAnswer()`, which needs no
+ * cooperation from the model.
+ *
+ * @example
+ * ```ts
+ * scriptRecoveryClause({ blocks: [{ block: 1, label: 'completed-with-failure', exitCode: 7,
+ *   toolCallId: 'c1', tool: 'run_code' }], earlierTurnRows: 0, regionsDropped: 0 },
+ *   [{ value: '1200', shape: 'number', region: 'prose' }], ['run_code']);
+ * // 'The script shown is the one submitted to `run_code` on call c1 (completed with failure,
+ * //  exit 7) and was not checked. Keep it. The listed values were in the prose around it.'
+ * ```
+ */
+import { labelWords } from './label.js';
+/** `run_code`, `` `a` or `b` `` — the tools named, quoted. */
+function toolsNamed(tools) {
+    const quoted = tools.map((t) => `\`${t}\``);
+    if (quoted.length === 0)
+        return 'a code-running tool';
+    if (quoted.length === 1)
+        return quoted[0];
+    return `${quoted.slice(0, -1).join(', ')} or ${quoted[quoted.length - 1]}`;
+}
+/**
+ * The clause(s) for one rejected draft — `''` when the verdict calls for
+ * none (no fenced block, or no flagged value the blocks bear on).
+ * `toolsThisTurn` names the code-running tools this turn's calls submitted
+ * to, in first-call order.
+ */
+export function scriptRecoveryClause(scripts, unsupported, toolsThisTurn) {
+    const clauses = [];
+    const unmatched = scripts.blocks.some((b) => b.label === 'unmatched');
+    if (unmatched && unsupported.some((v) => v.region === 'code')) {
+        clauses.push(`The fenced code in the rejected draft matched no submission to ${toolsNamed(toolsThisTurn)} recorded this turn, so its contents were checked as prose. Keep a script in the ` +
+            'answer: show the program exactly as it was submitted on that call, byte for byte, or ' +
+            'say that the code shown is not the one that was submitted. Fix the values in the prose.');
+    }
+    const matched = scripts.blocks.flatMap((b) => (b.label === 'unmatched' ? [] : [b]));
+    if (matched.length > 0 && unsupported.some((v) => v.region === 'prose')) {
+        const calls = matched.map((b) => `to \`${b.tool}\` on call ${b.toolCallId} (${labelWords(b.label, b.exitCode)})`);
+        clauses.push(matched.length === 1
+            ? `The script shown is the one submitted ${calls[0]} and was not checked. Keep it. The ` +
+                'listed values were in the prose around it.'
+            : `The scripts shown are the ones submitted ${calls.join(' and ')} and were not checked. ` +
+                'Keep them. The listed values were in the prose around them.');
+    }
+    return clauses.join(' ');
+}
+//# sourceMappingURL=recovery.js.map

package/dist/esm/core/agent/scripts/recovery.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"recovery.js","sourceRoot":"","sources":["../../../../../src/core/agent/scripts/recovery.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAwCG;AAEH,OAAO,EAAE,UAAU,EAAE,MAAM,YAAY,CAAC;AAQxC,8DAA8D;AAC9D,SAAS,UAAU,CAAC,KAAwB;IAC1C,MAAM,MAAM,GAAG,KAAK,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC;IAC5C,IAAI,MAAM,CAAC,MAAM,KAAK,CAAC;QAAE,OAAO,qBAAqB,CAAC;IACtD,IAAI,MAAM,CAAC,MAAM,KAAK,CAAC;QAAE,OAAO,MAAM,CAAC,CAAC,CAAW,CAAC;IACpD,OAAO,GAAG,MAAM,CAAC,KAAK,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,OAAO,MAAM,CAAC,MAAM,CAAC,MAAM,GAAG,CAAC,CAAC,EAAE,CAAC;AAC7E,CAAC;AAED;;;;;GAKG;AACH,MAAM,UAAU,oBAAoB,CAClC,OAAuB,EACvB,WAAoC,EACpC,aAAgC;IAEhC,MAAM,OAAO,GAAa,EAAE,CAAC;IAC7B,MAAM,SAAS,GAAG,OAAO,CAAC,MAAM,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,KAAK,KAAK,WAAW,CAAC,CAAC;IACtE,IAAI,SAAS,IAAI,WAAW,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,MAAM,KAAK,MAAM,CAAC,EAAE,CAAC;QAC9D,OAAO,CAAC,IAAI,CACV,kEAAkE,UAAU,CAC1E,aAAa,CACd,mFAAmF;YAClF,uFAAuF;YACvF,yFAAyF,CAC5F,CAAC;IACJ,CAAC;IACD,MAAM,OAAO,GAAG,OAAO,CAAC,MAAM,CAAC,OAAO,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,CAAC,KAAK,KAAK,WAAW,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;IACpF,IAAI,OAAO,CAAC,MAAM,GAAG,CAAC,IAAI,WAAW,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,MAAM,KAAK,OAAO,CAAC,EAAE,CAAC;QACxE,MAAM,KAAK,GAAG,OAAO,CAAC,GAAG,CACvB,CAAC,CAAC,EAAE,EAAE,CAAC,QAAQ,CAAC,CAAC,IAAI,cAAc,CAAC,CAAC,UAAU,KAAK,UAAU,CAAC,CAAC,CAAC,KAAK,EAAE,CAAC,CAAC,QAAQ,CAAC,GAAG,CACvF,CAAC;QACF,OAAO,CAAC,IAAI,CACV,OAAO,CAAC,MAAM,KAAK,CAAC;YAClB,CAAC,CAAC,yCAAyC,KAAK,CAAC,CAAC,CAAC,qCAAqC;gBACpF,4CAA4C;YAChD,CAAC,CAAC,4CAA4C,KAAK,CAAC,IAAI,CAAC,OAAO,CAAC,yBAAyB;gBACtF,6DAA6D,CACpE,CAAC;IACJ,CAAC;IACD,OAAO,OAAO,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;AAC3B,CAAC"}

package/dist/esm/core/agent/scripts/rows.d.ts

@@ -0,0 +1,143 @@
+/**
+ * scripts/rows — the `script` row: built from one call, filed through ONE
+ * writer, read back per turn, and bounded.
+ *
+ * Pattern: Map + one writer (the `findings/ledger.ts` · `recordFindings`
+ *          twin for this kind): `scriptRowFor` builds, `recordScriptRow` is
+ *          the only thing that writes a `script` row, `scriptRowsOfTurn` is
+ *          the one reader the match and the attachment share.
+ * Role:    core/ layer leaf. Called by the dispatch loop (`stages/toolCalls.ts`)
+ *          at each place a call of a declared code-running tool pauses or
+ *          settles; read by the Route decider's judge and the final branch.
+ * Emits:   N/A — the row is state; the runner's facts already rode
+ *          `agentfootprint.tools.code_run`, which never carries the code.
+ *
+ * ## One unit, and the bounds (design § 4.4)
+ *
+ * UTF-8 payload bytes of the program, measured at record time
+ * (`lib/utf8.ts` · `utf8Length`) — never characters: 32,768 characters of a
+ * 3-byte character are 98,304 bytes.
+ *
+ * - **Per script.** A program over {@link MAX_SCRIPT_BYTES} keeps a row with
+ *   `bytes`, `lines` and the outcome, and no `text`: it can be neither matched
+ *   nor attached.
+ * - **Per turn.** {@link MAX_SCRIPT_ROWS} calls keep a row; a further call of
+ *   the turn files none and is counted in `AgentState.scriptsDropped`.
+ * - **Eligible text.** A row's `text` lives for its own turn: the seed stage's
+ *   restore drops it from every earlier turn's row (`withoutEarlierScriptText`),
+ *   so the text the ledger holds is at most 16 × 32,768 bytes = 512 KiB before
+ *   serialization, whatever the conversation's length. That bounds eligible
+ *   text only — prior turns' metadata, history and the answers that carried an
+ *   attached script are outside it.
+ *
+ * ## Append only, last wins
+ *
+ * A call PAUSED before it settles (a check-in, a consent, an ask, a tool that
+ * asked a person) files a `submitted` row at the pause, WITHOUT its text: the
+ * settled row filed when the call resumes is the one that carries it, so a
+ * program is never held twice. A reader takes the LAST row per call of the
+ * turn (the ledger's own law). A row that never settles stays `submitted`.
+ */
+import type { ToolScript } from '../../../tools/script.js';
+import type { FindingsLedger } from '../findings/types.js';
+import { type CallSettlement, type RunnerOutcome } from './label.js';
+import type { ScriptRow } from './types.js';
+/** A program longer than this (UTF-8 bytes) keeps a row with no text. Design § 4.4. */
+export declare const MAX_SCRIPT_BYTES = 32768;
+/** Calls per turn that keep a row; the rest are counted. Design § 4.4. */
+export declare const MAX_SCRIPT_ROWS = 16;
+/** Lines of a program: LF-separated, `0` for an empty one. */
+export declare function linesOf(program: string): number;
+/** One call of a declared code-running tool, as the dispatch loop knows it. */
+export interface ScriptCall {
+    readonly script: ToolScript;
+    /** The name the model called. */
+    readonly tool: string;
+    readonly toolCallId: string;
+    readonly iteration: number;
+    /** `AgentState.turnNumber`. */
+    readonly turn: number;
+    /**
+     * The declared argument's VALUE as the model proposed it — read once, as
+     * the call arrived, before any before-tool rule ran (`programIn`). A string
+     * is immutable: no code that runs later can change what was captured.
+     */
+    readonly proposed: unknown;
+    /**
+     * The declared argument's value as handed to `execute` — read once, just
+     * before the tool ran, after every rule. Absent: the call never got there,
+     * and the proposal stands.
+     */
+    readonly submitted?: unknown;
+    readonly settlement: CallSettlement;
+    /** The runner's facts, when the tool filed them. */
+    readonly facts?: RunnerOutcome;
+    /** The tool's own ceiling replaced the delivered result. */
+    readonly withheld?: boolean;
+    /** A pause: the row is filed without its text (the settled row carries it). */
+    readonly paused?: boolean;
+}
+/**
+ * The declared argument's value in `args` — the one read a call's program is
+ * captured with. Read it at the boundary it names (as the call arrives; just
+ * before `execute`) and keep the value: never the arguments object, which app
+ * code may edit after it was handed over.
+ */
+export declare function programIn(script: ToolScript, args: Readonly<Record<string, unknown>> | undefined): unknown;
+/** A row before the writer gives it its dispatch identity. */
+export type ScriptRowDraft = Omit<ScriptRow, 'dispatch'>;
+/**
+ * The row for one call, or `undefined` when the call carried no program — the
+ * declared argument is not a string (an argument check refuses such a call;
+ * there is nothing to record as "the program submitted").
+ */
+export declare function scriptRowFor(call: ScriptCall): ScriptRowDraft | undefined;
+/** The scope surface the writer needs. Structurally a `TypedScope<AgentState>`. */
+export interface ScriptScope {
+    findingsLedger?: FindingsLedger;
+    scriptsDropped?: number;
+}
+/**
+ * THE ONE WRITER of a `script` row, and the one place a call gets its
+ * DISPATCH identity: the 1-based order of the actual dispatch within its turn.
+ * A call is a dispatch, never a provider id: a later call that reuses an id is
+ * a new dispatch. `options.dispatch` names a dispatch that already has a row
+ * (a paused call, settling): its row joins that dispatch.
+ *
+ * Appended, unless the turn already holds {@link MAX_SCRIPT_ROWS} other
+ * dispatches — then the call files nothing and `scriptsDropped` counts it
+ * (value-conditional: absent until a call is dropped). A dispatch that already
+ * has a row is never dropped, and a PAUSE is never counted (`paused`): its call
+ * is counted once, when it settles. Returns the dispatch the row was filed
+ * under, `undefined` when it was dropped. Synchronous: one read, one write, no
+ * await between.
+ */
+export declare function recordScriptRow(scope: ScriptScope, draft: ScriptRowDraft, options?: {
+    readonly paused?: boolean;
+    readonly dispatch?: number;
+}): number | undefined;
+/** This turn's calls — the LAST row of each dispatch, in the order those rows were filed. */
+export interface TurnScripts {
+    readonly current: readonly ScriptRow[];
+    /** Calls of EARLIER turns on the ledger: counted, never compared. */
+    readonly earlier: number;
+}
+/**
+ * The one reader of a turn's script rows: the last row per DISPATCH wins, and
+ * a dispatch sits where its last row was filed — execution order, so a call
+ * that settles after a later one ran is read after it. Earlier turns counted.
+ */
+export declare function scriptRowsOfTurn(ledger: readonly unknown[] | undefined, turn: number): TurnScripts;
+/**
+ * The restore door's half of the bound (seed): every `script` row of a turn
+ * BEFORE `turn` keeps its facts — ids, counts, outcome — and loses its `text`.
+ * The same reference when there is nothing to drop, so a ledger without
+ * script text is restored byte for byte.
+ */
+export declare function withoutEarlierScriptText<T>(ledger: readonly T[], turn: number): readonly T[];
+/**
+ * Whether a value read from a stored checkpoint is a `script` row this library
+ * could have written — the checkpoint door's arm (`core/runCheckpoint.ts`).
+ * An older runtime refuses a checkpoint carrying one.
+ */
+export declare function scriptRowIsWellFormed(r: Readonly<Record<string, unknown>>): boolean;