agentfootprint 10.2.0 → 10.3.1

package/dist/esm/semantics/coverage/absent.js

@@ -0,0 +1,349 @@
+/**
+ * absent — an absence that names its own coverage.
+ *
+ * Pattern: minted by a helper, RECOGNIZED by the framework (the tool-effects
+ *          envelope precedent). A return shape the framework does not
+ *          understand is a convention, and a convention cannot set a status,
+ *          keep a value out of the evidence corpus, or stop a retry loop.
+ * Role:    core/ layer, pure. The dispatch loop calls `readAbsence` at the
+ *          execute boundary; `absent()` is what a tool author writes.
+ * Emits:   N/A (the caller emits `agentfootprint.tools.absent`).
+ *
+ * ## The direction-of-error argument — the whole point of this file
+ *
+ * A tool that finds nothing returns *something*: an empty array, a `null`, a
+ * sentence. From any of those a model cannot tell **"I looked and there is
+ * nothing"** from **"I could not look"**. That confusion is not symmetric,
+ * and the asymmetry is what makes it worth a primitive:
+ *
+ *   • a *nothing-found* misread as an *outage* sends someone to investigate a
+ *     collector that is working perfectly — expensive, and self-correcting.
+ *   • an *outage* misread as *nothing-found* declares a system healthy that
+ *     was never checked — cheap, silent, and wrong in the direction that
+ *     hurts.
+ *
+ * So the two must not share a shape. An error is a `role: 'tool'` result with
+ * `error: true`, a message, and no coverage. An absence is this: a result
+ * that RAN, carries the ground it covered, and says out loud that asking
+ * again changes nothing.
+ *
+ * ## Why the note is never interpolated
+ *
+ * Tool results are the evidence gate's corpus, so an absence that echoed the
+ * model's own arguments into that corpus would GROUND every identifier a model
+ * invented, as long as it handed the invention to one tool that found nothing.
+ * That is laundering an invention through a failed lookup — the same bug
+ * `evidence/frames.ts` exists to stop on the other side of the conversation.
+ *
+ * The gate therefore withholds `looked_for` (see `coverage/evidence.ts`): it
+ * is the one field whose job is to quote the request. The record-only item
+ * keys `short` and `kind` are withheld with it — a short form restates
+ * `what`, so nothing is lost, and it is the field an author is most tempted to
+ * personalise. Everything else the absence carries — the coverage lists, the
+ * author's `tryInstead` and `tryInsteadTool`, any extra key the tool attached
+ * to the envelope — is the TOOL speaking about the world and does ground,
+ * because an answer that follows the absence's own advice must not be called
+ * ungrounded for doing so.
+ * The note is kept free of interpolation for the same reason the exclusion
+ * exists: static library text has nothing of the caller's to leak.
+ *
+ * ## A suggestion to try another tool is typed, never parsed (9.113.0)
+ *
+ * `tryInstead` is ONE sentence, for the model; nothing in this library reads
+ * a tool name out of it. When the sentence points at another tool, the author
+ * names that tool beside it — `tryInsteadTool: { tool, why? }` — and the
+ * envelope carries it under its OWN key, `try_instead_tool`. Its own key, not
+ * `try_instead`: that field has been a string since it shipped and every
+ * reader typed against `ToolAbsence` reads it as one, so a second shape there
+ * would be dropped by each of them without a word. `tools.absent` carries
+ * both, as declared. ONE rule set decides what each is ({@link readSentence},
+ * {@link readToolSuggestion}): `absent()` refuses by it and the recognizer
+ * reads by it, so a mint and a read cannot disagree.
+ */
+import { mintProvenance } from '../described.js';
+import { warnIfInvalidToolName } from '../../lib/toolName.js';
+import { normalizeCoverageList } from './items.js';
+import { mintPeriod } from './period.js';
+import { refusal, refuseUnknownKeys } from './refusal.js';
+// The recognizer lives in the leaf `recognize.ts` (a post-hoc reader asks it
+// without loading this mint); re-exported here so every import keeps working.
+import { ABSENCE_MARKER, readAbsence } from './recognize.js';
+export { ABSENCE_MARKER, readAbsence };
+/**
+ * The static sentence every absence carries. Says the three things the field
+ * implementation proved a model needs: that the call SUCCEEDED, that nothing
+ * was substituted, and that a retry is futile. The third clause is the one
+ * that ends the loop.
+ */
+// One literal on purpose: its TYPE is the sentence, so a redacted record keeps
+// it as the library's own words (`redaction/knownStrings.ts`).
+export const ABSENCE_NOTE = 'The search ran and matched nothing. This is an ANSWER, not an error: nothing failed, nothing was substituted for what was asked, and calling this tool again with the same arguments returns this same result. `checked` is the ground this answer covers; anything under `not_checked` or `cannot_cover` is ground it does NOT cover, and reaching that needs a different question, not a retry.';
+/**
+ * The note the MODEL is served in place of {@link ABSENCE_NOTE} when the
+ * absence's own period is `partly-held` or `not-held` (honesty step 7b, bench
+ * round 1) — `coverage/read.ts` · `strip` swaps it in and appends the period's
+ * one clause. It keeps what stays true (the call ran, a retry returns the same
+ * result) and drops the two completeness claims that do not: "nothing was
+ * substituted for what was asked" and `checked` as the whole ground. Static,
+ * never interpolated, never minted — the tool's own output keeps
+ * {@link ABSENCE_NOTE}.
+ */
+export const ABSENCE_NOTE_HELD_ONLY = 'The search ran and matched nothing — the call did not fail, and calling this tool again ' +
+    'with the same arguments returns this same result. `checked` is the ground this answer ' +
+    'covers inside `period.held` only; anything under `not_checked` or `cannot_cover` is ground ' +
+    'it does NOT cover, and reaching that needs a different question, not a retry.';
+/**
+ * The typed tool's keys, tied to {@link TryInsteadTool} in BOTH directions: a
+ * key the interface gains, or one listed here that it does not have, fails to
+ * compile. Any other key on a value is refused, so a misspelt `why` cannot
+ * vanish without a word.
+ */
+const TOOL_SUGGESTION_KEYS = Object.keys({
+    tool: true,
+    why: true,
+});
+/**
+ * The declaration's keys, tied to {@link AbsenceDeclaration} in BOTH
+ * directions, the {@link TOOL_SUGGESTION_KEYS} way. Any other key is refused,
+ * naming the spelling meant when it is a slip of one of these: a declaration
+ * fed from plain JavaScript or JSON with `not_checked` used to mint without
+ * that list, and the limit it declared vanished without a word.
+ */
+const ABSENCE_DECLARATION_KEYS = Object.keys({
+    what: true,
+    checked: true,
+    notChecked: true,
+    cannotCover: true,
+    tryInstead: true,
+    tryInsteadTool: true,
+    provenance: true,
+    period: true,
+});
+/**
+ * `undefined` and `null` both mean "not given" for the typed tool and its
+ * `why`. A JSON producer writes a missing optional value as `null`, and
+ * `tryInstead: null` read as no suggestion before 9.113.0 — refusing it would
+ * turn a nothing-found into a tool error, the direction of error this file
+ * exists to prevent.
+ */
+const notGiven = (raw) => raw === undefined || raw === null;
+/** An object literal's shape — `{…}` or `Object.create(null)`; never an
+ *  array, a Date, a boxed string or any other class instance. */
+const isPlainObject = (raw) => {
+    if (typeof raw !== 'object' || raw === null || Array.isArray(raw))
+        return false;
+    const prototype = Object.getPrototypeOf(raw);
+    return prototype === Object.prototype || prototype === null;
+};
+/**
+ * The rule for the SENTENCE (`tryInstead`, `try_instead` on the wire):
+ * trimmed, and one that trims to nothing is no suggestion, as it always was.
+ *
+ * ONE non-string is refused: a plain object. That is the typed form
+ * `{ tool, why? }` written into the sentence's slot, and the refusal points it
+ * at `tryInsteadTool` rather than drop the author's tool without a word. Any
+ * OTHER value that is not a string — `null`, `false` from
+ * `tryInstead: cond && '…'`, a number, a list, a Date — reads as no
+ * suggestion, exactly as it did before 9.113.0: `absent()` runs inside a
+ * tool's `execute`, so refusing it would turn a nothing-found the 9.112.2
+ * loop delivered as an absence into that call's error result.
+ */
+function readSentence(raw) {
+    if (typeof raw === 'string') {
+        const sentence = raw.trim();
+        return { value: sentence === '' ? undefined : sentence };
+    }
+    if (isPlainObject(raw)) {
+        return {
+            problem: '`tryInstead` is the sentence the model reads, and only that. To name the other ' +
+                'tool as data, give { tool, why? } as `tryInsteadTool`, beside the sentence.',
+        };
+    }
+    return { value: undefined };
+}
+/**
+ * The rule for the TYPED TOOL (`tryInsteadTool`, `try_instead_tool` on the
+ * wire): `{ tool, why? }`, where `tool` is a non-empty name and `why`, when
+ * given, says something. Both are trimmed; `why: null` reads as omitted. The
+ * name is recorded as declared: never looked up (a provider may serve it on a
+ * later iteration), and held to no charset here — which names a provider
+ * accepts is `lib/toolName.ts` · `assertValidToolName`'s question, and
+ * `absent` asks the dev-mode warning that owns it.
+ *
+ * Why ONE tool and not a list: every suggestion on record names at most one
+ * other tool, and where a sentence joins that tool to "or widen the window",
+ * the rest of the advice stays in the sentence. A list would be a second
+ * shape of this field for every reader to narrow — the cost this key exists
+ * to spare `try_instead`.
+ */
+function readToolSuggestion(raw) {
+    if (notGiven(raw))
+        return { value: undefined };
+    if (Array.isArray(raw)) {
+        return {
+            problem: '`tryInsteadTool` names ONE tool — { tool, why? }, never a list. Say the rest of the ' +
+                'advice in the `tryInstead` sentence.',
+        };
+    }
+    if (typeof raw !== 'object') {
+        return {
+            problem: `\`tryInsteadTool\` must be { tool, why? } — got ${typeof raw}. For a sentence, use ` +
+                '`tryInstead`; to suggest nothing, omit the field.',
+        };
+    }
+    const value = raw;
+    const unknownKey = Object.keys(value).find((key) => !TOOL_SUGGESTION_KEYS.includes(key));
+    if (unknownKey !== undefined) {
+        return {
+            problem: `\`tryInsteadTool\` has an unknown key '${unknownKey}' — the form is { tool, why? }, ` +
+                'and a misspelt `why` would otherwise vanish without a word.',
+        };
+    }
+    const { tool, why } = value;
+    if (typeof tool !== 'string' || tool.trim() === '') {
+        return {
+            problem: '`tryInsteadTool.tool` must name the tool to try — its registered name, e.g. ' +
+                "{ tool: 'cluster_inventory', why: 'it lists the collected names' }. The name is " +
+                'recorded as declared and never looked up (a provider may serve it).',
+        };
+    }
+    const name = tool.trim();
+    if (notGiven(why))
+        return { value: { tool: name } };
+    if (typeof why !== 'string' || why.trim() === '') {
+        return {
+            problem: `\`tryInsteadTool.why\` (for '${name}') must be a sentence — say why that tool, or ` +
+                'omit the field.',
+        };
+    }
+    return { value: { tool: name, why: why.trim() } };
+}
+/**
+ * Say "I looked, and there is nothing" in a way a model cannot read as a
+ * failure — and cannot productively retry.
+ *
+ * Returns the value a tool's `execute` should return. The framework
+ * recognizes it at the dispatch boundary and gives it a delivered status of
+ * `'absent'` (routable by `onToolStatus`), a `tools.absent` event, and an
+ * evidence-corpus rule of its own.
+ *
+ * Refuses (throws, where it is called) a declaration it cannot honor — and
+ * any key the declaration does not have, naming the spelling meant when the
+ * key is a casing slip (`not_checked` → `notChecked`), so a list declared
+ * from plain JavaScript or JSON cannot vanish without a word. Every refusal
+ * starts `refused: `: inside `execute` it becomes the call's error result,
+ * which the model reads.
+ *
+ * Since honesty step 7b an absence also says WHERE it looked and WHEN —
+ * `provenance: { measuredAt, source }`, the shape and rules `describedResult()`
+ * uses — and what time its read covered — `period: { queried, held, readAt? }`,
+ * ISO 8601 instants with a zone (`held` may be `'unknown'`). "Searched the 02:00
+ * export — nothing" becomes data; the results layer judges the period.
+ *
+ * @example a port-lookup tool that found no matching FLOGI
+ *   defineTool({
+ *     name: 'flogi_for_port',
+ *     description: 'FLOGI entries for one interface',
+ *     inputSchema: { type: 'object', properties: { switch: { type: 'string' },
+ *       port: { type: 'string' } }, required: ['switch', 'port'] },
+ *     execute: ({ switch: sw, port }) => {
+ *       const rows = fcns.flogi(sw, port);
+ *       if (rows.length > 0) return rows;
+ *       return absent({
+ *         what: `FLOGI entries on ${port}`,
+ *         checked: [
+ *           `${sw}: the live fcns database`,
+ *           { what: 'window: the last 24h', why: 'FLOGI history retention on this fabric' },
+ *         ],
+ *         notChecked: [{ what: 'the archived FLOGI history', why: 'older than the 24h window' }],
+ *         cannotCover: [{ what: 'ports on the peer fabric',
+ *           why: 'this collector is scoped to one fabric' }],
+ *         tryInstead: 'Ask for a different interface, or query the peer fabric by name.',
+ *       });
+ *     },
+ *   });
+ */
+export function absent(decl) {
+    const fn = 'absent';
+    if (typeof decl !== 'object' || decl === null) {
+        throw refusal(`${fn}() takes a declaration — { what, checked, notChecked?, cannotCover?, tryInstead?, ` +
+            `tryInsteadTool?, provenance?, period? }.`);
+    }
+    refuseUnknownKeys(decl, ABSENCE_DECLARATION_KEYS);
+    const what = typeof decl.what === 'string' ? decl.what.trim() : '';
+    if (what === '') {
+        throw refusal(`\`what\` must say what was looked for (e.g. 'FLOGI entries on fc1/3'). An ` +
+            `absence that cannot name what it did not find is indistinguishable from a tool that ` +
+            `returned nothing by accident.`);
+    }
+    const checked = normalizeCoverageList('checked', decl.checked, false);
+    if (checked.length === 0) {
+        throw refusal(`'${what}' — \`checked\` must name at least one source, window or population ` +
+            `that WAS searched. An absence with no coverage is a null with extra steps: the reader ` +
+            `still cannot tell "I looked and there is nothing" from "I could not look", which is ` +
+            `the confusion this function exists to remove. If you genuinely could not look, that ` +
+            `is an error — throw, or return a failure the model can retry.`);
+    }
+    const notChecked = normalizeCoverageList('notChecked', decl.notChecked, false);
+    const cannotCover = normalizeCoverageList('cannotCover', decl.cannotCover, true);
+    const sentence = readSentence(decl.tryInstead);
+    if (sentence.problem !== undefined)
+        throw refusal(`'${what}' — ${sentence.problem}`);
+    const tool = readToolSuggestion(decl.tryInsteadTool);
+    if (tool.problem !== undefined)
+        throw refusal(`'${what}' — ${tool.problem}`);
+    const tryInstead = sentence.value;
+    const tryInsteadTool = tool.value;
+    // The name's charset is the tool registry's question: the owner warns in
+    // dev mode and never throws — the verdict a `defineTool` of it would get.
+    if (tryInsteadTool !== undefined)
+        warnIfInvalidToolName(tryInsteadTool.tool);
+    // Honesty step 7b — the source and time of the search, by the ONE provenance
+    // rule `describedResult()` mints with (`semantics/described.ts` ·
+    // `mintProvenance`), and the period its read covered, by the ONE period rule
+    // (`period.ts` · `mintPeriod`). Each refuses at this line, in camelCase.
+    // `null` reads as omitted for either — a JSON producer's missing value.
+    const provenance = decl.provenance == null ? undefined : mintProvenance(decl.provenance);
+    const period = mintPeriod(decl.period);
+    return {
+        af_absent: true,
+        outcome: 'nothing_found',
+        looked_for: what,
+        checked,
+        ...(notChecked.length > 0 && { not_checked: notChecked }),
+        ...(cannotCover.length > 0 && { cannot_cover: cannotCover }),
+        ...(provenance !== undefined && { provenance }),
+        ...(period !== undefined && { period }),
+        retry_returns_the_same: true,
+        ...(tryInstead !== undefined && { try_instead: tryInstead }),
+        ...(tryInsteadTool !== undefined && { try_instead_tool: tryInsteadTool }),
+        note: ABSENCE_NOTE,
+    };
+}
+/** The absence's coverage, in the normalized three-list shape everything
+ *  downstream (the event, the answer block) reads. */
+export function coverageOfAbsence(absence) {
+    return {
+        checked: absence.checked ?? [],
+        notChecked: absence.not_checked ?? [],
+        cannotCover: absence.cannot_cover ?? [],
+    };
+}
+/**
+ * The absence's sentence, read by the rules `absent()` mints by. `undefined`
+ * when it declared none, AND when it declared one those rules refuse: an
+ * envelope minted elsewhere (a non-JS tool, a hand-built value) is read,
+ * never repaired, and the absence itself is still an absence either way.
+ */
+export function tryInsteadOfAbsence(absence) {
+    return readSentence(absence.try_instead).value;
+}
+/**
+ * The absence's typed tool, read by the same rules — a copy, never the
+ * object the envelope holds. `undefined` when it declared none, or one those
+ * rules refuse (see {@link tryInsteadOfAbsence}).
+ */
+export function tryInsteadToolOfAbsence(absence) {
+    return readToolSuggestion(absence.try_instead_tool).value;
+}
+//# sourceMappingURL=absent.js.map

