agentfootprint 9.99.0 → 9.101.1

package/AGENTS.md

@@ -544,7 +544,7 @@ files `agentfootprint.tools.coverage_declared`; with
 to the final answer, which is how a limit survives a model that would rather not
 mention it.
 
-### Observability — 111 typed events across 24 domains
+### Observability — 113 typed events across 25 domains
 
 ```typescript
 agent.on('agentfootprint.context.injected', (e) =>

package/CHANGELOG.md

@@ -5,6 +5,177 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [9.101.1] - 2026-09-16
+
+### Fixed — the docs site's export-file ceiling
+
+- 9.101.0 never reached npm: its publish workflow stopped at the docs site's
+  performance budget (`docs-next/scripts/check-site-budget.mjs`), where the
+  generated API-reference routes for the findings ledger's new exports took the
+  static export past the file-count ceiling. The ceiling is raised to the
+  measured count plus the same thin headroom; no byte ceiling moved. The library
+  is byte-identical to 9.101.0; the entry below is what ships.
+
+## [9.101.0] - 2026-09-16
+
+### Added — the model's own findings, on the record, at zero extra calls
+
+- `.findings()` on the agent builder (`AgentBuilder.findings`) — every
+  SERVED tool schema gains one reserved optional argument, `_findings`
+  (`RESERVED_ARGUMENT`): the model declares a `basis` for each call before
+  the result exists (`direct` when it expects the answer, `exploratory` when
+  it is looking; optional `expect`: `low` / `medium` / `high`) and, on its
+  next tool call or as a top-level `_findings.previous` on a JSON answer,
+  the STANDING of each earlier tool result by its tool_result id — `fact`
+  with the assertions it stands on, `open` with what would settle it,
+  `ruled-out` with one line, `noise` with nothing. The library peels the
+  argument off before the tool, the middleware chain, the argument
+  validator, the permission gate and every pause carrier see the call, files
+  the rows through ONE writer as an append-only `AgentState.findingsLedger`
+  (`basis` / `standing` / `conflict` rows — a conflict is `conflictsOf`'s
+  fact about two stood-on readings that disagree, witnesses by identity),
+  and leaves the assistant turn in history verbatim. Read it back with
+  `Agent.findings()` (detached; `undefined` when unarmed or when the model
+  declared nothing — never an empty array standing in for "no findings").
+  Why: a long tool loop serves every result back in full on every call and
+  what the model already judged is nowhere but in its head; asking a second
+  model would cost a call per result and put a second voice on the record.
+  Nothing is inferred (a call with no declaration files no row; a result
+  nobody names has no standing — undeclared, never `open`); what the answer
+  turn is then SERVED from the record is the next block; and the always-on
+  `findings-ledger` instruction is a system piece hashed on every receipt,
+  so a reworded ask is a different hash a bench can name. `keepLedgerFacts`
+  is accepted now so no public name changes later and is inert until
+  standing-aware eviction lands.
+- Two typed events — `agentfootprint.findings.declared` (one per basis row)
+  and `agentfootprint.findings.standing` (one per standing row) — carry
+  identities, enums and counts only; assertion values, `settles` and `line`
+  live in the committed key under whatever redaction the run configured.
+- The checkpoint carries `findingsLedger` only when present, and
+  `continueFrom` re-seeds it, so a continued conversation never reports its
+  earlier declarations as undeclared. `validateCheckpoint` checks each row's
+  shape per kind — shape only, never the values.
+- A registry tool that declares its own `_findings` property is refused at
+  build, naming the tool, and only when `.findings()` is armed; a provider-
+  or MCP-ingested schema that carries the name is left undecorated (the
+  author's property wins, recorded by the committed schema itself), and a
+  call to that tool is not peeled — the value runs as the author's argument
+  and files no row.
+- The answer that stands is the peeled JSON; a re-ask (`output-retry`,
+  `step-nudge`, `evidence-recheck`) quotes the emission — the string the
+  provider returned — into the conversation, never the peeled form. A policy
+  halt hands the app the peeled args (`PolicyHaltError.proposed.args`), the
+  same carrier law every pause carrier follows.
+- Exported from the root: `RESERVED_ARGUMENT` and the row types
+  (`FindingsLedger`, `FindingsRow`, `BasisRow`, `StandingRow`,
+  `ConflictRow`, `ConflictWitness`, `FindingsDeclaration`, `Basis`,
+  `Expect`, `Standing`).
+
+### Added — served from the ledger
+
+- The answer turn reads the ledger. Once the model has declared at least one
+  standing, every later call on an armed agent is served a request-only
+  system piece composed from the folded ledger — `source: 'findings'` on the
+  receipt's `system.pieces` and on `servedAt(snapshot, k).system.pieces` —
+  headed by the context contract's own field meanings and holding `facts`,
+  `limitations`, `evidenceRefs` and `nextSteps`, each bucket marked "declared
+  by the model" and quoting the declaration (a conflict names both witnesses
+  and no verdict; a ruled-out branch is its one line), then `noise` as a count
+  and `undeclared` for the results nobody named — the honest absence, never
+  `open`. Bounded, every overflow stated, an empty bucket omitted. On the
+  wire, and only on the wire, a tool result the model judged `noise` or
+  `ruled-out` is served as a ticket, `{"collapsed":true,"standing":…,
+  "toolCallId":…}`, in place of its content; `open` and undeclared results
+  stay verbatim; nothing is dropped or reordered, and `toolName` /
+  `toolCallId` are untouched, so the tool_use/tool_result pair stays
+  wire-valid. `history` never changes — the window stage stays its only
+  writer — and `servedAt` rebuilds the piece and the collapse with the same
+  functions in the same order, so `receiptAt(k)` agrees by construction on
+  an armed run with a collapsed entry; no new served gap, `withheld`
+  untouched. Why a piece and a ticket rather than a rewritten history: the
+  record must keep the emission, and a judged result's bytes should not be
+  read again at full size on every call after the model said what it was.
+- `.findings({ serve })` chooses how much of the pile stays:
+  `'ledger-and-facts'` (the default — facts, open and undeclared results
+  verbatim beside the piece; noise and ruled-out as tickets) or
+  `'ledger-only'` (fact results as tickets too; the model answers from the
+  piece, its own paraphrase). The second is BENCH-GATED: shipped so
+  `bench/findings-shuffle.mjs` can measure it on a real model, not a
+  recommendation, and never a default until that run shows the answer does
+  not drift when the same evidence arrives in a different order. The run
+  constant `findingsServe` is committed on every armed run so a served view
+  knows which dial produced the wire.
+- The piece carries no per-call byte — it is a function of the folded
+  ledger and the wire's tool ids and nothing else — because it joins the ONE
+  system block the cache marker covers (`systemPromptCachePolicy` is
+  `'always'` by default, and the Anthropic adapters mark the whole joined
+  system prompt as one block). A re-ask is served the same system bytes and
+  the same system hash as the call before it. What that does NOT save: a
+  model that declares on every call moves the ledger on every call, so from
+  the first standing on each such call writes a new system cache entry and
+  reads none, and on Anthropic's wire the message breakpoints behind it miss
+  too. The feature's claim is wire bytes, not cache reads; no bench in the
+  tree counts cache tokens yet, and the design page names the trade.
+- Measured (`npm run bench:findings`, mock provider, 20 tool calls, a
+  planted fact every 3rd): the piece carries all 6 planted facts at the
+  answer turn on every armed row — including under a sliding window that had
+  evicted 4 of them — and 13 of the 14 noise results are tickets, the noise
+  share of tool-result bytes on the wire falling from 93.5% to 15.2% with no
+  window; the fourteenth is the last batch's, undeclared by the
+  no-outputSchema law and served in full. The design page has the printed
+  table and its reading; no real-model number exists yet.
+- Grounding is unchanged: the evidence gate keeps indexing raw history, so a
+  faithful ledger fact grounds through the result it cites and an invented
+  value is flagged. The choice seam no longer credits the whole system prompt
+  while a request-only piece is joined, so a subject id invented in a `fact`
+  assertion cannot excuse an argument equal to it; an unarmed agent takes the
+  branch it always did. The grouped chart carries `findingsLedger` across the
+  call-llm boundary, so both chart shapes serve byte-equal text.
+
+### Unchanged — an agent without `.findings()` records the bytes it recorded before
+
+- Every decoration, peel, write, piece and event is gated on the door. The
+  15 byte-identity references under `test/core/tools/reference/` were run on
+  this tree first and pass untouched; ONE new reference, `agent-findings`,
+  was generated alone — and regenerated alone for the served piece, its
+  delta (the run constant, the piece on one receipt, nothing else) on the
+  test file's header. `npm run bench:findings` runs each configuration
+  unarmed, armed with the mock declaring, and armed with the mock declaring
+  NOTHING, and exits non-zero if any of the six baseline columns moves under
+  that silent arm — they do not: an armed agent whose model declares no
+  standing is served the bytes it always was, plus the instruction.
+- The name was proved before it shipped: `_findings` survives every
+  provider's `inputSchema` mapping byte-for-byte, `required` untouched —
+  Anthropic, OpenAI, Gemini, Bedrock, Ollama, Foundry (hosted and local) and
+  both browser providers (`test/adapters/reservedArgumentSurvives.test.ts`).
+
+## [9.100.0] - 2026-09-16
+
+### Added — the delivered answer names its shape guarantee
+
+- `AgentState.answerGuarantee` — written by the Route decider on the turn
+  it picks `final`: `'tool-forced'` (the provider was forced by name to
+  answer through the output schema's synthetic tool, so the shape held on
+  the wire), `'checked'` (generated as text, parsed by the output schema
+  after), or `'none'` (no output schema, free text). A fact about HOW the
+  answer was obtained, beside `answerValidation`, which is about its
+  content. Why: three different strengths of "the answer has a shape"
+  existed and the record could not say which applied; a lens showing the
+  Answer stop now can. Borrowed from constrained decoding, where the shape
+  holds by construction — that word joins the vocabulary when a provider
+  that constrains its own decoding ships.
+
+### Changed — artifact bytes are encoded with footprintjs's own encoder
+
+- `canonicalPayloadBytes` — the one place every artifact store turns a JSON
+  payload into bytes — uses footprintjs 9.26.0's `stringifySnapshot`: the
+  same bytes `JSON.stringify` produces, with its own stack. A recording of
+  a long linear run (about ten thousand stages) nests one level per stage
+  and the engine's recursive encoder threw; such a recording could not be
+  minted. Byte-identical for everything that could be minted before, so
+  digests and `bytes` do not change. The file store's envelope already held
+  the payload as encoded text, so it needed nothing. footprintjs `^9.26.0`.
+
 ## [9.99.0] - 2026-09-16
 
 ### Added — the story knows which stage each beat came from

package/CLAUDE.md

@@ -157,7 +157,7 @@ Traps: `src/observability/` holds the finder IMPLEMENTATIONS (canonical home; `d
 - **Embedder fingerprint** (8.9.0) → `Embedder.id` (optional; every shipped embedder sets one, and NONE include dims — the store appends `@<dims>` itself, so an id carrying its own size double-stamps) + `indexDocuments` defaulting `embedderId` to it + `SqliteVectorStore.reconcileFingerprint` (the only comparison site). Rule: dimensions ALWAYS decide, model ids decide only when BOTH sides named themselves — refusing on an absent name would block the majority of callers who never pass `embedderId`.
 - **Retrieval record** (8.8.0) → FOUR stages write one object in sequence: `loadRelevant` (candidates+scores+threshold verdicts) → `pickByBudget` (re-marks admitted→over-budget/over-max-entries) → `formatDefault` (`promptFragment` + `promptPosition`) → the read mount's outputMapper lifts it to root as `retrievalEvidence_<id>`. `memoryRecallInjections` then splits ONE recall into one ActiveInjection PER CHUNK — guarded by a byte-equality check (`fragments.join('\n\n') === systemContent`) that falls back to the single injection rather than change the prompt. `rank` (score order) and `promptPosition` (picker order) are DIFFERENT and both load-bearing: joining fragments in rank order reproduces the right bytes in a sequence the model never saw.
 - **AgentState** → all 8 stages/ files, both builders' mappers, memory-wire STRING-TYPED keys ('runIdentity'/'turnNumber'/… buildAgentChart.ts:177-180 — not refactor-safe), finalizeResult's `reliabilityFail*`/`policyHalt*` reads (rename silently kills the typed errors).
