agentfootprint 9.118.1 → 9.120.0

package/AGENTS.md

@@ -210,35 +210,57 @@ the model — the framework stamps `toolCallId` / `toolName` / `iteration`, you
 `payload`. `agent.on('agentfootprint.stream.*')` and `toSSE(agent)` carry it with
 no extra wiring.
 
-### When a tool finds nothing, and what a clean result does not cover
+### What a tool returns: rows, a verdict with limits, or nothing
+
+| helper | use it when | the model reads | the record keeps |
+|---|---|---|---|
+| `describedResult({ … })` | rows, a series or relationships from a system of record — or a question back (`clarify`) | data + `grain` + `provenance` + one `not_covered` line per gap + a static note — NOT the `checked` list | the whole envelope on `tools.semantics_declared`, coverage in `coverageDeclared` |
+| `coverage(value, { … })` | any other value that has limits (a verdict, a sentence) | your value under `result`, the coverage lists under `af_coverage` | `tools.coverage_declared`, `coverageDeclared` |
+| `absent({ … })` | nothing matched | what was looked for, the coverage, "a retry returns the same" | `tools.absent`, `coverageDeclared`, status `'absent'` |
+
+The rule: rows from a system of record → `describedResult()`; any other value with limits →
+`coverage()`; nothing matched → `absent()`. Never wrap one in another. All three are the tool's
+RESPONSE — nothing goes into the system prompt or the tool schema.
 
 ```typescript
-import { absent, coverage, defineTool } from 'agentfootprint';
-
-// "I looked and there is nothing" — never readable as "I could not look".
-execute: ({ port }) => rows.length ? rows : absent({
-  what: `FLOGI entries on ${port}`,
-  checked: ['shq-fab-a: the live fcns database', 'window: the last 24h'],
-  notChecked: [{ what: 'the archived history', why: 'older than the 24h window' }],
-  cannotCover: [{ what: 'the peer fabric', why: 'this collector is scoped to one fabric' }],
-  tryInstead: 'Ask for a different interface, or query the peer fabric by name.',
-}),
-
-// A verdict WITH its boundary — what "fine" does and does not rule out.
-execute: async () => coverage(await checkReplication(), {
-  checked: ['SRDF pair state on all 4 arrays'],
-  cannotCover: [{ what: 'host-side multipathing', why: 'no collector on the ESX hosts' }],
-}),
+import { absent, coverage, defineTool, describedResult } from 'agentfootprint';
+
+execute: ({ vm, summary }) => {
+  const { exportedAt, source, runs: all } = backupExport;   // the system of record
+  const runs = all.filter((r) => r.vm === vm);
+  const ground = {
+    checked: [`every backup job in the export of ${exportedAt}`],
+    cannotCover: [{ what: 'PPDM', why: 'not collected on this install' }],
+  };
+  // "I looked and there is nothing" — never readable as "I could not look".
+  if (runs.length === 0) return absent({ what: `backup runs for ${vm}`, ...ground });
+  // A verdict WITH its boundary — what "fine" does and does not rule out.
+  if (summary) return coverage(`${vm}: ${runs.length} backup runs`, ground);
+  // Rows WITH their caveats. measuredAt comes from the data (the export's time,
+  // the moment of a live read, the newest sample) — never a typed-in date.
+  return describedResult({
+    facts: runs.map((r) => ({ entity: vm, day: r.day, ok: r.ok === 1 })),
+    provenance: { measuredAt: exportedAt, source },
+    coverage: ground,
+  });
+},
 ```
 
-An absence gets the delivered status `'absent'` (route it with
-`onToolStatus: 'absent'`), files `agentfootprint.tools.absent`, and grounds only
-its COVERAGE in the evidence gate — so an id the model invented does not become
-grounded by one lookup that found nothing. It is never an error: nothing retries
-it, nothing refuses it, no `error: true`. A ledger files
-`agentfootprint.tools.coverage_declared`; add `.limitsTravelWithTheAnswer()` on
-the agent and the framework APPENDS the run's limits to the final answer, so the
-model cannot drop what it never wrote.
+`describedResult()` is camelCase throughout (`measuredAt`, `ageSeconds`, `isCounter`,
+`filterNote`); the envelope the model reads stays snake_case. Series need `grain`
+(`{ interval, aggregation, isCounter }` — state `isCounter` for `sum`/`count`-like
+aggregations); series or facts without `provenance` are a compile error and a run-time
+refusal. `semantic()` is the deprecated name for the same envelope with a snake_case
+declaration — do not use it in new code.
+
+A helper that cannot honor its declaration throws inside `execute`: the model reads text
+starting `refused: ` in place of the data, and the run continues. An absence gets the
+delivered status `'absent'` (route it with `onToolStatus: 'absent'`) and grounds only its
+COVERAGE in the evidence gate — so an id the model invented does not become grounded by one
+lookup that found nothing. It is never an error: nothing retries it, nothing refuses it, no
+`error: true`. Add `.limitsTravelWithTheAnswer()` on the agent and the framework APPENDS the
+run's declared coverage to the final answer string (not to streamed tokens; it breaks
+`runTyped()`'s JSON), so the model cannot drop what it never wrote.
 
 ## Observing a run
 