package/dist/esm/semantics/coverage/absent.js.map

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

package/dist/esm/semantics/coverage/answer.d.ts

@@ -0,0 +1,197 @@
+/**
+ * answer — how a ledger survives into the final answer.
+ *
+ * Pattern: composed by the FRAMEWORK, not requested from the model. Pure
+ *          function of the run's declarations; the stage that calls it is a
+ *          two-line wrapper (see `stages/prepareFinal.ts`).
+ * Role:    core/ layer, pure.
+ * Emits:   N/A.
+ *
+ * ## Why this is an append and not a check
+ *
+ * A ledger the model can drop is worthless, and every mechanism that ASKS the
+ * model to carry it can be dropped: a note in the tool result is advice, a
+ * system-prompt rule is advice, and a judge that reads the answer back and
+ * asks "did it state its limits?" needs a second model to decide what
+ * counts — which would put a language judgement in the one place this library
+ * refuses to put one (see `evidence/README.md`: the guard may not need a
+ * bigger model than the thing it guards).
+ *
+ * So the limits are APPENDED. The model does not write them, so the model
+ * cannot drop them, and the mechanism is a string concatenation over data the
+ * tools declared — deterministic, auditable, and cheap. It changes the bytes
+ * of the answer, which is why it is opt-in
+ * (`.limitsTravelWithTheAnswer()`): an agent that never asks for it is
+ * byte-identical.
+ *
+ * ## Why a TYPED answer gets the same fold as data, never the block
+ *
+ * An answer with an output schema is JSON, and JSON followed by prose is not
+ * JSON — appending the block made `runTyped()` throw on every answer that had
+ * limits. So when an output schema is configured the answer string stays the
+ * model's own, and the same fold travels BESIDE it: `coverageOfAnswer` below,
+ * committed as `AgentState.answerCoverage`. The model still cannot drop it —
+ * the framework composes it from what the tools declared — and a person reads
+ * it wherever the app draws it, not wherever the prose happened to end.
+ *
+ * ## Why an absence contributes too
+ *
+ * `absent()` and `coverage()` make the same kind of statement about the same
+ * run. A search that found nothing in the fcns database really did cover the
+ * fcns database, and a search that could not reach the archive really is a
+ * limit on the answer. Folding both into one block is the only way the reader
+ * gets ONE boundary instead of a boundary per tool — and duplicates are
+ * dropped, so five tools naming the same missing collector say it once.
+ */
+import { type DeclaredPeriod } from './period.js';
+import type { BoundPresentation } from '../../time/present.js';
+import type { Coverage, DeclaredCoverage, InProgressItem } from './types.js';
+/**
+ * One declaring call's period, as the answer's limits carry it (honesty step
+ * 7b) — the tool, the call, and the period AS DECLARED: the data twin of one
+ * `Period:` line.
+ *
+ * @inline
+ */
+export interface AnswerPeriod extends DeclaredPeriod {
+    readonly toolName: string;
+    readonly toolCallId?: string;
+}
+/**
+ * One declaring call's in-progress items, as the answer's limits carry them —
+ * the tool, the call, and what its read found still running, as declared: the
+ * data twin of that call's lines under "In progress (outcome not known yet)".
+ *
+ * @inline
+ */
+export interface AnswerInProgress {
+    readonly toolName: string;
+    readonly toolCallId?: string;
+    readonly items: readonly InProgressItem[];
+}
+/**
+ * A TYPED answer's limits, as data — the three coverage lists the prose block
+ * would print, plus the values a tool's `assume` rule filled this turn (the
+ * inputs layer, honesty layer 2), which the prose answer prints as its
+ * "Assumed" block. The value of `AgentState.answerCoverage`,
+ * `turn_end.answerCoverage` and `agent.answerCoverage()`.
+ *
+ * `assumed` is the SAME reading of the SAME rows the block prints
+ * (`arguments/serve.ts` · `assumedLinesFor`): one entry per distinct (tool,
+ * argument, value), in the order the rows were filed, a row a before-tool
+ * rewrite superseded left out. `value` is the tool's own argument view —
+ * `'REDACTED'`, with `hidden: true`, when that view hides the argument.
+ * Present only when a value was assumed. `periods` (honesty step 7b) is the
+ * data twin of the block's `Period:` lines, present only when a call declared one.
+ */
+export interface AnswerCoverage extends Coverage {
+    /** The periods the calls declared (honesty step 7b) — one per declaring
+     *  call, as declared; present only when one did. */
+    readonly periods?: readonly AnswerPeriod[];
+    /** What the calls found still running — its outcome not known yet — one
+     *  entry per declaring call, as declared; present only when one did. Never a
+     *  reason on the answer's standing: a label that travels with the limits. */
+    readonly inProgress?: readonly AnswerInProgress[];
+    readonly assumed?: readonly {
+        readonly toolName: string;
+        readonly argument: string;
+        readonly value: string;
+        readonly hidden: boolean;
+    }[];
+}
+/** One assumed value as `AnswerCoverage` carries it. */
+type AssumedValue = NonNullable<AnswerCoverage['assumed']>[number];
+/** The block's opening line. Stable — tests and readers match on it. */
+export declare const COVERAGE_BLOCK_HEADING = "Coverage of this answer";
+/**
+ * The inputs layer's "Assumed" block's opening line (`arguments/serve.ts` ·
+ * `assumedBlock` composes the block). Owned here, beside the limits block's
+ * heading: this module's `composeAnswerWithCoverage` is the one composer of
+ * the section the framework appends after an answer, and a reader of the
+ * answer's text (`answer-account/account.ts` · `readAnswer`) finds every
+ * block of it through this one module. Stable — tests and readers match on it.
+ */
+export declare const ASSUMED_BLOCK_HEADING = "Assumed (a tool's rule, not your words):";
+/** The section heading the periods print under (honesty step 7b). Stable — readers match on it. */
+export declare const PERIOD_SECTION_LABEL = "Period";
+/** The section heading the wall-clock sources print under (the time layer, step T8). Stable. */
+export declare const CLOCKS_SECTION_LABEL = "Clocks";
+/**
+ * The time layer's limits lines (step T8), already composed from the record
+ * (`coverage/period.ts` · `periodCheckLine`, `clockLines`): `period` — one per
+ * call whose read differs from what was asked, shifted, or was older than the
+ * source keeps, printed under `Period` after the declared periods; `clocks` —
+ * the wall-clock sources, under `Clocks`. Passed only under `.time()`.
+ */
+export interface TimeLimitLines {
+    readonly period: readonly string[];
+    readonly clocks: readonly string[];
+    /**
+     * The MODEL's audience only (`coverage/timeLimits.ts` · `heldLine`): per call
+     * whose source holds none or only part of the asked time, what it asked
+     * about and what the source holds, in the person's zone. The person's block
+     * never reads it — its `Period:` line already prints both spans.
+     */
+    readonly held?: readonly string[];
+}
+/**
+ * The run's declarations folded into the ANSWER's coverage — the three lists
+ * `composeAnswerWithCoverage` renders, as data.
+ *
+ * `.limitsTravelWithTheAnswer()` on a typed answer (`.outputSchema()`): the
+ * answer string has to stay the model's JSON for `runTyped()` to parse it, so
+ * the limits travel beside it instead of inside it — this value, committed as
+ * `AgentState.answerCoverage`, projected onto `turn_end.answerCoverage` and
+ * returned by `agent.answerCoverage()`.
+ *
+ * Folded by the block's own fold (`foldSections`, the one place each list is
+ * merged — declaration order, duplicates dropped), so every entry is one the
+ * block would print and none is added. It keeps EVERY entry: the block's cap
+ * (twelve per section, then "… and N more") is a reading aid for prose, not a
+ * limit on the data.
+ *
+ * Fresh plain objects, copied field by field (`what`, `why`, and the
+ * record-only `short` / `kind` when declared), never a reference into the rows
+ * it was folded from — so the value can be committed, emitted and handed to a
+ * caller as detached data. `undefined` when nothing was declared: the identity
+ * case, the one every run whose tools declare nothing takes.
+ */
+export declare function coverageOfAnswer(declared: readonly DeclaredCoverage[]): AnswerCoverage | undefined;
+/**
+ * A typed answer's limits as ONE value: the folded coverage (or three empty
+ * lists) and the values assumed this turn, `assumed` present only when one
+ * was. `undefined` when there is neither — the identity case, so a run whose
+ * tools declared nothing and assumed nothing commits exactly the keys it
+ * always did.
+ */
+export declare function answerCoverageOf(folded: AnswerCoverage | undefined, assumed: readonly AssumedValue[]): AnswerCoverage | undefined;
+/** A coverage value as detached plain data — the same three lists, every item copied. */
+export declare function copyCoverage(value: Coverage): Coverage;
+/** A typed answer's limits as detached plain data — the lists and any assumed values, copied. */
+export declare function copyAnswerCoverage(value: AnswerCoverage): AnswerCoverage;
+/**
+ * Fold the run's declarations into one block and append it to the answer.
+ *
+ * Returns the answer UNCHANGED when nothing was declared — the identity case
+ * matters, because it is the one every agent that never returns a coverage
+ * shape takes.
+ *
+ * `standing` (the answer layer, honesty layer 4, under
+ * `.answerLayer({ standingLine: true })`) is the answer's standing as one
+ * already-composed line (`assessment/compose.ts` · `standingLineOf`); it opens
+ * the section, and while it is on the caller passes no `assumed` block — the
+ * line names the assumed values itself (one composer for one fact).
+ *
+ * `assumed` (the inputs layer, honesty layer 2) is a second, already-composed
+ * block — the values a tool's `assume` rule filled this turn
+ * (`arguments/serve.ts` · `assumedBlock`) — appended after the coverage block
+ * under the same separator. With neither declarations nor an assumed block the
+ * answer is unchanged, byte for byte.
+ *
+ * `presentation` (the time layer, only under `.time()`) is the run's clock
+ * zone: each `Period:` line renders its instants there, the zone named
+ * (`period.ts` · `periodLine`). Absent → the lines are the declared instants
+ * verbatim, as they always were.
+ */
+export declare function composeAnswerWithCoverage(answer: string, declared: readonly DeclaredCoverage[], assumed?: string, standing?: string, presentation?: BoundPresentation, time?: TimeLimitLines): string;
+export {};