-- **events/** → 111 typed events across 24 domains (counts anti-drift-tested against this file — update BOTH when adding events): ALL_EVENT_TYPES exhaustiveness tests, DomainWildcard hand-list, ~42 importers (recorders, strategies, stream, commentary).
+- **events/** → 113 typed events across 25 domains (counts anti-drift-tested against this file — update BOTH when adding events): ALL_EVENT_TYPES exhaustiveness tests, DomainWildcard hand-list, ~42 importers (recorders, strategies, stream, commentary).
 - **Run-configuration manifest (9.41.0)** → `agentfootprint.agent.run_configured`, the JOIN KEY that turns N runs into N labelled ARMS: one event naming the adapters/strategies in play (provider+model, reactMode, each memory's declared strategy/retrieval/embedder, window, graph posture+classifier, evidence posture, artifacts-present). Composed by the PURE `core/agent/runManifest.ts`, dispatched from `Agent.emitRunManifest()` at the END of `createExecutor` — the ONE funnel `run()` AND `resume()` share, both of which mint a fresh runId. Direct `dispatcher.dispatch` with a STATED pseudo-stage (`run-configured#0`), the `emitToolSessionReport` precedent — there is no stage yet, and `minimalMeta()` would make the one joinable-by-design event unjoinable. TWO laws, both tested: NAMES ONLY (a store is reported PRESENT and unnamed rather than identified by a directory/endpoint — `MemoryStore` and `ArtifactStore` declare no id), and ABSENT means "not configured", never a guessed `'default'`. Graph presence is read off `skillGraphNextSkill`, NOT `skillGraphCascade` (a 9.16-style mount sets no cascade and would read as "no graph"). `MemoryDefinition` gained `strategy`/`retrieval`/`embedderId` for it — declared names the compiled pipeline had closed over, the `store`-in-the-open precedent.
 - **adapters/types.ts LLMMessage/LLMRequest** → 62 importers: tool_use round-trip (toolCalls.ts:115-135), wire assembly (callLLM.ts:150-160), providers, cache strategies, security/extractSequence, reliability loop.
 - **Cache** → strategy registration is a MODULE SIDE EFFECT (src/index.ts:15-17); an entry point skipping that import silently falls back to NoOp. Resolved once per Agent at construction (Agent.ts:347).

package/README.md

@@ -931,6 +931,7 @@ The flowchart, recorders, and tests don't change between dev and prod.
 - Human-in-the-loop pause / resume — a tool calls `pauseHere(...)` (or `askHuman(...)`); `isPaused(result)` hands you a JSON-serializable checkpoint, and `agent.resume(checkpoint, input)` continues hours later on a different server
 - Resilience primitives — `withRetry`, `withFallback`, `withCircuitBreaker`, `.outputFallback`, `agent.resumeOnError`
 - Context Integrity — deterministic checks at the seams where a run contradicts ITSELF: a tool parked but still on the wire, a tool offered after the results grounding it were evicted, an answer field that disagrees with the fact it claims to report (`.claims()`, requires `.outputSchema()`). Nothing is blocked or rewritten — each defect is one typed finding, and every run files a disposition ledger so "no findings" and "no check ran" stay different states. `integrityPosture: 'dev'` adds the liveness proofs (a start-of-run canary; `CheckerDeadError` instead of a green report from a checker that never ran). Read it back with `find_context_errors` over a recording — [Context Integrity](https://agentfootprint.dev/docs/monitor/context-integrity/)
+- Findings ledger — `.findings()` adds one reserved optional argument, `_findings`, to every served tool schema: the model declares why it makes each call (`basis`: `direct` or `exploratory`) and, on its next call or as a top-level key of a JSON answer, the standing of each earlier result by its tool_result id (`fact` with the assertions it stands on, `open`, `ruled-out`, `noise`). Zero extra model calls. The argument is peeled off before the tool, the middleware or the validator sees the call; the rows land as one append-only `findingsLedger` on the run's state (`agent.findings()`), with a `conflict` row whenever two stood-on readings disagree. Nothing is inferred — a call that declares nothing files nothing — and nothing is served differently yet: the ledger is a record. An agent that never calls `.findings()` is byte-identical to one built before it existed
 - 60+ typed observability events — `agent` · `composition` · `context` · `stream` · `tools` · `skill` · `memory` · `cache` · `cost` · `permission` · `eval` · `embedding` · `pause` · `error` · `fallback` · `resilience` · `reliability` · `risk`
 
 **Debugging & compliance** (`agentfootprint/observe`)

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

@@ -252,7 +252,7 @@ const agent = Agent.create({ provider, model })
 agent.on('agentfootprint.context.evaluated', (e) => console.log(e.payload.activeIds));
 ```
 
-**111 typed events across 24 domains.** Two subscription shapes and no third:
+**113 typed events across 25 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.
 

package/dist/artifacts/payload.js

@@ -25,6 +25,7 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.decodeArtifactData = exports.encodeArtifactData = exports.computeArtifactDigest = exports.decodeCanonicalPayload = exports.payloadShapeOf = exports.measureArtifactBytes = exports.canonicalPayloadBytes = void 0;
 const types_js_1 = require("./types.js");
+const footprintjs_1 = require("footprintjs");
 const textEncoder = new TextEncoder();
 const textDecoder = new TextDecoder();
 /**
@@ -39,7 +40,10 @@ function canonicalPayloadBytes(data) {
         return textEncoder.encode(data);
     let serialized;
     try {
-        serialized = JSON.stringify(data);
+        // footprintjs's own encoder (9.26.0): the same bytes as JSON.stringify,
+        // with its own stack — a recording of a long linear run nests one level
+        // per stage and the engine's recursive encoder refused it.
+        serialized = (0, footprintjs_1.stringifySnapshot)(data);
     }
     catch (err) {
         throw new types_js_1.InvalidArtifactError(`the payload cannot be JSON-serialized (${err instanceof Error ? err.message : String(err)}). ` +

package/dist/artifacts/payload.js.map

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

package/dist/core/Agent.js

@@ -244,6 +244,14 @@ class Agent extends RunnerBase_js_1.RunnerBase {
     contextBudget;
     permissionChecker;
     toolArgValidation;
+    /** See AgentOptions.findings (9.101.0). Set by `.findings()` and undefined
+     *  on every other agent — the one value every findings gate below is
+     *  conditioned on, so an unarmed agent hands each stage exactly the deps
+     *  it always did. `serve` is threaded to seed (the run constant
+     *  `findingsServe`) and to call-llm (`findingsServe` in its deps) on an
+     *  armed agent only. `keepLedgerFacts` is inert until standing-aware
+     *  eviction lands. */
+    findingsOptions;
     /** The opt-in tool-result ceiling in characters (9.11.0). Absent → results
      *  are never measured. See {@link AgentOptions.maxToolResultChars}. */
     maxToolResultChars;
