agentfootprint 10.10.0 → 11.0.0

package/AGENTS.md

@@ -286,7 +286,7 @@ const agent = Agent.create({ provider, model })
 agent.on('agentfootprint.context.evaluated', (e) => console.log(e.payload.activeIds));
 ```
 
-**124 typed events across 27 domains.** Two subscription shapes and no third:
+**125 typed events across 27 domains.** Two subscription shapes and no third:
 `'*'` (every event) and `'agentfootprint.<domain>.*'` (one domain). **`'agentfootprint.*'`
 is not a pattern** — TypeScript rejects it, and at runtime it would match nothing.
 
@@ -300,14 +300,24 @@ agent.on('agentfootprint.agent.turn_end', (e) =>
 ## Human in the loop
 
 ```typescript
-import { askHuman, isPaused, checkInApproved } from 'agentfootprint';
+import { isCheckInPause, checkInApproved } from 'agentfootprint';
 
 const result = await agent.run({ message: 'Refund $500?' });
-if (isPaused(result)) {
-  const final = await agent.resume(result.checkpoint, checkInApproved({ by: 'maya' }));
+if (isCheckInPause(result)) {
+  // The decision names the request it answers: once, for exactly the call shown.
+  const final = await agent.resume(
+    result.checkpoint,
+    checkInApproved({ request: result.checkIn, by: 'maya' }),
+  );
 }
 ```
 
+A decision for another pause, for a checkpoint whose call changed, or a second
+resume with the same decision throws `ResumeDecisionError` — the tool never runs.
+"Once" holds per ledger: agents in one process share one by default; when more
+than one process can resume a paused run, give them one shared store via
+`Agent.create({ decisionLedger })`.
+
 ## Resilience
 
 ```typescript

package/CAPABILITIES.md

@@ -31,7 +31,8 @@ not in this table, search `src/index.ts` for the nearest noun before writing cod
 | serving agents to AG-UI frontends (CopilotKit, the AG-UI Dojo, an `@ag-ui/client` app) from any framework with no glue code — POST a `RunAgentInput`, stream AG-UI events back; the request is untrusted browser input: only the newest user message is conversation (the page's copy is never read), a system/developer message refused, an answer taken only for the pause the server keeps, frontend tools only by the app's name allow-list with its own contract (they run in the page, no server privilege), `state`/`context` only through the app's validators, no identity/credential/redaction from a request; a fresh runner per request, the thread bound to the caller the app authenticates, the conversation and paused runs kept server-side, one turn per thread, door guard, body ceiling, SSE keep-alive | `streamHandler` + `ProtocolAdapter` + `verifiedThreads` (`agentfootprint/hosting`) + `agUi` (`agentfootprint/ag-ui`) | `src/hosting/streamHandler.ts` | 10.4.0 |
 | serving an agent behind a GATEWAY that speaks AG-UI in its own request body and its own output envelope (`{"eventType":"…Event","event":{…,"eventSequence":n}}`) — `agUi()` as three replaceable strategies: a reader (the gateway's body → the turn), the translation (AG-UI vocabulary, unchanged) and the framing (the envelope; each frame's number in its own stream handed in by the host, never a shared counter); every untrusted-input rule stays in the core whichever reader ran (shape and ids, no system/developer message, frontend tools by allow-list, state/context by validators, answers only for the kept pause; each value read once) | `agUi({ reader, translation, framing })` + `AgUiRequestReader` / `AgUiTurnRequest` / `AgUiTranslationStrategy` (`agentfootprint/ag-ui`), `SseFraming.frame(event, { sequence })` + `SseFramePosition` (`agentfootprint/observe`) | `src/ag-ui/adapter.ts` | 10.5.0 |
 | checking forced tool choice per model without changing the existing boolean wire declaration; explicit requests refuse before transport, classifiers keep their strict parse alternative, wrappers preserve and fallback pairs intersect | `LLMProvider.supportsForcedToolChoice` + `forcedToolChoiceFor` + `UnsupportedToolChoiceError` (`agentfootprint/providers`) | `src/provider-contract/forcedToolChoice.ts` | 10.1.0 |
-| a typed answer constrained by the PROVIDER'S OWN structured output instead of asked for in prose — the schema sent as Anthropic's `output_config.format`, the agent keeping its tools; one function builds the API-compatible wire copy (objects closed, unsupported constraints moved into the description, recursion / external `$ref` / complex enums / open values / open-keyed maps refused at build by node), the parser still judges; per-model capability with unknown ids read as the newest generation, refused by name at run start and before transport; a `'refusal'` / `'max_tokens'` stop fails the attempt by name even when it parses; `_findings` allowed on the format when the ledger is armed | `.outputSchema(parser, { strategy: 'native', jsonSchema })` + `LLMProvider.carriesNativeOutputSchema` / `supportsNativeOutputSchema` + `nativeOutputSchemaFor` + `UnsupportedNativeOutputError` (`agentfootprint/providers`) + `answerGuarantee: 'native'` + `OutputAttempt.stopReason` | `src/provider-contract/nativeOutputSchema.ts` | 10.3.0 |
+| a typed answer constrained by the PROVIDER'S OWN structured output instead of asked for in prose — the schema sent as Anthropic's `output_config.format`, the agent keeping its tools; one function builds the API-compatible wire copy (objects closed, unsupported constraints moved into the description, recursion / external `$ref` / complex enums / open values / open-keyed maps refused at build by node), the parser still judges; explicit-native per-model capability with unknown ids read as the newest generation, refused by name at run start and before transport; a `'refusal'` / `'max_tokens'` stop fails the attempt by name even when it parses; `_findings` allowed on the format when the ledger is armed | `.outputSchema(parser, { strategy: 'native', jsonSchema })` + `LLMProvider.carriesNativeOutputSchema` / `supportsNativeOutputSchema` + `nativeOutputSchemaFor` + `UnsupportedNativeOutputError` (`agentfootprint/providers`) + `answerGuarantee: 'native'` + `OutputAttempt.stopReason` | `src/provider-contract/nativeOutputSchema.ts` | 10.3.0 |
+| choosing native structured output automatically only for positively known supported models (`supportsAutoNativeOutputSchema`) when a safely lowered JSON Schema is available; otherwise keeping instruction plus local validation, with an accurate format guarantee; accepting exactly one whole-answer JSON or unlabelled code fence before the unchanged JSON/schema parser | `.outputSchema(parser, { strategy: 'auto', jsonSchema? })` (default) + `agent.parseOutput` / `runTyped` | `src/core/agent/AgentBuilder.ts` | 11.0.0 |
 | replaying Anthropic thinking in its original content order; refusing known unsafe active-tool replay, observing each permitted completed-turn omission before sending, and retaining that decision across checkpoints | `LLMMessage.replay` + `UnsafeThinkingReplayError` + `LLMCallHooks.onReplayPrepared` + `agentfootprint.agent.thinking_omitted` | `src/adapters/llm/anthropicThinkingReplay.ts` | 10.1.0 |
 | keeping personal data out of an agent's saved records — snapshot, narrative, every event, recordings, bug reports, answer accounts, the exporters — while the model, the tools and the caller keep the real values; the library's own list of the names the conversation travels under (proven per feature), joined with the fields your tools name; it reaches compositions (members' policies adopted) and runs a tool starts (`ctx.redact`), and readers of the record say "kept out", never "not recorded" or "no tool ran" | `Agent.create({ redact })` (a footprintjs `RedactionPolicy`) + `conversationRedaction` + `ToolExecutionContext.redact` | `src/redaction/` | 9.140.0 |
 | prompt caching that keeps hitting behind `withRetry`, `withFallback` or your own provider wrapper — the cache strategy chosen from what the adapter DECLARES (explicit breakpoints / automatic / none), never from its name, plus a moving breakpoint on the conversation tail so each call reads back what the last one sent | `LLMProvider.promptCaching` (`PromptCaching`) + `cacheStrategyFor` + `BreakpointCacheStrategy` / `AutomaticCacheStrategy` / `NoOpCacheStrategy` | `src/cache/cacheStrategyFor.ts` | 9.138.0 |
@@ -45,6 +46,7 @@ not in this table, search `src/index.ts` for the nearest noun before writing cod
 | identifying which same-name tool call a permission check or credential event describes — captured at dispatch, including resume and inner pull failures; qualify with run identity, missing fields stay unknown | `ToolCallEventIdentity` + `bindToolSecurityEvents` | `src/core/agent/toolSecurityEvents.ts` | 9.137.0 |
 | guiding an evidence repair to ask for missing context without inventing values | `recoveryInstruction` + `EvidenceRecoveryContext` | `src/core/agent/evidence/` | 9.96.0 |
 | checking a typed final answer against scoped evidence before streaming or memory delivery — optional host-authored checks with enforce/observe modes, canonical JSON and bounded read-only artifacts | `answerValidation` + `AnswerValidationError` | `src/answer-validation/` | 9.95.0 |
+| an answer the agent's own checks flagged still being DELIVERED — a typed field that contradicts the fact a tool settled (`.claims()`) or a value no tool result carried (`.namesAndNumbersFromEvidence()`) withheld instead of only recorded: each listed check is a row of the enforcing answer validation, judged on the exact JSON delivered after any output transform (draft tokens held, `AnswerValidationError` on refusal, recorded only under `mode: 'observe'`), after the gate's one repair turn under `'guard'` (served no tools while the validation enforces, so a tool that writes or sends never runs twice); claims compare after a declared normalization (text in NFC, trimmed, case agreeing only between the same letters in another case in a word of more than three letters — `ß` never `ss`, and a rule that cannot know where case carries meaning, so `Polish` agrees with `polish`; a number and a plain decimal string by value; a unit exactly; a currency, separators, a dot-grouped number, a date or a time only as written), so a different spelling — an accent dropped included — is never a contradiction; a reading can only withhold — a field contradicting any value read fails its row, and readings that differ where the field contradicts none, a reading that settled only doubt beside a stated value, values that cannot be compared safely (a list with a hole included), a malformed `Claim`, or a doubt agreeing with a tool's doubt is `unreachable` and withheld; an agreeing claim, a fact no tool settled and a clean gate pass are `not-applicable` — the agent's rows withhold and never verify, so only the app's own checks pass a report; rows carry declared names and counts, never values; opt-in, defaults unchanged | `answerValidation({ agentChecks })` + `AgentCheckName` | `src/answer-validation/` | 11.0.0 |
 | blocking a declared claim when its required relationship evidence is missing or unresolved, while independently checked measurements remain usable — host-owned policies over Foottrace requirement records, composed with output middleware and enforcing answer validation | `checkClaimRequirements` + `ClaimRequirementPolicy` + `ClaimRequirementAssessment` | `src/answer-validation/requirements.ts` | 10.6.0 |
 | an output guard that sees which tools ran — fail the run when the answer presents code but no code-execution tool ran; this run's tool calls (name, call id, outcome ok/error/not-run; never arguments or results) handed to the enforce check, per run, bounded | `AnswerValidationContext.toolCalls` + `AnswerToolCallsView` + `limits.maxToolCalls` | `src/answer-validation/toolLedger.ts` | 10.5.0 |
 | 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 |
@@ -103,9 +105,16 @@ not in this table, search `src/index.ts` for the nearest noun before writing cod
 | a lookup tool that answers "nothing found" for EVERY id because a filter broke, and an agent reporting that absence as fact — the run itself produced the id, the lookup came back empty, and that PAIR is worth a look | `noticeEmptyLookups` + `readLookupResult` + `EMPTY_LOOKUP_CEILING` (dial default OFF and needs a tool declaring `argumentsFrom` too — two halves; kind `empty-lookup` at seam `write`, always `advisory: true`; empty = a zero-length ARRAY or an `absent()` envelope, every other shape files `not-applicable` and no finding; the ceiling is quoted verbatim into every message) | `src/integrity/empty-lookup/` | 9.77.0 |
 | an agent answering a NEW question out of an OLD turn's tool results — grounded, four turns stale, and the evidence gate approving it (`Tool calls 0` and "all 7 values were found in what the tools returned"). ALSO the bug half: the gate's two sentences claimed the flagged values "appear in no tool result FROM THIS TURN" while its index walked every `role:'tool'` turn — a boundary asserted and never measured; both now say "no tool result this run read" | `noticePriorTurnEvidence` + `PRIOR_TURN_EVIDENCE_CEILING` + `priorTurnEvidenceOf` + `AnswerGroundingReading` (dial default OFF and needs `.namesAndNumbersFromEvidence()` too — two halves, and the second is structural: the gate owns the extractor that decides which tokens are values; kind `prior-turn-evidence` at seam `claim`, always `advisory: true`; `EvidenceCorpus.values` became a `Map<form, turn>` stamped in the walk that was already happening, a TURN = each `role:'user'` message `isLibraryAuthoredTurn` did NOT write (counting the gate's own correction would file against every revised answer); fires when ≥1 value is grounded and NOT ONE came from the turn being answered — ONE current-turn value files nothing, which is what keeps an honest follow-up quiet and is the design's falsification test; the zero-tool-call turn is the SAME kind with a stronger witness, not a second kind; corpus is the LIVE WINDOW so ordinals are window-relative and the distance is a FLOOR, while the boundary stays exact (`'current-request'` is un-droppable); memory/RAG values are exempt from grounding and invisible — it can under-report, never over-report; the ceiling is quoted verbatim into every message) | `src/integrity/prior-turn-evidence/` | 9.83.0 |
 | a tool's ROWS quietly disagreeing with what the tool promised — a LUN 0 stored as `""` because it is falsy, a numeric column arriving as quoted strings, a declared column present in no row at all | `Tool.resultColumns` + `checkColumnTypes` + `COLUMN_TYPE_CEILING` + `readRowset` (dial `'off'` (default) / `'warn'` (file findings, model reads the rows unchanged) / `'enforce'` (refuse the rows, `resultCeiling`'s teaching-sentence idiom, delivered status `'invalid'`) — the `toolArgsValidation` trio, this seam's mirror; needs a tool declaring `resultColumns` too — two halves; types `number`/`string`/`boolean`/`date`, bare word or `{type, nullable}`, deliberately NO `'unknown'`; OPEN — unlisted columns allowed and unjudged; TWO kinds at seam `write` — `column-type-mismatch` (there, wrong type) vs `missing-column` (declared, in no row); rowset = an ARRAY OF PLAIN OBJECTS with ≥1 row, everything else incl. the ZERO-ROW result files `not-applicable` (empty is `empty-lookup`'s subject); travels MCP `_meta`; the ceiling is quoted verbatim into every message) | `src/integrity/column-types/` | 9.78.0 |
+| verifying the model-selected negative kind against cited native reads, normalizing only none/not-found over declared absence; optional subject phrases must include the recorded populations, and delivered subjects come from the searches; complete requires an explicit claim and completeness evidence, with visible absence-only fallback when it fails                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                         | `.negativeClaims({ field, tools })` + `NegativeClaimCitation`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                               | `src/core/agent/negativeClaims/`                        | 11.0.0                          |
+| observing data-anchored negative prose without an output schema, citation field or answer validator; native read evidence only, unchanged delivery and normal streaming, no correction or withholding. An eligible grammar match with no dispatched native read recorded for the current turn files one no-read note per answer; earlier-turn reads do not suppress it, but recorded failed or kept-out reads do. This presence check proves neither that no read occurred nor that evidence is usable. The observer filters exact normalized ordinary clauses None / No action is needed / Tests: 0 failed; added words or separate negative clauses remain eligible. Current-turn findings make the assessment not-sure; no finding never means verified. Bounded English heuristic with code/language/limit notes and optional literal phrase extensions; prior detector failed every free-replay benchmark gate, revised data-anchored path remains unmeasured. App validation stays independent; prose-only plus outputFallback is refused | `.negativeClaims({ prose: true, phrases? })` + `NegativeClaimsOptions` + `agent.findings()` + `agentfootprint.findings.negative_claim` (bounded locations, codes, phrase version and native references; no answer text or tool values) | `src/core/agent/negativeClaims/` | 11.0.0 |
+| deriving a typed negative's kind and searched subject from the cited native records; model supplies only result handles, legacy kind/about never steer checks, and advisory display text remains unchecked; other searches are compared using recorded populations | `.negativeClaims({ field, tools })` + `NegativeClaimCitation` | `src/core/agent/negativeClaims/` | 11.0.0 |
+| checking an agent's "there are none", "not found" or "that is the full list" against what its searches were actually made of — by code, never a model: a TYPED claim cites the library-minted result identities (or served handles) of the reads it rests on and is established only from those reads (this turn, read and returned, a local composed row, the kind fitting the row), withheld when rows on the same, a narrower or a wider search contradict it, a same-search call fails after it, or any call not classified as a read runs after it; the library writes the statement, attributing every text to the tool, the model or the result and listing every gap as "not checked". The typed path is UNMEASURED. A PROSE claim found by a fixed, versioned and hashed English grammar is only NOTED (`scope-wider`, `coverage-gap`, `entity-unresolved` …); on a first free replay against model-rater labels the prose grammar FAILED every gate it could be read on | `judgeTypedNegatives` + `judgeProseNegatives` + `composeStatement` + `NEGATIVE_CLAIM_PHRASES` (internal; typed checker mounted by `.negativeClaims()`, prose checker mounted observe-only with whole-answer limits) | `src/integrity/negative-claim/` | 11.0.0 |
 | a model head-mathing a total from tool-result numbers while a compute tool sits unused on the wire — a LATE line each iteration naming the staged refs and the `wants` tool that spends them (recency working FOR the instruction), plus the revise correction naming the same route | `nudge: true` (default off) + `stagedRefsNudgeLine` + `findStagedRefs` + `grounding_nudged` | `src/core/agent/stagedRefs.ts` | 9.75.0 |
 | a tool answering "I looked and found nothing", routably | `absent` + `looked_for` + `checked`/`not_checked`/`cannot_cover` + `tryInstead` (delivered status `'absent'`, routable by `onToolStatus`) | `src/semantics/coverage/absent.ts` | 9.43.0 |
+| a lookup that checked a name against ONE known list and found nothing — a named miss over the names it read, never "it does not exist": the names facet in `checked` (dated when `measuredAt` is an instant), the gap "names outside <source>" (`{ kind: 'scope', relevance: 'bears', bears: 'source' }`) the author cannot remove except by `authoritative: { why }` — and, for `partial: true`, also "not every name in <source> was read" (`bears: 'completeness'`), which nothing removes — and `provenance` composed; `names` read only to check `count` (`names-count-mismatch`) and never served | `absent({ what, among })` + `AmongDeclaration` + `namesFacetOf` | `src/semantics/coverage/among.ts` | 11.0.0 |
+| a build gate for declarations that claim more than was read — a refusal that says what does not exist, an absence that calls the input wrong, every `authoritative` names list for review | `checkSemantics(entries, { strict?, rules?: ['overclaim'] })` + catalog `refusals` (strings, values, or `{ text, argument?, value? }`) + codes `refusal-asserts-absence` / `absence-asserts-wrongness` / `authoritative-names` (warnings, only for samples using the new fields, and only on a sentence that names the looked-up argument or value; a format, range, permission or transport sentence exempts a wrongness phrase, never a non-existence one; `--strict` or `--rules=overclaim` make the first two errors) | `src/semantics/overclaim.ts` | 11.0.0 |
 | stating what a clean answer does NOT rule out | `coverage` + the declaration `{ checked, not_checked?, cannot_cover? }` | `src/semantics/coverage/ledger.ts` | 9.43.0 |
+| a tool's "nothing found" stating exactly what ONE call searched — declared once as typed data (every argument classified by role, defaults, built-in qualifiers, blind spots each bearing on a facet) and composed by the library from the arguments the call ran with, so it can only under-claim relative to a true declaration; a remote declaration establishes nothing; the row addressed by a library-minted result identity | `Tool.search` (`defineTool({ search })`: `source`, `subject`, `fixed`, `arguments` with `role` (incl. `query` / `match`) + `whenOmitted` (a value or `{ any: true }`), `complete`, `gaps` with `bears`, `limits.cap` / `limits.byCredential`, `ranking: 'approximate'`; judged at `defineTool` and again at registration) + `effects: 'read'` (local, `defineTool` only) + `absent({ checked: 'declared' })` / `coverage(rows, { checked: 'declared' })` + `resolved` / `paging` on a result + `ComposedCoverage` / `isComposedCoverage` (the `coverageDeclared` row: typed `checked`, `gaps`, `complete`, `composed: 'local' or 'remote'`, `resultId`, `handle`); events carry references, never a composed value; `check:semantics` lists `source-said` / `said-overlap` | `src/semantics/coverage/search/` | 11.0.0 |
 | a TYPED answer (`.outputSchema()`) carrying the limits its tools declared WITHOUT breaking its JSON — the same limits `.limitsTravelWithTheAnswer()` appends to a prose answer, as data beside it (checked / not checked / cannot cover, duplicates said once, every entry kept); `runTyped()` parses the model's answer untouched | `agent.answerCoverage()` + `turn_end.answerCoverage` + `AgentState.answerCoverage` (with `.outputSchema()` + `.limitsTravelWithTheAnswer()`; absent when no tool declared a limit) | `src/core/agent/stages/answerCoverage.ts` | 9.121.0 |
 | a person-readable short form of a coverage item, and whether an unchecked item is about EXISTENCE (does the thing asked about exist at all) or SCOPE (outside what the tool reaches) — on the record for a report, never in the model's request, never evidence. `short`: at most 80 chars, one line, never longer than `what`. `kind`: 'existence' or 'scope', on notChecked and cannotCover only. Refused at `absent()` and `coverage()`, read-never-repaired on a foreign envelope; carried by `tools.absent`, `tools.coverage_declared` and `coverageDeclared`; stripped from every served envelope, with `tool_end.modelResult` stamped where it differs | `CoverageItem` + `absent` + `coverage` | `src/semantics/coverage/` | 9.116.0 |
 | 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/injection-engine/factories/defineSkill.ts` | 9.116.0 |
@@ -124,6 +133,7 @@ not in this table, search `src/index.ts` for the nearest noun before writing cod
 | 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 |
 | proving a session store really honours the port | `runSessionLifecycleConformance` + `declared` skips (by case name WITH the reason; a declared case still RUNS) + outcomes `'passed'`/`'not-applicable'`/`'declared'`/`'failed'` | `src/hosting/conformance/` | 9.37.0 |
 | deciding who owns a contested session write | `resolveSessionOwner` | `src/hosting/sessionOwnership.ts` | 9.37.0 |
+| a session list that badges only what still waits on a person — an answered pause, or one no answer can reach any more, lists as a conversation; the one reading every store that lists reports (the conformance battery holds a store you wrote to it) | `listedFormatOf` + `SessionSummary.format` | `src/hosting/answeredPause.ts` | 11.0.0 |
 | a host filing its OWN per-turn artifacts (a story, the person's clicks) where `artifact-get` will look for the same caller — never composing a scope itself; awaited inside the turn, bounded (`turnArtifactsTimeoutMs`, default `TURN_ARTIFACTS_TIMEOUT_MS`), revoked after it (`TurnArtifactsExpiredError`), failures on the stream (`artifacts.hand_over_failed`) | `HostReply.turnArtifacts` + `TurnArtifacts` | `src/hosting/turnArtifacts.ts` | 9.115.0 |
 | a host reading or filing artifacts in the scope a redemption by the same caller reads, OUTSIDE a turn (a read by ref before a run, an app-owned route) — the redemption door's verifier (the person a token or a sign-in key proves — a `HostRequest` goes in as it is — or at an open door the session id and claim), session-id check, ownership rule and ONE scope composer; refusals as values (`unverified` / `unavailable` / `no-session` / `invalid-session` / `not-found` / `no-store`); never builds or evicts an instance, never the unscoped store; revoked with its instance | `handle.artifactsForRequest` + `ArtifactsForRequestResult` | `src/hosting/standingAgent.ts` | 9.117.0 |
 | refusing a forged cross-site request, DNS rebinding or an oversized session id at the hosting door — before any handler, in every identity mode; the same rule for an app's own routes beside the door | `doorGuard` + `checkSessionId` + `MAX_SESSION_ID_LENGTH` + `CrossSiteOptions` (`allowedOrigins` / `allowedHosts` / `requireJsonContentType` on `httpHost`, `nodeHost` and the hosted-runtime adapters, which default the browser rules OFF on a non-loopback bind; a loopback bind defaults `allowedHosts` to the loopback names) + `AgentHost.onRefusal` (feeds the ingress record) | `src/hosting/doorGuard.ts` | 9.115.0 |
@@ -140,7 +150,8 @@ not in this table, search `src/index.ts` for the nearest noun before writing cod
 | making a caller-supplied id safe for a backend | `encodeIdentityField` | `src/memory/identity/encode.ts` | 9.37.0 |
 | scoping a skill's tools so they reach the model only while it is active | `toolsFromActiveSkill` + a no-arg posture (default off) + the stamp `autoActivate: 'currentSkill'` (a default, never an override) | `src/core/agent/toolsFromActiveSkill.ts` | 9.36.0 |
 | subscribing to every event in one domain at once | `DomainWildcard` | `src/events/dispatcher.ts` | 9.4.0 |
-| pausing a run for a person and resuming it later | `checkInApproved` / `checkInDeclined` (`{ by, note?, value? }`; a decline is NOT an abort — the model gets a "declined by human" tool result and adapts in-loop) | `src/core/checkin.ts` | 7.5.0 |
+| pausing a run for a person and resuming it later | `checkInApproved` / `checkInDeclined` (`{ request, by, note?, value? }`; a decline is NOT an abort — the model gets a "declined by human" tool result and adapts in-loop) | `src/core/checkin.ts` | 7.5.0 |
+| a person's approval used ONCE, for the exact call they were shown — refused for another paused request (a later pause of the run, a parallel sibling, another conversation), for a checkpoint whose call changed after the ask, for an ask whose later rules changed or whose arguments a later rule rewrote, or on a second resume; once per ledger — one per process by default, one shared store across processes; every pre-execute callback and event (a `checkIn` predicate, the evidence assembler, the permission checker, `tool_start`, and the history they are handed) sees one shared frozen copy of the arguments (its own copy when they hold a `Map`, `Set`, `Date` or typed array), never the ones the tool runs with, and an approved call is held to its request again at `execute`; a closed pause's call is recorded as not run only when the ledger the request was minted under spends it (a tombstone, so nothing can run it later), else as possibly run — proof needs a shared ledger with a `storeId` (unique per backing store, never copied across environments, changed on migration) and a permanent `spend` across processes, and a retried close keeps its verdict (`closed-proven:` marker; a late answer is refused `'closed-by-host'`; a decision is spent only in the proving ledger its request was minted under — `'ledger-changed'` otherwise, so a ledger migration means pending approvals are asked again); this process's default ledger proves only for pauses kept in `memorySessions()`, a restart never; switching ledgers leaves earlier pauses unprovable | `CheckInRequest.id` / `MiddlewareAsk.id` (the request id, bound to the call) + `CheckInDecision.requestId` + `ResumeDecisionError` (`reason`) + `Agent.create({ decisionLedger })` / `DecisionLedger` / `inMemoryDecisionLedger` | `src/core/consentRequest.ts` | 11.0.0 |
 | refusing unserved, ambiguous, malformed or known not-dispatched findings citations before host callbacks and tool execution, with request-local accepted-attempt evidence, bounded diagnostics and JSON-answer admission; no additional model call or cache-layout change                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          | `captureFindingsRequest` + `findingsReferenceRefusal` (internal; enabled by `.findings()`)                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  | `src/core/agent/findings/admission.ts`                  | 10.9.0                          |
 | a SECOND source judging every tool result — a calibrated classifier asked what a result is worth for the declared proposition (never why the tool was called), its distribution and cost on the record beside the model's own standing, never merged, never served in its place (policy A) | `.findings({ judge })` + `Classifier` / `typesafe` / `mockClassifier` (`agentfootprint/classify`) + `JudgmentRow` / `JudgmentErrorRow` + `classifierScorer` (the scored entry choice, `agentfootprint/skill-graph`) | `src/classify/` | 9.104.0 |
 | a classifier's reading of WHICH TOOL beside every model call — the ranking, the pick and the cost on the record before the call, the model's call and the agreement after it; optionally the served list narrowed to the top-N plus the doors, on the committed record the receipt hashes and the served view rebuilds; a miss recorded and the full wire served next call, never a refusal, never an override | `.toolChoice({ classifier, serve, alwaysServe })` + `ToolChoiceRow` + `ToolChoiceOutcomeRow` + `ToolChoiceErrorRow` + `ALWAYS_SERVED_TOOLS` + `recordToolChoice` + `narrowServed` (events `agentfootprint.tool_choice.*`, bench `npm run bench:tool-choice`) | `src/core/agent/toolChoice/` | 9.105.0 |
@@ -154,7 +165,7 @@ not in this table, search `src/index.ts` for the nearest noun before writing cod
 | a per-request deadline on your gateway provider, so a gateway that never answers (or a stream that goes silent) fails typed instead of hanging the run: bounds the response headers, a `complete()` body and EACH stream read (first chunk, then every gap — a stream that keeps talking is never cut off); a miss aborts the request and raises `reason: 'timeout'`, `retryable: true` (withRetry re-opens it while no chunk reached the caller); the caller's `req.signal` still wins; omitted = the fetch gets exactly `req.signal` as before | `timeoutMs` + `invokeModelGateway` + `InvokeModelGatewayError` (`reason: 'timeout'`) | `src/adapters/llm/InvokeModelGatewayProvider.ts` | 9.130.0 |
 | Replay a saved complete domain-event batch with the same fork grouping and nested drill projection as live run steps | `ingestDomainEvents` + `getSteps` + `clear` | `src/recorders/observability/RunStepRecorder.ts` | 10.0.0 |
 | experimental, not yet validated in real use: additive saved-record shapes for scoped historical verification observations; paired checkpoint readers and writers validate retained evidence and counters without judging old observations again, and native continuation refuses an unarmed evidence carrier; protocol only — no runtime verifier, model declaration parser or answer badge is enabled | `FindingsRow` + optional `AgentRunCheckpoint.claimVerification` | `src/core/` | 10.2.0 |
-| an AG-UI frontend (`@ag-ui/client`, CopilotKit, the AG-UI Dojo) reading an agentfootprint run with no glue code — the run's served events translated into AG-UI 1.0 events: streamed text, tool calls with arguments and results, reasoning, ReAct iterations and compositions as steps, a nested agent (a `Sequence` step, a `Parallel` branch) as a sub-agent with its parent links, a pause as an interrupt, a failure as `RUN_ERROR` in the record's words; `CUSTOM` an allow-list of events with projected fields (`AG_UI_CUSTOM_EVENTS`), reasoning only on request; ids minted from the record's address under the request's run id (unique across a thread when branches reuse a provider's tool-call id); nothing a redaction policy hides on the wire, at any depth; framed by the official `@ag-ui/encoder` (optional peer, loaded only when a framing is built) | `agUiSerializer` + `agUiSse` + `AG_UI_CUSTOM_EVENTS` (`agentfootprint/ag-ui`) + `RunTranslation` / `RunSettlement` (the port, `agentfootprint/hosting`) | `src/ag-ui/` | 10.4.0 |
+| an AG-UI frontend (`@ag-ui/client`, CopilotKit, the AG-UI Dojo) reading an agentfootprint run with no glue code — the run's served events translated into AG-UI 1.0 events: streamed text, tool calls with arguments and results, reasoning, ReAct iterations and compositions as steps, a nested agent (a `Sequence` step, a `Parallel` branch) as a sub-agent with its parent links, a pause as an interrupt, a failure as `RUN_ERROR` in the record's words (an answer `.answerValidation()` withheld as `RUN_ERROR { code: 'ERR_ANSWER_VALIDATION' }`, a refusal not a crash — `RunSettlement.refusal` / `RunRefusal`); `CUSTOM` an allow-list of events with projected fields (`AG_UI_CUSTOM_EVENTS`), reasoning only on request; ids minted from the record's address under the request's run id (unique across a thread when branches reuse a provider's tool-call id); nothing a redaction policy hides on the wire, at any depth; framed by the official `@ag-ui/encoder` (optional peer, loaded only when a framing is built) | `agUiSerializer` + `agUiSse` + `AG_UI_CUSTOM_EVENTS` (`agentfootprint/ag-ui`) + `RunTranslation` / `RunSettlement` (the port, `agentfootprint/hosting`) | `src/ag-ui/` | 10.4.0 |
 | writing a run's Server-Sent Events in a different frame shape — the framing is a strategy: `toSSE({ framing })`, default the frames it always wrote | `SseFraming` + `agentfootprintSse` (`agentfootprint/observe`) | `src/hosting/stream.ts` | 10.4.0 |
 
 **Maintaining this table:** a new public capability adds a row, in the same

package/README.md

@@ -1,28 +1,25 @@
-
-
 <h1 align="center">Agentfootprint</h1>
 
 <p align="center">
-  <strong>Your agent gave an answer that <em>looks</em> right — and it's wrong.<br/>The logs can't tell you who influenced it. Agentfootprint can.</strong>
+  <strong>Build agents whose answers can be checked.</strong>
 </p>
 
 <p align="center">
-  The explainable AI agent framework for TypeScript: every read, write, decision, and tool call becomes
-  <strong>connected evidence</strong> as your agent runs. When something goes wrong, you don't grep logs — you ask.
+  A TypeScript agent framework for connecting answers to recorded evidence, making uncertainty explicit,
+  and checking outputs before delivery. Configure what an answer must support and when to withhold it.
 </p>
 
 <p align="center">
-  <strong>Build</strong> agents — skills, steering, RAG, memory, control flow — and <strong>debug</strong> them like nothing else.<br/>
-  <em>Why</em> is a query, not a guess.
+  Built on <a href="https://github.com/footprintjs/footPrint">FootprintJS execution provenance</a>:
+  context, tool calls, results and decisions become connected records as the agent runs.<br/>
+  Build with tools, skills, memory, RAG and orchestration; use that record for answer checks, debugging and review.
 </p>
 
 <p align="center">
-  <a href="https://footprintjs.github.io/agentThinkingUI/">
-    <img src="docs/assets/hero-atui.png" alt="An agent run replayed in Story Lens — the LLM 'brain' calls the Flight-search tool, the step inspector shows the tool's raw output and the brain's reasoning about it, and the timeline scrubs every step of the run." width="100%">
-  </a>
-</p>
-<p align="center">
-  <sub>A real run, replayed — rendered with <a href="https://github.com/footprintjs/agentThinkingUI"><b>Story Lens</b></a> (<code>npm i agentthinkingui</code>). Every frame is generated from the run's own trace; <a href="https://footprintjs.github.io/agentThinkingUI/">▶ watch it live</a>.</sub>
+  <a href="#what-can-this-answer-support">Evidence and limits</a> ·
+  <a href="#checks-you-can-enable">Checks and guarantees</a> ·
+  <a href="#how-this-compares-with-langchain-and-mastra">Framework comparison</a> ·
+  <a href="#quick-start--runs-offline-no-api-key">Quick start</a>
 </p>
 
 <p align="center">
@@ -37,38 +34,75 @@
 
 ---
 
-## The new error class
+## What can this answer support?
+
+A tool returned no rows. Before an agent says **"there are no incidents"**, the app
+needs to know which account was searched, what period the read covered, whether it
+finished, and what it could not reach. A successful empty query and a failed query
+support different answers.
+
+For example, the bounded claim is: **"The search returned no matching incidents
+for this account and time window. Email reports were not checked."** That is an
+illustration of scope-aware wording, not a claim that no incident exists anywhere.
+When the evidence cannot support the requested conclusion, the app should make
+that uncertainty explicit or withhold the answer.
+
+Agentfootprint supplies the execution record and configurable checks for that
+decision. Your app defines the comparisons and delivery policy. Tool declarations
+must describe the query truthfully: recording a source's assertion does not prove
+the source is correct.
+
+## How evidence reaches the answer
+
+1. **Record what ran.** FootprintJS connects execution steps and data dependencies;
+   Agentfootprint records the context supplied, tools called and results returned.
+2. **Preserve the limits.** Tools declare absence, coverage and time boundaries.
+   Configure those limits to travel with the answer instead of relying on the model
+   to repeat them.
+3. **Check before delivery.** Opt-in answer validation compares the candidate with
+   evidence under app-authored rules. Enforce mode withholds failed or unverified
+   candidates; the host decides how to explain the refusal to the user.
+4. **Inspect the same run.** Review recorded inputs, results, decisions and checks,
+   or replay the execution to investigate a failure.
+
+Execution provenance describes what ran and what was supplied. It does not expose
+the model's internal reasoning or independently establish that an external fact
+is true. Withholding an answer does not undo tool actions already performed.
 
-For decades, software had two kinds of errors — and developers never needed deep
-domain knowledge to fix either:
+## Checks you can enable
 
-| Error class | Where the bug lives | How you find it |
+Installing the framework does not make every answer verified. These mechanisms
+have different jobs and must be configured for the claims your app needs to check.
+
+| Mechanism | What it provides | Boundary of the guarantee |
 |---|---|---|
-| **Infrastructure** — crash, timeout, 500 | the system | infra logs, monitoring |
-| **Business logic** — wrong branch, wrong math | the code | stack trace, debugger, `console.log` |
-| **Contextual** — wrong tool chosen, wrong fact believed, stale memory trusted | **what the model was given** | **nothing. Until now.** |
+| [`absent()`, `coverage()` and `.limitsTravelWithTheAnswer()`](#what-a-tool-returns--three-helpers-one-rule) | Explicit absence and declared limits, carried into prose or returned beside typed output. | Preserves declarations; does not prove that the tool described its coverage correctly. |
+| [`.answerValidation()`](docs-next/content/docs/build/output-schema.mdx#check-the-answer-against-evidence) | App-authored checks on a typed final answer. Enforce mode buffers drafts and withholds failed or unverified answers; observe mode records the report and permits delivery. | Only the configured checks are judged. The app owns their correctness and the trustworthiness of its evidence. |
+| [`.namesAndNumbersFromEvidence()`](docs-next/content/docs/build/evidence-gate.mdx) | A deterministic detector for unsupported values, with configurable extraction limits and delivery postures. | Default `assist` flags; `rails` refuses. A false sentence assembled from real values can pass. This is not general factual verification. |
+| [`Tool.search` and typed `.negativeClaims()`](docs-next/content/docs/build/negative-claims.mdx) | Composed search scope and library-written statements for cited structured negative claims, retaining gaps and withholding or reporting unsupported claims according to policy. | **Opt-in, available but not recommended pending benchmark gates.** Accuracy and usefulness remain unmeasured. Depends on truthful app-owned search declarations; other answer fields remain unchecked model text. |
+| [`.negativeClaims({ prose: true })`](docs-next/content/docs/build/negative-claims.mdx) | Bounded heuristic warnings on the model's own negative sentences. | Never verifies, blocks or rewrites an answer. The previous detector failed its benchmark; the revised path is unmeasured. No warning does not mean verified. |
 
-Agents introduced the third class. The code is correct, the infra is healthy, the
-answer even reads well — and the run is still wrong, because something influenced
-the model:
+The links above describe this branch. Features marked **unreleased** in the
+[capability index](CAPABILITIES.md) are not yet available in the published package;
+check its availability column and the [release notes](CHANGELOG.md) for your
+installed version. The basic quick start below does not enable these checks.
 
-| The model… | because… |
-|---|---|
-| picked the wrong tool | two descriptions read nearly alike — it chose between twins |
-| believed a wrong "fact" | a tool returned it, or an injected fact planted it |
-| followed the wrong instruction | the wrong skill / steering fired — or fired one iteration too early |
-| answered from the past | a previous turn or stale memory bled into this one |
+## How this compares with LangChain and Mastra
 
-Classical logs can't explain any of it: **they record what the code did, never
-what the context did.** The debugging question changed — no longer *"what did my
-code do?"* but **"who influenced the model?"**
+These frameworks all support agent building and runtime controls. The useful
+distinction is what each emphasizes, rather than whether it has guardrails.
 
-## The idea
+| Framework | Emphasis and existing runtime controls |
+|---|---|
+| **LangChain / LangGraph** | Model and tool integrations, agent loops and stateful orchestration with persistence and human oversight. [LangGraph](https://docs.langchain.com/oss/javascript/langgraph/overview) covers execution; [LangChain guardrails](https://docs.langchain.com/oss/javascript/langchain/guardrails) can check inputs, outputs and tool calls during a run. |
+| **Mastra** | A TypeScript framework for agent applications, with workflows, memory, development tools, tracing and evaluations. Its [input/output processors](https://mastra.ai/docs/agents/processors) can validate or transform messages during execution. [Overview](https://mastra.ai/docs). |
+| **Agentfootprint** | Agent building organized around FootprintJS execution provenance: connected execution records, declared evidence limits, and [configured checks](#checks-you-can-enable) that can govern answer delivery. |
 
-If contextual errors live in what the model was given, then the run itself must be
-structured so context is **evidence** — every injection, read, write, decision, and
-tool call recorded *connected*, the moment it happens. Not logs you grep. Evidence
-you ask.
+Choose Agentfootprint when a central requirement is to connect an answer to what
+the agent actually read, the limits of that evidence, and the checks applied before
+delivery. Skills, tools and orchestration build the agent; the execution record
+also supports its answer policy. This comparison describes design emphasis, not
+exclusive capabilities or measured superiority in answer accuracy.
 
 ## Quick start — runs offline, no API key
 
@@ -92,7 +126,12 @@ const weather = defineTool({
 });
 
 const agent = Agent.create({
-  provider: mock({ reply: 'I checked: it is 72°F and sunny.' }),
+  provider: mock({
+    replies: [
+      { toolCalls: [{ id: 'weather-1', name: 'weather', args: { city: 'Paris' } }] },
+      { content: 'The demo weather tool returned 72°F and sunny for Paris.' },
+    ],
+  }),
   model: 'mock',
 })
   .system('You answer weather questions using the weather tool.')
@@ -100,10 +139,19 @@ const agent = Agent.create({
   .build();
 
 const result = await agent.run({ message: 'Weather in Paris?' });
-console.log(result);  // → "I checked: it is 72°F and sunny."
+console.log(result);  // → "The demo weather tool returned 72°F and sunny for Paris."
 ```
 
-For production, import a real provider from `agentfootprint/providers` and swap it in — `anthropic(...)` / `openai(...)` / `bedrock(...)` / `gemini(...)` / `ollama(...)`. Only the import line changes; the agent code stays the same. (Every provider — `mock` included — lives on the `agentfootprint/providers` subpath, so the main `agentfootprint` barrel stays free of optional peer-dep requires.)
+The tool runs locally and the mock scripts its call and reply. The temperature is
+fixture data, not a live weather reading; this example demonstrates wiring, not
+answer validation. For a configured delivery check, run the [mock answer-validation
+example](examples/features/99-guard-presented-code.ts).
+
+To use a real model, replace the scripted mock with a provider from
+`agentfootprint/providers` — `anthropic(...)` / `openai(...)` / `bedrock(...)` /
+`gemini(...)` / `ollama(...)` — and configure its model and any required credentials.
+The agent and tool wiring stays the same. Every provider, including `mock`, lives
+on that subpath so the main barrel stays free of optional provider SDK imports.
 
 **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).
 