package/CAPABILITIES.md

@@ -25,7 +25,8 @@ not in this table, search `src/index.ts` for the nearest noun before writing cod
 | turning a written operational procedure (a runbook, a triage playbook) into ONE agent tool whose every answer is EVIDENCE — coverage folded up from the inner tools it calls, rule name+version, verdict rows with GENERATED meanings, and the recorded walk as an artifact ticket, never bytes | `runbookAsTool` — dials: `procedure` (factory, invoked per call with `ctx.tools`) + `resultKind` (`'verdict/*'` arms the rowset projection; anything else ships spine + the chart's `report`) + `rules {name, version}` (default absent ⇒ `rule_version: 'undeclared'`) + `verdicts {decider, maxRows}` (default 50; `verdict_meanings` = statically declared branches + this run's rule labels + the DEFAULT branch's label, which reaches evidence only when the chart calls `decide(s, rules, {branch, label})` — fp ≥9.16.1, the default is chosen by NO rule so nothing else can name it, and inside a generated fan-out branch the static walk is blind too; an undeclared or blank label stays ABSENT from the map, never invented from a branch id, and there is deliberately NO caller-supplied meanings map) + `presentation` (`'prose'` default = ship `table` + `VERDICT_RENDER_NOTE` "output it VERBATIM"; `'panel'` = the HOST renders the rowset, so NO `table` key at all + `PANEL_RENDER_NOTE` "the rows are already on the reader's screen — do not reproduce them"; the rowset half is byte-identical across modes, `table` stays RESERVED in both, an unknown value THROWS at definition) + `walk {cap, recording}` (cap default 500; over-cap ⇒ control-flow projection, declared · `recording: true` or `{label, maxBytes}`, default OFF — ALSO files the inner chart's own `{snapshot, events, structure}` under `recording/run` and puts its ref on the spine as `walk.recording_ref`, because the ROW projection cannot be drawn; snapshot read from the REDACTED mirror so one `redact` means the same for both; over `maxBytes` (`DEFAULT_RECORDING_MAX_BYTES` = 5,000,000) it is REFUSED not truncated; every absence — no store / over size / unserializable / store threw — is STATED in `walk.recording_note`, and the four `recording_*` fields are absent entirely when the dial is off) + `composedOf` (drift-checked at agent BUILD) + kept `recorders`/`keepRecord`/`keepRecordLimit`/`redact`; reserved state keys `verdicts`/`coverage`/`report` (the `report` bag lands BESIDE the spine, never over it — a report field spelling `af_coverage`/`af_provenance`/`rule_version`/`walk`/`report_note` or a live projection key is discarded and NAMED in `result.report_note`; precedence is explicit in `report.ts`, never spread order); inner `absent()` passes through VERBATIM unless the call said `allowAbsent`; walk kind `recording/chart-walk` + `walk_segment` discriminant | `src/core/runbook/` | 9.76.0, recording 9.79.0 |
 | speaking MCP from a BROWSER — the SDK is browser-clean (its client + streamableHttp bundle at `platform:'browser'` with zero `node:` edges and never pull in `client/stdio.js`); the one barrier was that `lazyRequire` gets CALLED there, so the fix is to let the caller supply what the loader would have found | `mcpClient({ sdk })` (`McpSdk` = the two SDK modules you imported statically; the library STILL builds the transport, so headers/fetch/gateway vending/`retryOnThrottle`/`_meta` all keep working) · `mcpClient({ connection })` (`McpConnection` = listTools/callTool/close, deliberately NO `connect` — you already did; the only arm that reaches the SDK's `jsonSchemaValidator`, i.e. CSP) + `McpConnectionOptions`; `refuseConflictingOptions` REFUSES at construction every option a transport would have consumed, naming where it moved (a knob naming a behaviour that no longer happens is the defect class); `transportUrl` resolves a relative `url` against `globalThis.location.href` (absolute takes the identical branch, Node refuses by name); `sdkLoadFailure` classifies the seven load sites so a browser is never told to install a package it has (resolution failure ⇒ byte-identical historical message); `retryingFetch` + `ThrottleFetch` promoted out of `@internal` so the connection arm keeps its 429 handling. stdio keeps `lazyRequire` FOREVER — it spawns a subprocess. ZERO packaging change: no subpath, no `browser` condition (TypeScript is blind to it), peer stays optional (no literal dynamic `import()`). Fenced by `test/lib/mcp/browserGraph.test.ts` | `src/lib/mcp/` | 9.81.0 |
 | calling ANOTHER registered tool from inside a tool's `execute` — composition over the agent's own dispatch map instead of importing the module and building a second query stack | `agentToolDispatch` + `ctx.tools` (ToolDispatch has/call) — sees static and skill-carried tools, NEVER ToolProvider-delivered ones (no build-time list, the 9.72.0 caveat); inner calls get the outer facts with hasArtifacts false and a derived toolCallId, `needs` resolved fail-closed non-interactively, `checkIn` and `wants` tools refused by name, no nested dispatch; declare ingredients via `composedOf` (and `gates` for a pausing procedure) — both travel MCP `_meta` | `src/core/agent/toolDispatch.ts` | 9.76.0 |
-| a tool returning numbers WITH the caveats that make them honest — interval/aggregation grain, is-it-a-counter, when the world was measured, which ground was NOT covered — as typed data the model reads compactly and the record keeps whole | `semantic()` + `tools.semantics_declared` (model sees `semanticsForModel` projection; `coverage` field absorbed by the coverage()/absent() channel) | `src/lib/semantics/` | 9.53.0 |
+| a tool returning numbers WITH the caveats that make them honest — interval/aggregation grain, is-it-a-counter, when the world was measured, which ground was NOT covered — as typed data the model reads compactly and the record keeps whole | `semantic()` + `tools.semantics_declared` (model sees `semanticsForModel` projection; `coverage` field absorbed by the coverage()/absent() channel; `semantic()` is the deprecated name — use `describedResult()`, next row) | `src/lib/semantics/` | 9.53.0 |
+| the same typed tool result declared in ONE spelling — camelCase `measuredAt`/`isCounter`/`filterNote`, respelled to the unchanged snake_case wire — with a missing source a COMPILE error; which result helper to return (rows → describedResult, a value with limits → coverage, nothing → absent) | `describedResult()` + `DescribedResultDeclaration` (`provenance` required whenever `series`/`facts` is present; the snake_case spelling refused, naming the camelCase one) | `src/lib/semantics/described.ts` | 9.119.0 |
 | a build gate that refuses a triage/inventory tool that forgot its caveats, by tool name and field name | `checkSemantics` + `defineTool({ resultClass })` (`'triage'`/`'inventory'`, the closed set) + bin `agentfootprint-check-semantics` | `src/lib/semantics/check.ts` | 9.53.0 |
 | an agent that runs out of `maxIterations` mid-task handing back a HALF-SENTENCE as its answer — and nothing saying the budget ran out | `wrapUpAtMaxIterations` (default ON) + `WRAP_UP_INSTRUCTION` + `agent.budget_exhausted` + `stoppedEarly.wrappedUp` | `src/core/agent/stages/wrapUp.ts` | 9.56.0 |
 | the conversation outgrowing the context window — dropping, summarizing or token-budgeting old turns, every removal on the record (the three refusal rows below all guard this window) | `.window()` + `slidingWindow` / `summarizeOldest` (= `.compaction()`) / `tokenBudget` + `keepRecentTurns` (default 6) + `thresholdTokens` (required, deliberately no default) + `retain: 'conversation'` (default) / `'discard'` | `src/core/agent/window/` | 7.17.0 |
@@ -67,6 +68,7 @@ not in this table, search `src/index.ts` for the nearest noun before writing cod
 | a skill's plain name for a person ("array estate report" for `array-inventory`) on the recording, without changing what the model reads or what a graph draws — at most 60 chars, one line of plain visible text, not the id; carried as `skill.graph_declared` `nodes[].title` on a skill-graph agent, absent when not declared | `defineSkill` + `title` | `src/lib/injection-engine/factories/defineSkill.ts` | 9.116.0 |
 | how many of an answer's values the evidence check actually LOOKED UP — `candidates` also counts values the person's message or the app's instructions already held, which are never looked up; found plus not found, before the 12-value slice, on every `evidence_checked` | `lookedUp` + `EvidenceVerdict` | `src/core/agent/evidence/` | 9.116.0 |
 | explaining ONE answer to a person in plain words — what was asked, how it was routed, what each tool checked and did not check, what it found, how sure, and anything wrong — every line from the record by a fixed versioned template (never a model), each with its template id and who vouches for it (person / library / tool / model / app), "not recorded" instead of a guess, own-run events only, three checks with the ones that could not run said aloud | `accountForAnswer` + `AnswerAccount` | `src/lib/answer-account/` | 9.116.0 |
+| how far an answer STANDS — known · consistent with the record · not sure (with the reasons) · ask · not assessed — folded from the run's COMMITTED record (never from the model's confidence, never from events, never "known" from silence: only a passed enforce answer check supports it); each reason names the row it rests on, `checked` counts what ran, this turn only; a pause of any kind reads `ask` from the recording alone, a run with no answer has no standing; one emptiness reader shared with the answer account (`coverage/emptiness.ts`: a `coverage()` envelope read through, a described result counted, an undeclared empty rowset said aloud) | `assessAnswer` + `AnswerAssessment` (on the observe door), `agent.assessment()` | `src/core/agent/assessment/` | 9.120.0 |
 | serving that explanation to a browser without the recording: one opt-in wire op returns the account plus allow-listed "show me" leaves, owner-only on the `artifact-get` path, lane-free, cached and single-flight, a stated size ceiling, and a swept record answering "not available" even when cached | `standingAgent({ answerAccounts })` + `{ op: 'answer-account', ref }` + `answerAccountPointerKey` | `src/hosting/answerAccounts.ts` | 9.116.0 |
 | bounding what one session can ask of the artifact door at once: `artifact-head`, `artifact-get` and `answer-account` counted together per session, after the ownership check, refused 429 by name while every other session is served | `standingAgent({ artifactOpsPerSession })` + `ArtifactOpsBusyError` | `src/hosting/standingAgent.ts` | 9.116.0 |
 | minting one of those shapes from a tool that is NOT JavaScript — the canonical note sentences and reserved marker keys as DATA, so a Python/Go/Rust sidecar reads a file instead of regex-scraping `dist/esm` (which a consumer really did) | `canonical-notes.json` at the package root + the `./canonical-notes.json` exports entry, GENERATED from the built barrel by `scripts/gen-canonical-notes.mjs` | `scripts/gen-canonical-notes.mjs` | 9.70.0 |

package/README.md

@@ -107,6 +107,37 @@ For production, import a real provider from `agentfootprint/providers` and swap
 
 **No cloud account?** `ollama('llama3.2')` from `agentfootprint/providers` runs the same agent against a local model for $0 — the free rung between the mock and the bill. Full recipes: [Ollama](https://agentfootprint.dev/docs/build/ollama/) · [OpenAI-compatible endpoints](https://agentfootprint.dev/docs/build/openai/#openai-compatible-endpoints-ollama-llamacpp-vllm-together-groq-lm-studio).
 
+## What a tool returns — three helpers, one rule
+
+Whatever a tool returns is what the model reads next. When that value has limits the model must not lose, return it through one of three helpers — each is the tool's response; nothing is added to the system prompt or the tool's schema:
+
+| helper | use it when | the model reads | the record keeps |
+|---|---|---|---|
+| `describedResult({ … })` | rows, a series or relationships from a system of record | the data, with `grain`, `provenance` and one `not_covered` line per gap | the whole envelope (`tools.semantics_declared`) |
+| `coverage(value, { … })` | any other value that has limits | your value, with what was and was not checked | `tools.coverage_declared` |
+| `absent({ … })` | nothing matched | what was looked for, where, and that a retry returns the same | `tools.absent` |
+
+Never wrap one in another. Add `.limitsTravelWithTheAnswer()` and the declared coverage is appended to the final answer — provenance and grain never are.
+
+```typescript
+import { absent, coverage, describedResult } from 'agentfootprint';
+
+execute: ({ vm, summary }) => {
+  const { exportedAt, source, runs: all } = backupExport;   // your system of record
+  const runs = all.filter((r) => r.vm === vm);
+  const ground = { checked: [`every backup job in the export of ${exportedAt}`] };
+  if (runs.length === 0) return absent({ what: `backup runs for ${vm}`, ...ground });  // nothing matched
+  if (summary) return coverage(`${vm}: ${runs.length} backup runs`, ground);           // a verdict with limits
+  return describedResult({                                                             // rows from the record
+    facts: runs.map((r) => ({ entity: vm, day: r.day, ok: r.ok === 1 })),
+    provenance: { measuredAt: exportedAt, source },   // the time comes from the data
+    coverage: ground,
+  });
+},
+```
+
+What the model reads from each, exactly: [Tools → what `execute` returns](https://agentfootprint.dev/docs/build/tools/#what-execute-returns--three-helpers-one-rule).
+
 ## How — we abstract context engineering
 
 Skills, steering, RAG, facts, memory, guardrails — every name for context does one thing: it injects into one of three LLM slots. So we abstracted the injection itself.

package/ai-instructions/claude-code/SKILL.md

@@ -210,35 +210,57 @@ the model — the framework stamps `toolCallId` / `toolName` / `iteration`, you
 `payload`. `agent.on('agentfootprint.stream.*')` and `toSSE(agent)` carry it with
 no extra wiring.
 
-### When a tool finds nothing, and what a clean result does not cover
+### What a tool returns: rows, a verdict with limits, or nothing
+
+| helper | use it when | the model reads | the record keeps |
+|---|---|---|---|
+| `describedResult({ … })` | rows, a series or relationships from a system of record — or a question back (`clarify`) | data + `grain` + `provenance` + one `not_covered` line per gap + a static note — NOT the `checked` list | the whole envelope on `tools.semantics_declared`, coverage in `coverageDeclared` |
+| `coverage(value, { … })` | any other value that has limits (a verdict, a sentence) | your value under `result`, the coverage lists under `af_coverage` | `tools.coverage_declared`, `coverageDeclared` |
+| `absent({ … })` | nothing matched | what was looked for, the coverage, "a retry returns the same" | `tools.absent`, `coverageDeclared`, status `'absent'` |
+
+The rule: rows from a system of record → `describedResult()`; any other value with limits →
+`coverage()`; nothing matched → `absent()`. Never wrap one in another. All three are the tool's
+RESPONSE — nothing goes into the system prompt or the tool schema.
 
 ```typescript
-import { absent, coverage, defineTool } from 'agentfootprint';
-
-// "I looked and there is nothing" — never readable as "I could not look".
-execute: ({ port }) => rows.length ? rows : absent({
-  what: `FLOGI entries on ${port}`,
-  checked: ['shq-fab-a: the live fcns database', 'window: the last 24h'],
-  notChecked: [{ what: 'the archived history', why: 'older than the 24h window' }],
-  cannotCover: [{ what: 'the peer fabric', why: 'this collector is scoped to one fabric' }],
-  tryInstead: 'Ask for a different interface, or query the peer fabric by name.',
-}),
-
-// A verdict WITH its boundary — what "fine" does and does not rule out.
-execute: async () => coverage(await checkReplication(), {
-  checked: ['SRDF pair state on all 4 arrays'],
-  cannotCover: [{ what: 'host-side multipathing', why: 'no collector on the ESX hosts' }],
-}),
+import { absent, coverage, defineTool, describedResult } from 'agentfootprint';
+
+execute: ({ vm, summary }) => {
+  const { exportedAt, source, runs: all } = backupExport;   // the system of record
+  const runs = all.filter((r) => r.vm === vm);
+  const ground = {
+    checked: [`every backup job in the export of ${exportedAt}`],
+    cannotCover: [{ what: 'PPDM', why: 'not collected on this install' }],
+  };
+  // "I looked and there is nothing" — never readable as "I could not look".
+  if (runs.length === 0) return absent({ what: `backup runs for ${vm}`, ...ground });
+  // A verdict WITH its boundary — what "fine" does and does not rule out.
+  if (summary) return coverage(`${vm}: ${runs.length} backup runs`, ground);
+  // Rows WITH their caveats. measuredAt comes from the data (the export's time,
+  // the moment of a live read, the newest sample) — never a typed-in date.
+  return describedResult({
+    facts: runs.map((r) => ({ entity: vm, day: r.day, ok: r.ok === 1 })),
+    provenance: { measuredAt: exportedAt, source },
+    coverage: ground,
+  });
+},
 ```
 
-An absence gets the delivered status `'absent'` (route it with
-`onToolStatus: 'absent'`), files `agentfootprint.tools.absent`, and grounds only
-its COVERAGE in the evidence gate — so an id the model invented does not become
-grounded by one lookup that found nothing. It is never an error: nothing retries
-it, nothing refuses it, no `error: true`. A ledger files
-`agentfootprint.tools.coverage_declared`; add `.limitsTravelWithTheAnswer()` on
-the agent and the framework APPENDS the run's limits to the final answer, so the
-model cannot drop what it never wrote.
+`describedResult()` is camelCase throughout (`measuredAt`, `ageSeconds`, `isCounter`,
+`filterNote`); the envelope the model reads stays snake_case. Series need `grain`
+(`{ interval, aggregation, isCounter }` — state `isCounter` for `sum`/`count`-like
+aggregations); series or facts without `provenance` are a compile error and a run-time
+refusal. `semantic()` is the deprecated name for the same envelope with a snake_case
+declaration — do not use it in new code.
+
+A helper that cannot honor its declaration throws inside `execute`: the model reads text
+starting `refused: ` in place of the data, and the run continues. An absence gets the
+delivered status `'absent'` (route it with `onToolStatus: 'absent'`) and grounds only its
+COVERAGE in the evidence gate — so an id the model invented does not become grounded by one
+lookup that found nothing. It is never an error: nothing retries it, nothing refuses it, no
+`error: true`. Add `.limitsTravelWithTheAnswer()` on the agent and the framework APPENDS the
+run's declared coverage to the final answer string (not to streamed tokens; it breaks
+`runTyped()`'s JSON), so the model cannot drop what it never wrote.
 
 ## Observing a run
 

package/dist/core/Agent.js

@@ -14,6 +14,29 @@
  *            agentfootprint.stream.tool_start / tool_end
  *            agentfootprint.context.* (via ContextRecorder)
  */
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || function (mod) {
+    if (mod && mod.__esModule) return mod;
+    var result = {};
+    if (mod != null) for (var k in mod) if (k !== "default" && Object.prototype.hasOwnProperty.call(mod, k)) __createBinding(result, mod, k);
+    __setModuleDefault(result, mod);
+    return result;
+};
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.Agent = exports.AgentBuilder = void 0;
 const footprintjs_1 = require("footprintjs");
@@ -3165,6 +3188,50 @@ class Agent extends RunnerBase_js_1.RunnerBase {
             ?.answerValidation;
         return report === undefined ? undefined : structuredClone(report);
     }
+    /**
+     * How far the last run's answer stands — folded from its COMMITTED record,
+     * never from how sure the model sounded: `known` · `consistent` (checks ran,
+     * none fired — never "verified") · `not-sure` (with the reasons) · `ask` (the
+     * run paused on a question still waiting for a person) · `not-assessed`
+     * (nothing on the record could be checked).
+     *
+     * The same pure fold as `assessAnswer` on `agentfootprint/observe`, over this
+     * agent's last snapshot; it reads committed state, never events, so a later
+     * reader of the same recording folds the same standing. It resolves
+     * asynchronously because the fold is loaded through `import()` on first use —
+     * an agent that never asks does not carry it.
+     *
+     * Resolves to `undefined` when there is no answer to assess: before the first
+     * run, while a run is in flight, and after a run that threw or whose answer a
+     * rule refused (the typed error carries that verdict).
+     *
+     * `declarations` is the answer account's object, accepted as it is: the fold
+     * reads `tools[name].rowsAt`, where an object result keeps its rows.
+     *
+     * @example
+     * ```ts
+     * await agent.run({ message: 'Which ports on switch A are down?' });
+     * const a = await agent.assessment();
+     * if (a?.standing === 'not-sure') {
+     *   for (const r of a.reasons) console.log(r.reason); // e.g. 'empty-undeclared'
+     * }
+     * ```
+     */
+    async assessment(declarations) {
+        const snapshot = this.getLastSnapshot();
+        if (snapshot === undefined)
+            return undefined;
+        // Settled before the fold, which cannot tell a crash from its committed state: an answer
+        // this run RETURNED (`lastRunAnswer`, cleared at every run's start), or a pause — the fold
+        // reads that one from the committed state itself. Read BEFORE the import resolves, so a
+        // run started meanwhile cannot change which run is assessed.
+        const paused = this.lastExecutor?.isPaused() === true;
+        if (!paused && this.lastRunAnswer === undefined)
+            return undefined;
+        // Loaded on first use, off the default graph (the findings/peel.ts precedent).
+        const { assessAnswer } = await Promise.resolve().then(() => __importStar(require('./agent/assessment/assess.js')));
+        return assessAnswer({ snapshot }, declarations);
+    }
     finalizeResult(executor, result) {
         const paused = this.detectPause(executor, result);
         if (paused)