@@ -427,6 +435,10 @@ class Agent extends RunnerBase_js_1.RunnerBase {
      *  destroyed by the act of continuing, which is the one thing retention
      *  exists to prevent. Cleared on first read, exactly like the history. */
     pendingResumeFolded;
+    /** Its sibling for the findings ledger (9.101.0) — the model's standings
+     *  on results this process never saw, carried by the checkpoint and
+     *  restored as a stored record. Cleared on first read, like the history. */
+    pendingResumeFindingsLedger;
     /** The last completed run's final answer — see `checkpoint()` for why it is
      *  kept here rather than read back from the recording. Undefined after a run
      *  that failed or paused. */
@@ -605,6 +617,8 @@ class Agent extends RunnerBase_js_1.RunnerBase {
             this.permissionChecker = opts.permissionChecker;
         if (opts.toolArgValidation !== undefined)
             this.toolArgValidation = opts.toolArgValidation;
+        if (opts.findings !== undefined)
+            this.findingsOptions = opts.findings;
         // The tool-result ceiling (9.11.0). Refused HERE, naming the value, rather
         // than at the first tool call of the first run — a dial that cannot cap
         // anything is a configuration mistake, not a runtime condition.
@@ -1356,7 +1370,10 @@ class Agent extends RunnerBase_js_1.RunnerBase {
                 this.conversationOwner(), 
                 // …and the same graph cursor (SG-C), from the same snapshot reader —
                 // one reader, two carriers, so neither can lose what the other keeps.
-                this.continuityCursorOf(this.getLastSnapshot()?.sharedState), this.evidenceRecoveryOf(this.getLastSnapshot()?.sharedState));
+                this.continuityCursorOf(this.getLastSnapshot()?.sharedState), this.evidenceRecoveryOf(this.getLastSnapshot()?.sharedState), 
+                // …and the findings ledger (9.101.0), from the same snapshot reader
+                // `checkpoint()` uses — one reader, two carriers.
+                this.findingsLedgerOf(this.getLastSnapshot()?.sharedState));
                 throw new runCheckpoint_js_1.RunCheckpointError(cause, checkpoint);
             }
             throw cause;