@@ -138,7 +186,7 @@ execute: ({ vm, summary }) => {
 
 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
+## Building agents — context, tools and orchestration
 
 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.
 
@@ -184,12 +232,23 @@ That's the whole model: `Injection = slot × trigger × cache`.
 
 **3 slots × 4 triggers × N flavors = the entire context-engineering surface.**
 
-## What tracking buys you
+## Inspect and replay the evidence
+
+The recorded run also supports debugging. These examples illustrate different
+kinds of evidence; a similarity score or recorded dependency alone is not proof
+of why a model chose an answer.
 
-**See it in 30 seconds** — four questions logs can't answer, each answered by code in this repo from a real run:
+<p align="center">
+  <a href="https://footprintjs.github.io/agentThinkingUI/">
+    <img src="docs/assets/hero-atui.png" alt="An agent run replayed in Story Lens, with recorded tool output, model messages and an execution timeline." width="100%">
+  </a>
+</p>
+<p align="center">
+  <sub>A run replayed with <a href="https://github.com/footprintjs/agentThinkingUI"><b>Story Lens</b></a> (<code>npm i agentthinkingui</code>). Frames are generated from the run's trace; <a href="https://footprintjs.github.io/agentThinkingUI/">▶ watch it live</a>.</sub>
+</p>
 
 ```text
-Q: Why did the model pick refund_full instead of refund_partial?
+Q: Were refund_full and refund_partial described similarly?
 A: margin 0.02 — ⚠ NARROW: the two tool descriptions read nearly identical
    (toolChoiceRecorder — and the catalog lint flags the pair before you ever run)
 
@@ -197,23 +256,27 @@ Q: Why was this loan declined?
 A: decision ← [control: "DTI above the 0.43 affordability ceiling"] ← dti 0.52 ← monthlyDebt / income
    (decide() evidence + the causal slice — every hop is a real recorded edge)
 
-Q: Which piece of context made the answer wrong?
-A: CAUSAL: ablating fact 'vip-override' flipped the outcome in 3/3 seeded reruns
-   (localizeContextBug — ranked proxies, counterfactual proof)
+Q: Did removing a piece of context change the outcome in these reruns?
+A: ablating fact 'vip-override' flipped the outcome in 3/3 seeded reruns
+   (localizeContextBug — evidence from those counterfactual trials)
 
-Q: Prove nobody edited this run's record.
+Q: Does this exported bundle pass its integrity check?
 A: verifyAuditBundle → valid: false, brokenAt: #16 — the tampered record, named
    (hash-chained audit export, offline verification)
 ```
 
-And you don't have to read the trace yourself — the trace toolpack lets a debugger model do it: in one run it found a planted bug while reading **9.5% of the trace** ([self-explain](https://agentfootprint.dev/docs/debug/self-explain/)). The watching costs the run nothing: recorders run one beat behind the agent, never on its hot path.
+The trace toolpack also lets a debugger model inspect the record: in one run it
+found a planted bug while reading **9.5% of the trace**
+([self-explain](https://agentfootprint.dev/docs/debug/self-explain/)). That is one
+debugging result, not an answer-accuracy benchmark. Integrity checks establish
+properties of the exported record; they do not establish that its source data was true.
 
 ## Pick your door
 
-| 🔧 Building an agent? | 🐛 Agent misbehaving? | 🏛️ Need audit / compliance? |
+| Checking answers? | Building an agent? | Inspecting a run? |
 |---|---|---|
-| Typed agents with skills, steering, RAG, memory, guardrails — and the trace for free. | Lint your tool catalog in 5 minutes — works on **any** framework's tool list. Then causal slices, context bisection, and the debugger-LLM toolpack. | Hash-chained, tamper-evident run records with an offline verifier — record-keeping in the EU-AI-Act shape. |
-| [→ Quick start](https://agentfootprint.dev/docs/getting-started/quick-start/) · [→ Build an agent](https://agentfootprint.dev/docs/build/agent/) | [→ Debug](https://agentfootprint.dev/docs/debug/debug/) · [→ Tool-catalog lint](https://agentfootprint.dev/docs/debug/tool-catalog-lint/) · [→ Self-explain](https://agentfootprint.dev/docs/debug/self-explain/) | [→ Exporters & audit bundles](https://agentfootprint.dev/docs/monitor/exporters/) · [→ Security](https://agentfootprint.dev/docs/monitor/security/) |
+| Declare the evidence and limits; configure checks and the response to uncertainty. | Typed agents with skills, steering, RAG, memory and control flow. | Recorded dependencies, counterfactual reruns, replay and audit-bundle integrity checks. |
+| [→ Checks and guarantees](#checks-you-can-enable) · [→ Output contracts](docs-next/content/docs/build/output-schema.mdx) | [→ Quick start](https://agentfootprint.dev/docs/getting-started/quick-start/) · [→ Build an agent](https://agentfootprint.dev/docs/build/agent/) | [→ Debug](https://agentfootprint.dev/docs/debug/debug/) · [→ Exporters & audit bundles](https://agentfootprint.dev/docs/monitor/exporters/) |
 
 ## Mocks first, production second
 

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

@@ -286,7 +286,7 @@ const agent = Agent.create({ provider, model })
 agent.on('agentfootprint.context.evaluated', (e) => console.log(e.payload.activeIds));
 ```
 
-**124 typed events across 27 domains.** Two subscription shapes and no third:
+**125 typed events across 27 domains.** Two subscription shapes and no third:
 `'*'` (every event) and `'agentfootprint.<domain>.*'` (one domain). **`'agentfootprint.*'`
 is not a pattern** — TypeScript rejects it, and at runtime it would match nothing.
 
@@ -300,14 +300,24 @@ agent.on('agentfootprint.agent.turn_end', (e) =>
 ## Human in the loop
 
 ```typescript
-import { askHuman, isPaused, checkInApproved } from 'agentfootprint';
+import { isCheckInPause, checkInApproved } from 'agentfootprint';
 
 const result = await agent.run({ message: 'Refund $500?' });
-if (isPaused(result)) {
-  const final = await agent.resume(result.checkpoint, checkInApproved({ by: 'maya' }));
+if (isCheckInPause(result)) {
+  // The decision names the request it answers: once, for exactly the call shown.
+  const final = await agent.resume(
+    result.checkpoint,
+    checkInApproved({ request: result.checkIn, by: 'maya' }),
+  );
 }
 ```
 
+A decision for another pause, for a checkpoint whose call changed, or a second
+resume with the same decision throws `ResumeDecisionError` — the tool never runs.
+"Once" holds per ledger: agents in one process share one by default; when more
+than one process can resume a paused run, give them one shared store via
+`Agent.create({ decisionLedger })`.
+
 ## Resilience
 
 ```typescript

package/dist/adapters/hosting/agentCoreA2A.js

@@ -73,8 +73,12 @@ function agentCoreA2AErrorCode(code) {
         case 'ERR_SESSION_NOT_FOUND':
         case 'ERR_ARTIFACT_NOT_FOUND':
             return -32051;
+        // ERR_RESUME_DECISION is a Validation, not -32054: a client retries a
+        // Conflict with backoff, and the same decision is refused the same way
+        // every time.
         case 'ERR_INVALID_WIRE_OP':
         case 'ERR_DECISION_REQUIRED':
+        case 'ERR_RESUME_DECISION':
         case 'ERR_ARTIFACT_SESSION_REQUIRED':
         case 'invalid_request':
         case 'invalid_params':

package/dist/adapters/hosting/agentCoreA2A.js.map

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

package/dist/adapters/hosting/firestoreSessions.js

@@ -223,6 +223,7 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.firestoreFailure = exports.isFailedPrecondition = exports.grpcStatusOf = exports.documentIdFor = exports.firestoreSessions = exports.EnvelopeTooLargeError = exports.FirestoreIndexMissingError = exports.FIRESTORE_MAX_ENVELOPE_BYTES = exports.FIRESTORE_MAX_DOCUMENT_BYTES = exports.ttlPolicyCommand = exports.EXPIRES_AT_FIELD = exports.DEFAULT_SESSION_COLLECTION = void 0;
 const node_crypto_1 = require("node:crypto");
+const answeredPause_js_1 = require("../../hosting/answeredPause.js");
 const envelope_js_1 = require("../../hosting/envelope.js");
 const errors_js_1 = require("../../hosting/errors.js");
 const sessionOwnership_js_1 = require("../../hosting/sessionOwnership.js");
@@ -543,7 +544,10 @@ function firestoreSessions(options = {}) {
             const ref = docFor(sessionId);
             const row = {
                 sessionId,
-                format: checked.format,
+                // The LISTED format (`listedFormatOf`), what `listByUser` reports: a
+                // pause whose decision a resume already used reads as a conversation
+                // here, though `envelope` still holds the paused run.
+                format: (0, answeredPause_js_1.listedFormatOf)(checked),
                 savedAt: checked.savedAt,
                 envelope: json,
                 messageCount: (0, envelope_js_1.envelopeTranscript)(checked).length,
@@ -692,7 +696,10 @@ function firestoreSessions(options = {}) {
                     // hand a caller an id that opens nothing.
                     sessionId: typeof row['sessionId'] === 'string' ? row['sessionId'] : '',
                     savedAt: typeof row['savedAt'] === 'number' ? row['savedAt'] : 0,
-                    format: typeof row['format'] === 'string' ? row['format'] : 'unknown',
+                    // What the session IS now: a document written before the field
+                    // held the listed format says 'flowchart-v1' for any pause, and is
+                    // read again from the envelope the query already returned.
+                    format: (0, answeredPause_js_1.listedFormatOfRow)(typeof row['format'] === 'string' ? row['format'] : 'unknown', row['envelope']),
                     // A listing hint, never the authority — the transcript op reads the
                     // envelope itself and says the truth.
                     messageCount: typeof row['messageCount'] === 'number' ? row['messageCount'] : 0,