@@ -1377,6 +1394,7 @@ class Agent extends RunnerBase_js_1.RunnerBase {
             // nobody asked it to. One run, one continuation.
             this.pendingResumeHistory = undefined;
             this.pendingResumeFolded = undefined;
+            this.pendingResumeFindingsLedger = undefined;
             this.pendingResumeSkillCursor = undefined;
             this.pendingEvidenceRecovery = undefined;
         }
@@ -1783,6 +1801,7 @@ class Agent extends RunnerBase_js_1.RunnerBase {
         const owner = this.conversationOwner();
         const skillCursor = this.continuityCursorOf(state);
         const evidenceRecovery = this.evidenceRecoveryOf(state);
+        const findingsLedger = this.findingsLedgerOf(state);
         return {
             version: 1,
             runId: this.currentRunContext.runId,
@@ -1802,6 +1821,9 @@ class Agent extends RunnerBase_js_1.RunnerBase {
             // exact byte shape.
             ...(skillCursor !== undefined && { skillCursor }),
             ...(evidenceRecovery !== undefined && { evidenceRecovery }),
+            // The model's standings (9.101.0) — absent unless the run recorded any,
+            // by the `folded` rule: an optional key, never a format change.
+            ...(findingsLedger !== undefined && { findingsLedger }),
         };
     }
     /** Both checkpoint doors keep the repair budget separately from conversation text. */
@@ -1855,6 +1877,20 @@ class Agent extends RunnerBase_js_1.RunnerBase {
             return undefined;
         return structuredClone(spans);
     }
+    /**
+     * The findings ledger for a checkpoint (9.101.0) — `foldedSpansOf`'s twin:
+     * one reader for `checkpoint()` and the crash carrier, `undefined` when the
+     * run recorded no rows (so the key stays absent), and a detached copy
+     * otherwise, never a reference into the live heap.
+     *
+     * @internal
+     */
+    findingsLedgerOf(state) {
+        const ledger = state?.findingsLedger;
+        if (ledger === undefined || ledger.length === 0)
+            return undefined;
+        return structuredClone(ledger);
+    }
     /**
      * The two owner facts every conversation carrier stamps — who the run was
      * for, and which agent ran it (9.2.0).
@@ -1901,6 +1937,11 @@ class Agent extends RunnerBase_js_1.RunnerBase {
         // and `undefined` is the right answer there — it means "this conversation
         // recorded no folds", which is exactly true.
         this.pendingResumeFolded = cp.folded;
+        // The findings ledger beside it (9.101.0). Stashed whether or not THIS
+        // agent is armed: seed restores it only under `.findings()` (the deps
+        // gate), and an unarmed continuation consumes and ignores it — exactly
+        // like a `folded` field on an agent that never folds.
+        this.pendingResumeFindingsLedger = cp.findingsLedger;
         // The conversation's skill cursor (SG-C). Stashed unconditionally —
         // whether it is HONORED is seed's `restoreSkillCursor` gate, which reads
         // the mounted graph's `continuity` declaration; a checkpoint written by a
@@ -2460,6 +2501,19 @@ class Agent extends RunnerBase_js_1.RunnerBase {
                 getRunContext: getRunCtx,
             }));
         }
+        // Same wiring for `agentfootprint.findings.*` (9.101.0) — the ledger's two
+        // events, filed by `recordFindings` on scope. Attached only under
+        // `.findings()`: an unarmed agent gains no bridge, no listener and no
+        // per-event work, and `agent.on('agentfootprint.findings.*')` can only
+        // ever fire on an agent that could have filed a row.
+        if (this.findingsOptions !== undefined) {
+            attachObserver(new EmitBridge_js_1.EmitBridge({
+                id: 'agentfootprint.findings-bridge',
+                prefix: 'agentfootprint.findings.',
+                dispatcher,
+                getRunContext: getRunCtx,
+            }));
+        }
         for (const r of this.attachedRecorders) {
             // A recorder's OWN `delivery` field is more specific than the
             // agent-level default — footprintjs's options bag would override the
@@ -2797,6 +2851,34 @@ class Agent extends RunnerBase_js_1.RunnerBase {
         const state = this.getLastSnapshot()?.sharedState;
         return state?.unsupportedValues;
     }
+    /**
+     * The last run's findings ledger (9.101.0) — the model's OWN standings on
+     * its tool results, as `.findings()` recorded them: `basis` rows (what a
+     * call was for, declared before it ran), `standing` rows (`fact` with the
+     * assertions stood on, `open`, `ruled-out`, `noise` — the LAST row per
+     * `toolCallId` is the current reading; earlier ones are quotable history)
+     * and `conflict` rows (two stood-on readings that disagree, witnesses by
+     * identity). Undefined when the agent has no `.findings()` OR the model
+     * declared nothing — never an empty array standing in for "no findings",
+     * and an id with no standing row is undeclared, never `open`.
+     *
+     * Detached from the execution record (`structuredClone`), so a caller may
+     * keep or mutate it without touching the run's state.
+     *
+     * @example
+     * ```ts
+     * await agent.run({ message: 'which port is down?' });
+     * const current = new Map<string, string>();
+     * for (const row of agent.findings() ?? []) {
+     *   if (row.kind === 'standing') current.set(row.toolCallId, row.standing);
+     * }
+     * ```
+     */
+    findings() {
+        const ledger = this.getLastSnapshot()?.sharedState
+            ?.findingsLedger;
+        return ledger === undefined ? undefined : structuredClone(ledger);
+    }
     /** The last run's answer checks, detached from its execution record.
      * Undefined means no terminal validation ran, never an implicit pass. */
     answerValidation() {
@@ -3049,6 +3131,20 @@ class Agent extends RunnerBase_js_1.RunnerBase {
                 this.pendingResumeFolded = undefined;
                 return f;
             },
+            // The findings ledger (9.101.0): the arm, the serve mode it puts on the
+            // record (the `forcedOutputToolName` precedent — a build-time constant
+            // the rebuild reads instead of the receipt), and the continued
+            // conversation's rows, all under the one gate — an unarmed agent hands
+            // seed exactly the deps object it always did.
+            ...(this.findingsOptions !== undefined && {
+                findings: true,
+                findingsServe: this.findingsOptions.serve ?? 'ledger-and-facts',
+                consumePendingResumeFindingsLedger: () => {
+                    const l = this.pendingResumeFindingsLedger;
+                    this.pendingResumeFindingsLedger = undefined;
+                    return l;
+                },
+            }),
             // The conversation's inherited skill cursor (SG-C). Consumed (cleared)
             // on every run; HONORED only when the mounted graph declared
             // `continuity: 'conversation'` — the same one-option-one-behavior gate
@@ -3109,6 +3205,9 @@ class Agent extends RunnerBase_js_1.RunnerBase {
         // name uniqueness; produces the dispatch map.
         const { registryByName, toolSchemas, toolDeclaringSkills, toolClaimants } = (0, buildToolRegistry_js_1.buildToolRegistry)(registry, this.injections, {
             hasArtifactStore: artifactStore !== undefined,
+            // The reserved-argument refusal (9.101.0) — only when the ledger is
+            // armed may a registry tool's own `_findings` be refused.
+            ...(this.findingsOptions !== undefined && { findings: true }),
         });
         // A statically registered tool that declares `wants` on an agent with no
         // store is configuration that lies: every call would be refused at
@@ -3371,6 +3470,9 @@ class Agent extends RunnerBase_js_1.RunnerBase {
             ...(budget?.tools !== undefined && { budgetCap: budget.tools }),
             // Steps (9.18.0): per-step narrowing + banner + the skip_step offer.
             ...(stepPlanFor !== undefined && { stepPlanFor }),
+            // The findings ledger (9.101.0): the ONE decoration site is inside this
+            // slot; the gate rides in value-conditionally.
+            ...(this.findingsOptions !== undefined && { findings: true }),
         });
         // callLLM extracted to ./agent/stages/callLLM.ts (v2.11.2). Same
         // late-binding pattern as seed for toolSchemas (computed below).
@@ -3379,6 +3481,18 @@ class Agent extends RunnerBase_js_1.RunnerBase {
                 this.evidenceGate.posture !== 'assist' && {
                 hasEvidenceRecovery: true,
             }),
+            // The findings ledger (9.101.0): the choice seam and `postValidate`
+            // read peeled args / content under `findings`; the SERVING (step 3) —
+            // the ledger piece after the recovery piece, the wire-only collapse of
+            // judged results — rides `hasFindingsLedger` with its mode, the same
+            // value seed records as the run constant `findingsServe`. One gate,
+            // the `hasEvidenceRecovery` grammar: an unarmed agent hands the stage
+            // exactly the deps it always did and reads no new key.
+            ...(this.findingsOptions !== undefined && {
+                findings: true,
+                hasFindingsLedger: true,
+                findingsServe: this.findingsOptions.serve ?? 'ledger-and-facts',
+            }),
             ...(this.answerValidationConfig !== undefined && { suppressDraftTokens: true }),
             // The receipt's salt (9.88.0) — read per call, like seed's own accessor.
             getRunId: () => this.currentRunContext?.runId,
@@ -3513,7 +3627,11 @@ class Agent extends RunnerBase_js_1.RunnerBase {
         // exactly the arguments it always did — and `buildRouteDeciderStage`'s
         // no-judge fast path still returns the very function reference every
         // pre-9.83.0 chart was given.
-        this.noticePriorTurnEvidence && this.evidenceGate !== undefined ? true : undefined);
+        this.noticePriorTurnEvidence && this.evidenceGate !== undefined ? true : undefined, 
+        // THE ANSWER TURN'S STANDINGS (9.101.0) — the same value-conditional
+        // trailing positional, for the same reason: an unarmed agent hands the
+        // builder exactly the arguments it always did.
+        this.findingsOptions !== undefined ? true : undefined);
         const routeDecider = this.answerValidationConfig === undefined
             ? baseRouteDecider
             : (0, answerValidation_js_1.withAnswerValidation)(baseRouteDecider, this.answerValidationConfig, this.outputSchemaParser, artifactStore, () => this.consentOutstanding.size > 0);
@@ -3529,6 +3647,9 @@ class Agent extends RunnerBase_js_1.RunnerBase {
             // contract to read it (9.61.0) — value-conditional, so every other
             // agent commits exactly what it always did.
             ...(this.claimContract !== undefined && { collectClaimFacts: true }),
+            // The findings ledger (9.101.0) — the peel, the basis row and the
+            // previous batch's standings all live in this handler under this gate.
+            ...(this.findingsOptions !== undefined && { findings: true }),
             // THE WRITE SEAM (9.77.0) — `empty-lookup`. Handed the SAME harvested
             // map callLLM reads at the choice seam, so the two stages agree by
             // construction about which calls are armed. Value-conditional on both