agentfootprint 9.74.0 → 9.76.0

package/AGENTS.md

@@ -524,7 +524,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 — 108 typed events across 24 domains
+### Observability — 109 typed events across 24 domains
 
 ```typescript
 agent.on('agentfootprint.context.injected', (e) =>

package/CHANGELOG.md

@@ -7,6 +7,132 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [9.76.0] - 2026-08-28
+
+### Added
+
+- **`runbookAsTool` — turn a written procedure into a tool whose every answer
+  is evidence.** Triage is the most-used agent job in a business: run the
+  standing procedure, come back with a verdict somebody can act on. The first
+  production tool of that shape hand-rolled ~800 lines of envelope around a
+  footprintjs chart — a coverage ledger merging every inner source's own
+  ledger, a rule-version stamp on every sentence, capped verdict rows beside a
+  pre-rendered table, and the recorded walk that lets a reader CHECK the
+  verdict instead of trusting it. `runbookAsTool` is that envelope as one
+  declaration bag; the smallest legal call is `{ name, description,
+  procedure }` and it still yields the honest spine.
+
+  **The mandatory honesty spine**, on every answer whatever the runbook's
+  shape: `af_coverage` (three lists + a sentence naming the rule set and
+  version, with every inner tool's ledger folded upward), `af_provenance`
+  re-emitted FIRST (a seeded source's confession survives composition),
+  `rule_version` (or the honest `'undeclared'`), and the recorded walk as an
+  artifact ticket — new kind **`recording/chart-walk`** beside
+  `recording/run`, with `chartWalkPutInput` beside `recordingPutInput`. The
+  walk descriptor carries truthful counters, the declared projection (over
+  the cap, the CONTROL FLOW survives — stages, forks, and every `condition`
+  entry with its decide() evidence — never a head slice that keeps four
+  hundred writes and drops every decision), and a `walk_segment` discriminant
+  (`'full'` today; the wire is ready for resumed segments before gates land).
+  A failed mint costs the ticket, never the answer.
+
+  **The optional verdict projection**, selected by `resultKind: 'verdict/*'`:
+  rows off the chart's `verdicts` state key, ONE cap for the structured list
+  and the rendered table, truthful `rows_shown/rows_total/rows_complete`, and
+  `verdict_meanings` GENERATED from the decider's declared branches plus the
+  rule labels this run's evidence carried — never hand-restated, so a rule
+  change and its meaning change on the same day. Three outcomes, honestly: a
+  clean envelope; an inner absence passed through VERBATIM (the framework
+  still reads it as an absence); and `declined` rows counted into the ledger
+  as not-checked ground.
+
+  `flowchartAsTool` stays for compatibility (its `resultMapper` users stay
+  put, byte-identical); its stale pause message now names the runbook
+  program's gate phase instead of a version that shipped years ago.
+
+- **`ctx.tools` — a tool's body can call other registered tools through the
+  run's own dispatch.** The `procedure` factory is invoked per call with the
+  agent's dispatch (static + skill-carried tools; ToolProvider-delivered
+  tools are invisible — there is no build-time list, the stated 9.72.0
+  caveat), so stages compose registered sources instead of importing modules
+  and building a second query stack. Inner calls run with `hasArtifacts:
+  false` (one answer, one ticket — never competing chips), a derived
+  toolCallId naming the outer call, `needs` resolved on the fail-closed
+  non-interactive path, and `checkIn`/`wants` tools refused BY NAME (an inner
+  call cannot pause, and must never silently skip a consent gate).
+
+- **`composedOf` + `gates` on `defineTool`.** A composed tool names its
+  ingredient tools; the drift gate runs at AGENT BUILD — the one moment the
+  catalog is complete — so a renamed ingredient fails the build by name, not
+  the first 3 a.m. run. `gates` declares a procedure that can raise an
+  approval gate (read by composition-time checks that must keep a gating tool
+  out of a fan-out branch). Both pass the declaration bar (consumer-side
+  rails read them; nothing governs execution) and travel the MCP `_meta` bag
+  in both directions, judged on ingest by the same exported asserts
+  `defineTool` uses.
+
+## [9.75.0] - 2026-08-28
+
+### Added
+
+- **Grounded numbers: the staged-refs nudge, and a revise correction that
+  names the route.** The field failure this closes, from a consumer's recorded
+  run: four tool results carried real numbers, a compute tool that could sum
+  them was registered — with `wants` declared over the staged dataset kind —
+  and the app's prompt said to use it. The model summed the numbers in its
+  head anyway and stated the total; the evidence gate recorded *"appears in no
+  tool result"* and the answer shipped, because the posture only observed. The
+  app patched it with more prose. The library-shaped fix is two mechanisms it
+  already owns, on the one dial it already has:
+
+  **`nudge: true` on `.namesAndNumbersFromEvidence()`** — when an iteration's
+  context holds a tool result staged by reference (an `artifacts.placement`
+  ticket) AND a tool the model can currently call declares `wants` over that
+  ticket's kind, ONE short line is appended at the very END of that request,
+  naming the refs and the spender tool by its registered name: derived numbers
+  come from the tool, not from mental arithmetic. Composed entirely from
+  declarations (`Tool.resultKind`, `Tool.wants`, matched by the exact-string
+  law dispatch uses — never by tool name); no prose surface for apps. The
+  placement is the point: the measured failure was recency — the app's own
+  instruction sat at the top of a long context and the numbers at the bottom,
+  so this one sits beside the data. Request-only (never history, so it never
+  enters the gate's exempt corpus), recomposed per iteration so it exists
+  exactly while both conditions hold, judged against the tools REALLY served
+  this call (the wrap-up's withheld surface arms nothing). Each firing lands
+  as `agentfootprint.agent.grounding_nudged` (event 109) with refs and tools
+  as data — the line's one record, since the line itself is not conversation.
+
+  ```ts
+  const agent = Agent.create({ provider, model, artifacts: { store, placement } })
+    .tool(exportRows) // resultKind: 'dataset/rows' — staged over the threshold
+    .tool(compute) //    wants: { dataset: 'dataset/rows' } — the declared spender
+    .namesAndNumbersFromEvidence({ posture: 'guard', nudge: true })
+    .build();
+  ```
+
+  **The guarantee stays the postures the gate has had since 9.35.0** — the
+  existing value extraction is THE detector, unchanged: `'assist'` records,
+  `'guard'` allows the one bounded revision then delivers with both attempts
+  on the record, `'rails'` refuses with `UnsupportedValuesError`. What the
+  revision gains: when the flagged turn holds staged refs a served `wants`
+  tool can spend, the correction now names them — *"pass 'art_…'
+  (dataset/rows) to `compute` — compute the number there and answer with what
+  it returns"* — inside the authored frame, so the quoted values still come
+  last and the exempt-corpus fence is untouched. The `revision-asked`
+  `evidence_checked` event carries the same facts additively (`stagedRefs`,
+  `spenderTools`). Absent everything — no gate, `nudge` unset, or no
+  `wants`-declaring tool — every request, record and correction keeps its
+  exact bytes, pinned by test.
+
+### Changed
+
+- **A `guard`/`rails` agent that also registers a `wants`-declaring tool will
+  see its evidence correction gain the refs clause above when staged refs are
+  in context.** That is the fix, not a side effect: a correction that says
+  "call the tool that provides it" without naming WHICH tool over WHICH ref
+  leaves the model to head-math again. Agents without a `wants` tool — or
+  without staged refs in the flagged turn — keep the exact 9.35.0 sentence.
+
 ## [9.74.0] - 2026-08-27
 
 ### Added

package/CLAUDE.md

@@ -17,45 +17,50 @@ not in this table, search `src/index.ts` for the nearest noun before writing cod
 
 | If you are about to build… | It is | Where | Since |
 |---|---|---|---|
+| 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) + `walk {cap}` (default 500; over-cap ⇒ control-flow projection, declared) + `composedOf` (drift-checked at agent BUILD) + kept `recorders`/`keepRecord`/`keepRecordLimit`/`redact`; reserved state keys `verdicts`/`coverage`/`report`; inner `absent()` passes through VERBATIM unless the call said `allowAbsent`; walk kind `recording/chart-walk` + `walk_segment` discriminant | `src/core/runbook/` | 9.76.0 |
+| calling ANOTHER registered tool from inside a tool's `execute` — composition over the agent's own dispatch map instead of importing the module and building a second query stack | `agentToolDispatch` + `ctx.tools` (ToolDispatch has/call) — sees static and skill-carried tools, NEVER ToolProvider-delivered ones (no build-time list, the 9.72.0 caveat); inner calls get the outer facts with hasArtifacts false and a derived toolCallId, `needs` resolved fail-closed non-interactively, `checkIn` and `wants` tools refused by name, no nested dispatch; declare ingredients via `composedOf` (and `gates` for a pausing procedure) — both travel MCP `_meta` | `src/core/agent/toolDispatch.ts` | 9.76.0 |
 | a tool returning numbers WITH the caveats that make them honest — interval/aggregation grain, is-it-a-counter, when the world was measured, which ground was NOT covered — as typed data the model reads compactly and the record keeps whole | `semantic()` + `tools.semantics_declared` (model sees `semanticsForModel` projection; `coverage` field absorbed by the coverage()/absent() channel) | `src/lib/semantics/` | 9.53.0 |
-| a build gate that refuses a triage/inventory tool that forgot its caveats, by tool name and field name | `checkSemantics` + `defineTool({ resultClass })` + bin `agentfootprint-check-semantics` | `src/lib/semantics/check.ts` | 9.53.0 |
+| a build gate that refuses a triage/inventory tool that forgot its caveats, by tool name and field name | `checkSemantics` + `defineTool({ resultClass })` (`'triage'`/`'inventory'`, the closed set) + bin `agentfootprint-check-semantics` | `src/lib/semantics/check.ts` | 9.53.0 |
 | an agent that runs out of `maxIterations` mid-task handing back a HALF-SENTENCE as its answer — and nothing saying the budget ran out | `wrapUpAtMaxIterations` (default ON) + `WRAP_UP_INSTRUCTION` + `agent.budget_exhausted` + `stoppedEarly.wrappedUp` | `src/core/agent/stages/wrapUp.ts` | 9.56.0 |
+| the conversation outgrowing the context window — dropping, summarizing or token-budgeting old turns, every removal on the record (the three refusal rows below all guard this window) | `.window()` + `slidingWindow` / `summarizeOldest` (= `.compaction()`) / `tokenBudget` + `keepRecentTurns` (default 6) + `thresholdTokens` (required, deliberately no default) + `retain: 'conversation'` (default) / `'discard'` | `src/core/agent/window/` | 7.17.0 |
 | keeping the user's own request in context while the window shrinks — the task's anchor, un-droppable by every window strategy including one you wrote | `'current-request'` refusal + `currentRequestIndexOf` + `WindowStrategyInput.currentRequestIndex` | `src/core/agent/window/currentRequest.ts` | 9.55.0 |
-| the window evicting the EVIDENCE while keeping the task — the tool result carrying the only valid ids leaves, and the model invents one that has never existed | `keepLastToolResults` (default 2) + `'last-tool-result'` refusal + `toolResultPinsOf` + `WindowRecord.observations` (what was kept, and its exact char cost) | `src/core/agent/window/lastToolResult.ts` | 9.57.0 |
+| the window evicting the EVIDENCE while keeping the task — the tool result carrying the only valid ids leaves, and the model invents one that has never existed | `keepLastToolResults` (default 2; `0`/`false` disables) + `'last-tool-result'` refusal + `toolResultPinsOf` + `WindowRecord.observations` (what was kept, and its exact char cost) | `src/core/agent/window/lastToolResult.ts` | 9.57.0 |
 | telling the model WHICH tools' results a drop took, so it re-calls instead of reconstructing from memory — and filing the same fact on the record even when no notice was authored | `droppedToolNames` + the notice's tool sentence + `WindowRecord.droppedObservations` | `src/core/agent/window/toolNames.ts` | 9.57.0 |
-| an instruction that SAYS a run-time number rather than only gating on it ("you are on action 25 of 30") — with the library owning absence, so never "23 of undefined" and never a fabricated zero | `promptTemplate` + the closed `TEMPLATE_FACTS` vocabulary + `skipped: 'unknown-fact'` + `Injection.templated` | `src/lib/injection-engine/promptTemplate.ts` | 9.57.0 |
+| an instruction that SAYS a run-time number rather than only gating on it ("you are on action 25 of 30") — with the library owning absence, so never "23 of undefined" and never a fabricated zero | `promptTemplate` + the closed `TEMPLATE_FACTS` vocabulary (`action`/`actionBudget`/`actionsRemaining`) + `skipped: 'unknown-fact'` + `Injection.templated` | `src/lib/injection-engine/promptTemplate.ts` | 9.57.0 |
 | an injection predicate that can see how much of the action budget is left | `InjectionContext.maxIterations` / `.iterationsRemaining` + `iterationsRemainingOf` (the ONE denominator, shared with the cache decision) | `src/lib/iterationBudget.ts` | 9.57.0 |
 | report progress from inside a tool — "hop 3 of 12 done", said mid-call while a long-running `execute` is still working (the record was otherwise atomic: tool_start, silence, tool_end) | `ctx.progress` + `agentfootprint.stream.tool_progress` | `src/core/tools.ts` | 9.52.0 |
-| show tool progress to the user — a mid-call report reaching the live status line / chat bubble, not just the record (`message` shown verbatim, capped; otherwise an honest generic line, never a payload dump) | `selectStatus` + `progressMessageOf` + `tool.progress` templates | `src/recorders/observability/status/statusTemplates.ts` | 9.54.0 |
+| show tool progress to the user — a mid-call report reaching the live status line / chat bubble, not just the record (`message` shown verbatim, capped at 120 chars with the cut stated; otherwise an honest generic line, never a payload dump) | `selectStatus` + `progressMessageOf` + `tool.progress` templates | `src/recorders/observability/status/statusTemplates.ts` | 9.54.0 |
 | declaring which skills connect — the SkillMap as one named thing (the agent that mounts it is the SkillWalker; there is deliberately no walker class) | `defineSkillMap` + `SkillMap` (permanent reference-equal aliases of `skillGraph`/`SkillGraph`) | `src/lib/injection-engine/skillGraph.ts` | 9.51.0 |
-| guarding a skill transition on state or a tool result's fields — a route condition as DATA (comparable, drawable, evidence-recorded), not an opaque predicate | `guard:` + `compileGuard` + `guard-unsatisfiable` | `src/lib/injection-engine/skillGuard.ts` | 9.51.0 |
+| guarding a skill transition on state or a tool result's fields — a route condition as DATA (comparable, drawable, evidence-recorded), not an opaque predicate | `guard:` + `compileGuard` (ops `'eq'`/`'ne'`/`'gt'`/`'gte'`/`'lt'`/`'lte'`/`'in'`/`'notIn'`) + `guard-unsatisfiable` | `src/lib/injection-engine/skillGuard.ts` | 9.51.0 |
 | seeing the skill map in a recording — the author's nodes + edges (guards included) as DATA, never parsed from prose or inferred from fired hops | `skill.graph_declared` + `buildSkillGraphDeclared` | `src/core/agent/skillGraphDeclared.ts` | 9.50.0 |
 | "where could the run go next?" — the reachable skill set at every cursor move, typed on the move itself | `cursorMove.reachable` + `reachableSkills` | `src/lib/injection-engine/buildInjectionEngineSubflow.ts` | 9.50.0 |
 | putting the ASSEMBLED system prompt in the recording — the exact string the model read (opt-in; default OFF is a privacy decision) | `recordSystemPrompt` | `src/core/agent/types.ts` | 9.50.0 |
-| a typed HITL prompt — let a person pick from a list, choose a range, use a real control instead of typing prose | `AskComponent` | `src/core/askComponent.ts` | 9.24.0 |
-| carrying WHAT the person chose back, with what they could see | `DecisionValue` | `src/core/checkin.ts` | 9.47.0 |
-| archiving a finished run — filing it, attaching it to a bug report, feeding it to an analysis tool | `persistRecording` + `RecordingEnvelope` | `src/recorders/observability/recordingEnvelope.ts` | 9.48.0 |
-| packaging a run for a HUMAN to file — a zip whose evidence is the archive envelope, plus host facts and a readable transcript | `exportBugReport` | `src/lib/bug-report/build.ts` | — |
+| a typed HITL prompt — let a person pick from a list, choose a range, use a real control instead of typing prose | `AskComponent` + `componentId` (consumer-registered vocabulary, opaque here) + inline `props` + `propsRef` (artifact claim ticket for the big half) | `src/core/askComponent.ts` | 9.24.0 |
+| carrying WHAT the person chose back, with what they could see | `DecisionValue` (`kind` / `value` / `from?` + `coverage {seen, total, filter?}`) | `src/core/checkin.ts` | 9.47.0 |
+| archiving a finished run — filing it, attaching it to a bug report, feeding it to an analysis tool | `persistRecording` + `RecordingEnvelope` + `run.complete` (required) + `privacy.mode` (`'full'` today; `'structure-only'`/`'redacted'` refuse by name) | `src/recorders/observability/recordingEnvelope.ts` | 9.48.0 |
+| packaging a run for a HUMAN to file — a zip whose evidence is the archive envelope, plus host facts and a readable transcript | `exportBugReport` + `include` (the consent seam; left-out units are counted in `manifest.excluded`) + `warnOverBytes` (default 20 MB) | `src/lib/bug-report/build.ts` | — |
 | writing archived runs somewhere — a directory, one JSON file per run | `fileRecordingSink` + `RecordingSink` | `src/recorders/observability/fileRecordingSink.ts` | 9.48.0 |
 | declaring an agent's whole setup as one named, versioned thing — a preset, a template, a blueprint, "the support agent we all use" | `defineAgentRecipe` + `AgentBuilder.recipe()` | `src/recipes/` | 9.48.0 |
 | naming your own branches and nodes — which prefix is reserved, and telling framework plumbing from consumer structure in a trace | `RESERVED_SUBFLOW_PREFIX` + `isReservedSubflowSegment` | `src/conventions.ts` | 9.49.0 |
-| keeping a large tool result out of the model's context | `artifacts` + `wants` + `placement` | `src/artifacts/` | 9.21.0 |
+| keeping a large tool result out of the model's context | `artifacts` (bare store, or `{ store, placement: { maxInlineChars }, recordings }` — `placement` omitted ⇒ never placed; `recordings: true` / `{ label }`, default off) + `wants` + `placement` | `src/artifacts/` | 9.21.0 |
 | the ticket placement just minted being REFUSED by your own `wants` argument as a kind mismatch — because the mint says `tool-result/<toolName>` and your consumer says `dataset/rows` | `Tool.resultKind` + `placedResultKind(toolName, declared?)` (the mint speaks the consumer's vocabulary; the exact-match matcher is untouched) | `src/artifacts/placement.ts` | 9.70.0 |
 | letting the UI draw an artifact without the model naming a component | `registerArtifactComponent` (in the `agentfootprint-lens` package) | — | — |
 | finding which tools the model keeps writing by hand | `agentfootprint.tools.code_run` + `codeShape` | `src/core/codeRunnerTool.ts` | 9.46.0 |
-| a skill wrongly activated by a keyword staying loaded for the whole turn — suspending/parking a map's prompt + tools when its contribution goes unused, WITHOUT touching its cursor, and re-engaging it on evidence | `.maps()` + `advanceEngagement` + `agentfootprint.map.engaged/parked` + skip reason `'parked'` | `src/maps/` | 9.58.0 |
+| a skill wrongly activated by a keyword staying loaded for the whole turn — suspending/parking a map's prompt + tools when its contribution goes unused, WITHOUT touching its cursor, and re-engaging it on evidence | `.maps({ renewalGrace })` (default 3) + `MountedMap.nonParkable` + `advanceEngagement` + `agentfootprint.map.engaged/parked` + skip reason `'parked'` | `src/maps/` | 9.58.0 |
 | a value that must say how it knows itself — an unknown count that can never render as zero | `Claim<T>` (`known`/`unknown`/`notApplicable`) | `src/lib/claim/claim.ts` | 9.58.0 |
 | asking a debugging model "what did this run contradict itself about, and why?" — the Context Integrity findings, joined to the step that filed them | `find_context_errors` | `src/lib/trace-toolpack/traceToolpack.ts` | 9.61.0 |
+| the model inventing an id or a reading that no tool ever returned — a deterministic fabrication detector on the final answer, with a posture for how hard it pushes back | `.namesAndNumbersFromEvidence()` + `posture` (`'assist'` record+flag, the default / `'guard'` one revision then ship flagged / `'rails'` refuse instead) + `shapes` + `exempt` + `minDigits` (default 4) + `nudge` (default off) | `src/core/agent/evidence/` | 9.35.0 |
 | counting a HUMAN-VERIFIED value as ground for the choice-seam check — the person clicked a row, the app verified the cells against the artifact, and the id the model takes from that selection is not fabricated; the source label travels onto the record | `externalGrounds` + `ExternalGround` + `external_ground_used` | `src/integrity/unsupported-argument/check.ts` | 9.72.0 |
-| a tool answering "I looked and found nothing", routably | `absent` | `src/core/agent/coverage/absent.ts` | 9.43.0 |
-| stating what a clean answer does NOT rule out | `coverage` | `src/core/agent/coverage/ledger.ts` | 9.43.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/core/agent/coverage/absent.ts` | 9.43.0 |
+| stating what a clean answer does NOT rule out | `coverage` + the declaration `{ checked, not_checked?, cannot_cover? }` | `src/core/agent/coverage/ledger.ts` | 9.43.0 |
 | minting one of those shapes from a tool that is NOT JavaScript — the canonical note sentences and reserved marker keys as DATA, so a Python/Go/Rust sidecar reads a file instead of regex-scraping `dist/esm` (which a consumer really did) | `canonical-notes.json` at the package root + the `./canonical-notes.json` exports entry, GENERATED from the built barrel by `scripts/gen-canonical-notes.mjs` | `scripts/gen-canonical-notes.mjs` | 9.70.0 |
-| proving a session store really honours the port | `runSessionLifecycleConformance` | `src/hosting/conformance/` | 9.37.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 |
-| making a caller-supplied id safe for a backend | `encodeIdentityField` | `src/memory/identity/encode.ts` | 9.40.0 |
-| scoping a skill's tools so they reach the model only while it is active | `toolsFromActiveSkill` | `src/core/agent/toolsFromActiveSkill.ts` | 9.43.0 |
+| 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` | `src/core/checkin.ts` | 9.24.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 |
 
 **One law before you add a mapping.** Any function turning caller data into a KEY,
 a namespace, a filename or an index entry must be injective, and its collision
@@ -133,7 +138,7 @@ Traps: `src/observability/` holds the finder IMPLEMENTATIONS (canonical home; `d
 - **Recordings as artifacts (9.26.0)**: `artifacts: { store, recordings: true | { label } }`. `Agent.startRunRecording()` calls the SAME `recordRun` (before `createExecutor` — `attach()` collects for the executor not yet built); `fileRunRecording` mints AFTER `finalizeResult`, awaited, every failure contained to `artifacts.refused`. Pure half in artifacts/recordingArtifact.ts; payload is the recording's JSON TEXT (a live snapshot handed to an in-process store would be a live view into a finished run). No new wire op — `artifact-get` serves it.
 - **Code staging-in (9.26.0)**: `CodeSession.stageInputs?(inputs) → StagedCodeInput[]` — OPTIONAL, feature-detected via `canStageCodeInputs`, and its contract is TWO promises: the payloads are readable at the returned paths, AND every later `execute` exposes the manifest as `STAGED_INPUTS_ENV` (`AF_STAGED_INPUTS`, `name → path`). `CodeInput.name` is the MANIFEST KEY (the wants arg name, so a static description can name it) and `fileName` is the on-disk name — separate fields so the two cannot drift. `codeRunnerTool({ wants })` composes the schema properties + the description clause and refuses BY NAME on a non-staging runner. Implemented by localCodeRunner only.
 - **Repeated-call nudge (9.26.0)**: `core/agent/repeatedCall.ts` (pure `noteRepeatedCall` + `repeatedCallLedgers()`) + the ONE batch-loop hook in toolCalls. Fingerprints (FNV-1a) of stable-stringified args and the tool's OWN delivered result — never values. **The counters are NOT tracked state**: they live in a bounded run-keyed map held by `buildToolCallsHandler` and keyed by `deps.currentRun().runId`, so a turn that repeats nothing is byte-identical in state, commit log, narrative and recordings (a scope key would have changed all four for every agent that merely upgraded); the repeat itself rides `agentfootprint.tools.repeated_call`, the emit channel per-attempt facts belong on. A resume mints a new runId ⇒ counting restarts. Fires at the SECOND identical landing, once. `AgentOptions.repeatedCallNudge: false` disables (threaded value-conditionally; ON is the default). Deliberately NOT applied on the pause-resume dispatch paths.
-- **Evidence gate (9.35.0)** — `.namesAndNumbersFromEvidence({ posture, shapes, exempt, minDigits })`: every name/number in the final answer must appear in a `role:'tool'` result. Postures reuse the routing VOCABULARY (`assist`|`guard`|`rails`) as a SEPARATE option — routing authority ≠ evidence discipline, and overloading `skillGraphCascade.strictness` would deny "strict routing, loose evidence". Wiring is the stepNudge blast radius verbatim: `ResolvedEvidenceGate` (builder-resolved, refusals at the CALL SITE) → Agent ctor trailing param → `buildRouteDeciderStage`'s 4th arg (`judgeEvidence` runs LAST of the three judges — schema > steps > evidence — and NOT on a denied or schema-exhausted answer) → `evidenceRecheckStage` branch (`{loopTo}`, mounted only for a revising posture) → `STAGE_IDS.EVIDENCE_RECHECK` + BOUNDARY_LOCAL_IDS + milestoneFor. TWO deps flags, and the second is the one a reader misses: `evidenceRecheckStage` (branch) AND `hasEvidenceGate` (bubbles `systemPromptInjections` out of sf-llm-call in the GROUPED chart — without it the gate flags the app's own prompt). Per-check facts ride `agentfootprint.agent.evidence_checked` (emit channel); only the terminal verdict is committed (`unsupportedValues`), because the boundary raises off it. `UnsupportedValuesError` joins the TERMINAL-typed-error list in `run()`'s catch (a verdict is not a crash — no retry handle for a wall).
+- **Evidence gate (9.35.0)** — `.namesAndNumbersFromEvidence({ posture, shapes, exempt, minDigits })`: every name/number in the final answer must appear in a `role:'tool'` result. Postures reuse the routing VOCABULARY (`assist`|`guard`|`rails`) as a SEPARATE option — routing authority ≠ evidence discipline, and overloading `skillGraphCascade.strictness` would deny "strict routing, loose evidence". Wiring is the stepNudge blast radius verbatim: `ResolvedEvidenceGate` (builder-resolved, refusals at the CALL SITE) → Agent ctor trailing param → `buildRouteDeciderStage`'s 4th arg (`judgeEvidence` runs LAST of the three judges — schema > steps > evidence — and NOT on a denied or schema-exhausted answer) → `evidenceRecheckStage` branch (`{loopTo}`, mounted only for a revising posture) → `STAGE_IDS.EVIDENCE_RECHECK` + BOUNDARY_LOCAL_IDS + milestoneFor. TWO deps flags, and the second is the one a reader misses: `evidenceRecheckStage` (branch) AND `hasEvidenceGate` (bubbles `systemPromptInjections` out of sf-llm-call in the GROUPED chart — without it the gate flags the app's own prompt). Per-check facts ride `agentfootprint.agent.evidence_checked` (emit channel); only the terminal verdict is committed (`unsupportedValues`), because the boundary raises off it. `UnsupportedValuesError` joins the TERMINAL-typed-error list in `run()`'s catch (a verdict is not a crash — no retry handle for a wall). **Grounded numbers (9.75.0)** rides the SAME dial: `nudge: true` arms the staged-refs nudge — `toolWantsOf` harvests `Tool.wants` beside the `toolGrounding` harvest in `Agent.buildChart` (same ToolProvider blindness), callLLM appends ONE request-only late line when a placed ticket's kind matches a SERVED `wants` tool (judged on `registeredToolSchemas`, so wrap-up's withheld surface arms nothing; history untouched ⇒ never in the exempt corpus), recorded as `agent.grounding_nudged`; and the recheck correction names the same refs+spender via `buildEvidenceCorrection`'s third arg — threaded whenever a `wants` tool exists, NOT gated on `nudge`, clause INSIDE the authored frame so `isLibraryAuthoredTurn`'s prefix match and values-last both hold.
 - **Coverage primitives (this release)** — `absent()` / `coverage()`, both copied from FIELD USE. THE argument is the direction of the error: a *nothing-found* misread as an *outage* costs an investigation, an *outage* misread as *nothing-found* declares a system healthy that was never checked — so the two must not share a shape. Blast radius, and it is the `resultCeiling` radius verbatim: `readCoverageResult` called by `declareCoverage` at BOTH execute boundaries in toolCalls.ts (batch loop + `resolveCredentialAndExecute`), on the UNWRAPPED content and BEFORE the ceiling. FOUR downstream changes and no more: (1) `ToolResultStatus` gained a SEVENTH word `'absent'` — routable by `onToolStatus`, because folding it into `'failure'` is the confusion itself and into `'success'` leaves nothing to route on; (2) two events (`tools.absent`, `tools.coverage_declared`); (3) tracked `AgentState.coverageDeclared` — a limit is a fact about the ANSWER, not about an attempt, which is why it is state and the repeated-call counters are not; (4) the evidence corpus indexes an absence's COVERAGE ONLY (`coverage/evidence.ts` — a failed lookup is the cheapest laundering machine, and `absent()` would have made it cheaper: this is frames.ts's argument on the tool side). Deliberately UNCHANGED: no `error: true`, no retry, no refusal, no gate flag. Survival into the answer is `.limitsTravelWithTheAnswer()` → `attachCoverageLimits` dep → BOTH builders swap the final branch's first stage for `prepareFinalWithLimitsStage` (same id, same position). It APPENDS rather than judges: a check for "did the model state its limits?" needs a second model to decide what counts, which is what evidence/README.md forbids.
 - **Out-of-budget wrap-up (9.56.0)** — `wrapUpAtMaxIterations` (AgentOptions, default ON, `repeatedCallNudge`'s opt-out grammar): the FOURTH Route branch, and the SchemaRetry mechanism verbatim — `STAGE_IDS.WRAP_UP` + same `{loopTo}`, so the last call is one ordinary turn with its own `iteration_start`/`llm_start`/`cost.tick`. Two things are its own: (1) the tools are WITHHELD at REQUEST ASSEMBLY in callLLM (`scope.wrapUpAsked`, the `schemaTool` seam's mirror — the schema tool still rides, so an output contract survives), which is what makes the call terminal BY CONSTRUCTION rather than by a rule, and is why it is exempt from `maxIterations`; (2) the CONDITIONAL MOUNT is on the agent having a TOOL SURFACE (`registryByName.size > 0 || externalToolProvider`) — a limit only cuts a turn short when tool calls were pending, so a toolless agent's chart must not grow a box that can never run. `decideBranch` treats a spent wrap-up as cut-short for every downstream judge (`toolCalls.length > 0 || scope.wrapUpAsked`), or a step nudge / evidence revision would loop past the limit that fired. `wrapUpAsked` is deliberately NOT seeded — a turn that finishes inside its budget commits the exact key set it always did. The record is FOUR channels: `stoppedEarly` (now with `wrappedUp`, corrected on the pass after so `answerWasEmpty` describes the answer the caller GOT), `cost.limit_hit` (unchanged), the new `agent.budget_exhausted {action: 'wrapped-up'|'cut-short'}`, and an optional `turn_end.stoppedEarly` projection.
 - **Closed seams**: Agent chart internals (AgentChartDeps not exported — extend via injections/tools/memory/thinking, never by adding a ReAct stage); ContextSlot (3 slots fixed); ProviderKind factory; dormant ports with no consumer (ContextSourceAdapter, EmbeddingProvider, RiskDetector — adapters/types.ts only); reserved tool names under selfExplain — 8.16.0 made the list DERIVED: `TRACE_TOOL_NAMES` (traceToolpack.ts, 11 names since 9.61.0: run_overview/find_context_errors/find_in_trace/trace_node/trace_slice/backtrack/who_wrote/get_value/inspect_tool_call/inspect_tool_run/read_narrative) is what AgentBuilder.ts:~1560 reserves in inline mode (`explain_run` in delegate mode), so a NEW toolpack tool joins ONE list and the reservation follows — but it must ALSO join the lazy template's mounted set (lazyToolpack builds over `{narrative: [], events: []}` so the catalog shape is fixed at build time) and the count assertion in test/lib/trace-toolpack/selfExplainAgent.test.ts. **8.17.0 `inspect_tool_run`** is the descent THROUGH the tool boundary: `flowchartAsTool({ keepRecord: true })` files each invocation's record in a bounded LRU store (lib/trace-toolpack/innerRunRecords.ts) keyed by the executing `ctx.toolCallId`, riding the `Tool` under the `INNER_RUN_RECORDS` registry symbol; `AgentBuilder.build()` → `collectInnerRuns(registry, injections)` → `SelfExplainSource.getInnerRuns` → `TraceToolpackArtifacts.innerRuns`. The inner views are the pack ITSELF re-run over `openRecording(record.recording)` — do not add a second query implementation. Provider-delivered tools are NOT collected (no build-time list); inner runtimeStageIds are a SEPARATE namespace and only `inspect_tool_run` accepts them. **9.61.0 `find_context_errors`** is the Context Integrity read-out: it reads `agentfootprint.integrity.context_error` + `…disposition` off the artifacts' EVENT TAIL (never re-running a check), joins each finding to the step it was filed at, and mounts UNCONDITIONALLY — a tool that vanished with the tail could not say the evidence channel is ABSENT, which is the one sentence this family forbids collapsing into "no errors found".
@@ -145,7 +150,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/** → 108 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/** → 109 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).
 - **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/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));
 ```
 
-**108 typed events across 24 domains.** Two subscription shapes and no third:
+**109 typed events across 24 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/index.js

@@ -11,7 +11,7 @@
  * this folder for the one-job map and the import direction.
  */
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.placedToolResult = exports.placedResultKind = exports.isPlacedToolResult = exports.assertArtifactPlacement = exports.runArtifactStoreConformance = exports.runArtifactStoreCase = exports.formatArtifactStoreReport = exports.artifactStoreConformance = exports.UnserializableRecordingError = exports.RECORDING_MEDIA_TYPE = exports.RECORDING_ARTIFACT_KIND = exports.recordingPutInput = exports.presentArtifact = exports.PRESENT_TOOL_NAME = exports.wantsNeedsStoreRefusal = exports.resolveToolWants = exports.assertToolWants = exports.unconfiguredArtifacts = exports.bindArtifacts = exports.collectStream = exports.canStreamArtifacts = exports.canPutArtifactStream = exports.canGetArtifactStream = exports.bytesAsStream = exports.assertStreamBytes = exports.gcsArtifacts = exports.s3Artifacts = exports.UnreadableArtifactStoreError = exports.sqliteArtifacts = exports.UnreadableArtifactFileError = exports.fileArtifacts = exports.DEFAULT_IN_MEMORY_ARTIFACT_RETENTION = exports.inMemoryArtifacts = exports.mintArtifactRef = exports.isArtifactRef = exports.ARTIFACT_REF_PREFIX = exports.UnknownParentRefError = exports.InvalidArtifactError = exports.ArtifactIntegrityError = void 0;
+exports.placedToolResult = exports.placedResultKind = exports.isPlacedToolResult = exports.assertArtifactPlacement = exports.runArtifactStoreConformance = exports.runArtifactStoreCase = exports.formatArtifactStoreReport = exports.artifactStoreConformance = exports.UnserializableRecordingError = exports.chartWalkPutInput = exports.CHART_WALK_ARTIFACT_KIND = exports.RECORDING_MEDIA_TYPE = exports.RECORDING_ARTIFACT_KIND = exports.recordingPutInput = exports.presentArtifact = exports.PRESENT_TOOL_NAME = exports.wantsNeedsStoreRefusal = exports.resolveToolWants = exports.assertToolWants = exports.unconfiguredArtifacts = exports.bindArtifacts = exports.collectStream = exports.canStreamArtifacts = exports.canPutArtifactStream = exports.canGetArtifactStream = exports.bytesAsStream = exports.assertStreamBytes = exports.gcsArtifacts = exports.s3Artifacts = exports.UnreadableArtifactStoreError = exports.sqliteArtifacts = exports.UnreadableArtifactFileError = exports.fileArtifacts = exports.DEFAULT_IN_MEMORY_ARTIFACT_RETENTION = exports.inMemoryArtifacts = exports.mintArtifactRef = exports.isArtifactRef = exports.ARTIFACT_REF_PREFIX = exports.UnknownParentRefError = exports.InvalidArtifactError = exports.ArtifactIntegrityError = void 0;
 var types_js_1 = require("./types.js");
 Object.defineProperty(exports, "ArtifactIntegrityError", { enumerable: true, get: function () { return types_js_1.ArtifactIntegrityError; } });
 Object.defineProperty(exports, "InvalidArtifactError", { enumerable: true, get: function () { return types_js_1.InvalidArtifactError; } });
@@ -54,6 +54,8 @@ var recordingArtifact_js_1 = require("./recordingArtifact.js");
 Object.defineProperty(exports, "recordingPutInput", { enumerable: true, get: function () { return recordingArtifact_js_1.recordingPutInput; } });
 Object.defineProperty(exports, "RECORDING_ARTIFACT_KIND", { enumerable: true, get: function () { return recordingArtifact_js_1.RECORDING_ARTIFACT_KIND; } });
 Object.defineProperty(exports, "RECORDING_MEDIA_TYPE", { enumerable: true, get: function () { return recordingArtifact_js_1.RECORDING_MEDIA_TYPE; } });
+Object.defineProperty(exports, "CHART_WALK_ARTIFACT_KIND", { enumerable: true, get: function () { return recordingArtifact_js_1.CHART_WALK_ARTIFACT_KIND; } });
+Object.defineProperty(exports, "chartWalkPutInput", { enumerable: true, get: function () { return recordingArtifact_js_1.chartWalkPutInput; } });
 Object.defineProperty(exports, "UnserializableRecordingError", { enumerable: true, get: function () { return recordingArtifact_js_1.UnserializableRecordingError; } });
 // The battery a store must pass to CLAIM the port, exported beside the port
 // itself so an out-of-tree store imports the check the same way it imports the

package/dist/artifacts/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/artifacts/index.ts"],"names":[],"mappings":";AAAA;;;;;;;;;;GAUG;;;AAEH,uCAkBoB;AAjBlB,kHAAA,sBAAsB,OAAA;AACtB,gHAAA,oBAAoB,OAAA;AACpB,iHAAA,qBAAqB,OAAA;AAgBvB,yCAAkF;AAAzE,gHAAA,mBAAmB,OAAA;AAAE,0GAAA,aAAa,OAAA;AAAE,4GAAA,eAAe,OAAA;AAE5D,+DAKgC;AAJ9B,yHAAA,iBAAiB,OAAA;AACjB,4IAAA,oCAAoC,OAAA;AAItC,uDAI4B;AAH1B,iHAAA,aAAa,OAAA;AACb,+HAAA,2BAA2B,OAAA;AAG7B,2DAK8B;AAJ5B,qHAAA,eAAe,OAAA;AACf,kIAAA,4BAA4B,OAAA;AAI9B,mDAAwE;AAA/D,6GAAA,WAAW,OAAA;AACpB,qDAA2E;AAAlE,+GAAA,YAAY,OAAA;AACrB,+CAUwB;AATtB,iHAAA,iBAAiB,OAAA;AACjB,6GAAA,aAAa,OAAA;AACb,oHAAA,oBAAoB,OAAA;AACpB,oHAAA,oBAAoB,OAAA;AACpB,kHAAA,kBAAkB,OAAA;AAClB,6GAAA,aAAa,OAAA;AAKf,iDAUyB;AATvB,8GAAA,aAAa,OAAA;AACb,sHAAA,qBAAqB,OAAA;AASvB,uCAOoB;AANlB,2GAAA,eAAe,OAAA;AACf,4GAAA,gBAAgB,OAAA;AAChB,kHAAA,sBAAsB,OAAA;AAKxB,2CAMsB;AALpB,+GAAA,iBAAiB,OAAA;AACjB,6GAAA,eAAe,OAAA;AAKjB,+DAMgC;AAL9B,yHAAA,iBAAiB,OAAA;AACjB,+HAAA,uBAAuB,OAAA;AACvB,4HAAA,oBAAoB,OAAA;AACpB,oIAAA,4BAA4B,OAAA;AAG9B,4EAA4E;AAC5E,+EAA+E;AAC/E,6EAA6E;AAC7E,mCAAmC;AACnC,mDAagC;AAZ9B,oHAAA,wBAAwB,OAAA;AACxB,qHAAA,yBAAyB,OAAA;AACzB,gHAAA,oBAAoB,OAAA;AACpB,uHAAA,2BAA2B,OAAA;AAU7B,+CAOwB;AANtB,uHAAA,uBAAuB,OAAA;AACvB,kHAAA,kBAAkB,OAAA;AAClB,gHAAA,gBAAgB,OAAA;AAChB,gHAAA,gBAAgB,OAAA"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/artifacts/index.ts"],"names":[],"mappings":";AAAA;;;;;;;;;;GAUG;;;AAEH,uCAkBoB;AAjBlB,kHAAA,sBAAsB,OAAA;AACtB,gHAAA,oBAAoB,OAAA;AACpB,iHAAA,qBAAqB,OAAA;AAgBvB,yCAAkF;AAAzE,gHAAA,mBAAmB,OAAA;AAAE,0GAAA,aAAa,OAAA;AAAE,4GAAA,eAAe,OAAA;AAE5D,+DAKgC;AAJ9B,yHAAA,iBAAiB,OAAA;AACjB,4IAAA,oCAAoC,OAAA;AAItC,uDAI4B;AAH1B,iHAAA,aAAa,OAAA;AACb,+HAAA,2BAA2B,OAAA;AAG7B,2DAK8B;AAJ5B,qHAAA,eAAe,OAAA;AACf,kIAAA,4BAA4B,OAAA;AAI9B,mDAAwE;AAA/D,6GAAA,WAAW,OAAA;AACpB,qDAA2E;AAAlE,+GAAA,YAAY,OAAA;AACrB,+CAUwB;AATtB,iHAAA,iBAAiB,OAAA;AACjB,6GAAA,aAAa,OAAA;AACb,oHAAA,oBAAoB,OAAA;AACpB,oHAAA,oBAAoB,OAAA;AACpB,kHAAA,kBAAkB,OAAA;AAClB,6GAAA,aAAa,OAAA;AAKf,iDAUyB;AATvB,8GAAA,aAAa,OAAA;AACb,sHAAA,qBAAqB,OAAA;AASvB,uCAOoB;AANlB,2GAAA,eAAe,OAAA;AACf,4GAAA,gBAAgB,OAAA;AAChB,kHAAA,sBAAsB,OAAA;AAKxB,2CAMsB;AALpB,+GAAA,iBAAiB,OAAA;AACjB,6GAAA,eAAe,OAAA;AAKjB,+DASgC;AAR9B,yHAAA,iBAAiB,OAAA;AACjB,+HAAA,uBAAuB,OAAA;AACvB,4HAAA,oBAAoB,OAAA;AACpB,gIAAA,wBAAwB,OAAA;AACxB,yHAAA,iBAAiB,OAAA;AACjB,oIAAA,4BAA4B,OAAA;AAI9B,4EAA4E;AAC5E,+EAA+E;AAC/E,6EAA6E;AAC7E,mCAAmC;AACnC,mDAagC;AAZ9B,oHAAA,wBAAwB,OAAA;AACxB,qHAAA,yBAAyB,OAAA;AACzB,gHAAA,oBAAoB,OAAA;AACpB,uHAAA,2BAA2B,OAAA;AAU7B,+CAOwB;AANtB,uHAAA,uBAAuB,OAAA;AACvB,kHAAA,kBAAkB,OAAA;AAClB,gHAAA,gBAAgB,OAAA;AAChB,gHAAA,gBAAgB,OAAA"}

package/dist/artifacts/recordingArtifact.js

@@ -33,10 +33,18 @@
  *     than at whatever reads it next.
  */
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.recordingPutInput = exports.UnserializableRecordingError = exports.RECORDING_MEDIA_TYPE = exports.RECORDING_ARTIFACT_KIND = void 0;
+exports.chartWalkPutInput = exports.recordingPutInput = exports.UnserializableRecordingError = exports.RECORDING_MEDIA_TYPE = exports.CHART_WALK_ARTIFACT_KIND = exports.RECORDING_ARTIFACT_KIND = void 0;
 /** The consumer vocabulary a run recording is stored under. One kind, exact
  *  match — the same rule every `wants` declaration is judged by. */
 exports.RECORDING_ARTIFACT_KIND = 'recording/run';
+/**
+ * The consumer vocabulary a chart WALK is stored under (9.76.0) — one row per
+ * execution step of a runbook's inner chart, with the decider evidence
+ * sentences in the `condition` rows. Namespaced by what it IS (`recording/…`,
+ * beside `recording/run`), never by what produced it: a walk is a recording
+ * projection, not a dataset that happens to mention stages.
+ */
+exports.CHART_WALK_ARTIFACT_KIND = 'recording/chart-walk';
 /** The media type a recording is minted with. */
 exports.RECORDING_MEDIA_TYPE = 'application/json';
 /**
@@ -85,4 +93,42 @@ function recordingPutInput(recording, facts = {}) {
     };
 }
 exports.recordingPutInput = recordingPutInput;
+/**
+ * Turn one chart walk into the `put` input that stores it under
+ * {@link CHART_WALK_ARTIFACT_KIND}.
+ *
+ * Pure, and serialized to JSON TEXT at the mint for exactly the reasons the
+ * run recording is (see the file header): a walk row must never be a live
+ * view into engine memory, and a walk JSON cannot carry could not cross any
+ * wire either.
+ *
+ * @throws UnserializableRecordingError when the rows cannot be
+ *   JSON-serialized. Walk rows are projected to plain data upstream, so this
+ *   firing means the projection let a live value through — fail at the mint,
+ *   loudly.
+ */
+function chartWalkPutInput(rows, facts = {}) {
+    let text;
+    try {
+        text = JSON.stringify(rows) ?? '';
+    }
+    catch (err) {
+        throw new UnserializableRecordingError(err instanceof Error ? err.message : String(err));
+    }
+    if (text === '') {
+        throw new UnserializableRecordingError('it serializes to nothing');
+    }
+    const origin = {
+        ...(facts.runId !== undefined && { runId: facts.runId }),
+        ...(facts.toolCallId !== undefined && { toolCallId: facts.toolCallId }),
+    };
+    return {
+        kind: exports.CHART_WALK_ARTIFACT_KIND,
+        mediaType: exports.RECORDING_MEDIA_TYPE,
+        data: text,
+        label: facts.label ?? (facts.toolName !== undefined ? `${facts.toolName} walk` : 'chart walk'),
+        ...(Object.keys(origin).length > 0 && { origin }),
+    };
+}
+exports.chartWalkPutInput = chartWalkPutInput;
 //# sourceMappingURL=recordingArtifact.js.map

package/dist/artifacts/recordingArtifact.js.map

@@ -1 +1 @@
-{"version":3,"file":"recordingArtifact.js","sourceRoot":"","sources":["../../src/artifacts/recordingArtifact.ts"],"names":[],"mappings":";AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgCG;;;AAIH;oEACoE;AACvD,QAAA,uBAAuB,GAAG,eAAe,CAAC;AAEvD,iDAAiD;AACpC,QAAA,oBAAoB,GAAG,kBAAkB,CAAC;AAoBvD;;;;;GAKG;AACH,MAAa,4BAA6B,SAAQ,KAAK;IAC5C,IAAI,GAAG,8BAAuC,CAAC;IAExD,YAAY,MAAc;QACxB,KAAK,CACH,0DAA0D,MAAM,mBAAmB;YACjF,kFAAkF;YAClF,oFAAoF;YACpF,kFAAkF,CACrF,CAAC;QACF,IAAI,CAAC,IAAI,GAAG,8BAA8B,CAAC;IAC7C,CAAC;CACF;AAZD,oEAYC;AAED;;;;;;;;GAQG;AACH,SAAgB,iBAAiB,CAC/B,SAAkB,EAClB,QAA4B,EAAE;IAE9B,IAAI,IAAY,CAAC;IACjB,IAAI,CAAC;QACH,IAAI,GAAG,IAAI,CAAC,SAAS,CAAC,SAAS,CAAC,IAAI,EAAE,CAAC;IACzC,CAAC;IAAC,OAAO,GAAG,EAAE,CAAC;QACb,MAAM,IAAI,4BAA4B,CAAC,GAAG,YAAY,KAAK,CAAC,CAAC,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC,CAAC;IAC3F,CAAC;IACD,IAAI,IAAI,KAAK,EAAE,EAAE,CAAC;QAChB,MAAM,IAAI,4BAA4B,CAAC,0BAA0B,CAAC,CAAC;IACrE,CAAC;IACD,OAAO;QACL,IAAI,EAAE,+BAAuB;QAC7B,SAAS,EAAE,4BAAoB;QAC/B,IAAI,EAAE,IAAI;QACV,KAAK,EAAE,KAAK,CAAC,KAAK,IAAI,CAAC,KAAK,CAAC,KAAK,KAAK,SAAS,CAAC,CAAC,CAAC,OAAO,KAAK,CAAC,KAAK,EAAE,CAAC,CAAC,CAAC,eAAe,CAAC;QAC1F,GAAG,CAAC,KAAK,CAAC,KAAK,KAAK,SAAS,IAAI,EAAE,MAAM,EAAE,EAAE,KAAK,EAAE,KAAK,CAAC,KAAK,EAAE,EAAE,CAAC;KACrE,CAAC;AACJ,CAAC;AApBD,8CAoBC"}
+{"version":3,"file":"recordingArtifact.js","sourceRoot":"","sources":["../../src/artifacts/recordingArtifact.ts"],"names":[],"mappings":";AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgCG;;;AAIH;oEACoE;AACvD,QAAA,uBAAuB,GAAG,eAAe,CAAC;AAEvD;;;;;;GAMG;AACU,QAAA,wBAAwB,GAAG,sBAAsB,CAAC;AAE/D,iDAAiD;AACpC,QAAA,oBAAoB,GAAG,kBAAkB,CAAC;AAoBvD;;;;;GAKG;AACH,MAAa,4BAA6B,SAAQ,KAAK;IAC5C,IAAI,GAAG,8BAAuC,CAAC;IAExD,YAAY,MAAc;QACxB,KAAK,CACH,0DAA0D,MAAM,mBAAmB;YACjF,kFAAkF;YAClF,oFAAoF;YACpF,kFAAkF,CACrF,CAAC;QACF,IAAI,CAAC,IAAI,GAAG,8BAA8B,CAAC;IAC7C,CAAC;CACF;AAZD,oEAYC;AAED;;;;;;;;GAQG;AACH,SAAgB,iBAAiB,CAC/B,SAAkB,EAClB,QAA4B,EAAE;IAE9B,IAAI,IAAY,CAAC;IACjB,IAAI,CAAC;QACH,IAAI,GAAG,IAAI,CAAC,SAAS,CAAC,SAAS,CAAC,IAAI,EAAE,CAAC;IACzC,CAAC;IAAC,OAAO,GAAG,EAAE,CAAC;QACb,MAAM,IAAI,4BAA4B,CAAC,GAAG,YAAY,KAAK,CAAC,CAAC,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC,CAAC;IAC3F,CAAC;IACD,IAAI,IAAI,KAAK,EAAE,EAAE,CAAC;QAChB,MAAM,IAAI,4BAA4B,CAAC,0BAA0B,CAAC,CAAC;IACrE,CAAC;IACD,OAAO;QACL,IAAI,EAAE,+BAAuB;QAC7B,SAAS,EAAE,4BAAoB;QAC/B,IAAI,EAAE,IAAI;QACV,KAAK,EAAE,KAAK,CAAC,KAAK,IAAI,CAAC,KAAK,CAAC,KAAK,KAAK,SAAS,CAAC,CAAC,CAAC,OAAO,KAAK,CAAC,KAAK,EAAE,CAAC,CAAC,CAAC,eAAe,CAAC;QAC1F,GAAG,CAAC,KAAK,CAAC,KAAK,KAAK,SAAS,IAAI,EAAE,MAAM,EAAE,EAAE,KAAK,EAAE,KAAK,CAAC,KAAK,EAAE,EAAE,CAAC;KACrE,CAAC;AACJ,CAAC;AApBD,8CAoBC;AAgBD;;;;;;;;;;;;;GAaG;AACH,SAAgB,iBAAiB,CAC/B,IAAwB,EACxB,QAA4B,EAAE;IAE9B,IAAI,IAAY,CAAC;IACjB,IAAI,CAAC;QACH,IAAI,GAAG,IAAI,CAAC,SAAS,CAAC,IAAI,CAAC,IAAI,EAAE,CAAC;IACpC,CAAC;IAAC,OAAO,GAAG,EAAE,CAAC;QACb,MAAM,IAAI,4BAA4B,CAAC,GAAG,YAAY,KAAK,CAAC,CAAC,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC,CAAC;IAC3F,CAAC;IACD,IAAI,IAAI,KAAK,EAAE,EAAE,CAAC;QAChB,MAAM,IAAI,4BAA4B,CAAC,0BAA0B,CAAC,CAAC;IACrE,CAAC;IACD,MAAM,MAAM,GAAG;QACb,GAAG,CAAC,KAAK,CAAC,KAAK,KAAK,SAAS,IAAI,EAAE,KAAK,EAAE,KAAK,CAAC,KAAK,EAAE,CAAC;QACxD,GAAG,CAAC,KAAK,CAAC,UAAU,KAAK,SAAS,IAAI,EAAE,UAAU,EAAE,KAAK,CAAC,UAAU,EAAE,CAAC;KACxE,CAAC;IACF,OAAO;QACL,IAAI,EAAE,gCAAwB;QAC9B,SAAS,EAAE,4BAAoB;QAC/B,IAAI,EAAE,IAAI;QACV,KAAK,EAAE,KAAK,CAAC,KAAK,IAAI,CAAC,KAAK,CAAC,QAAQ,KAAK,SAAS,CAAC,CAAC,CAAC,GAAG,KAAK,CAAC,QAAQ,OAAO,CAAC,CAAC,CAAC,YAAY,CAAC;QAC9F,GAAG,CAAC,MAAM,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC,MAAM,GAAG,CAAC,IAAI,EAAE,MAAM,EAAE,CAAC;KAClD,CAAC;AACJ,CAAC;AAxBD,8CAwBC"}

package/dist/core/Agent.js

@@ -105,6 +105,7 @@ const skillTools_js_1 = require("../lib/injection-engine/skillTools.js");
 const skillSteps_js_1 = require("../lib/injection-engine/skillSteps.js");
 const stepNudge_js_1 = require("./agent/stages/stepNudge.js");
 const evidenceRecheck_js_1 = require("./agent/stages/evidenceRecheck.js");
+const stagedRefs_js_1 = require("./agent/stagedRefs.js");
 const wrapUp_js_1 = require("./agent/stages/wrapUp.js");
 const gate_js_1 = require("./agent/evidence/gate.js");
 const errors_js_2 = require("./agent/evidence/errors.js");
@@ -2901,6 +2902,36 @@ class Agent extends RunnerBase_js_1.RunnerBase {
                 }
             }
         }
+        // The composedOf drift gate (9.76.0), judged HERE and not at defineTool —
+        // the one moment the catalog is complete. A tool that declares its
+        // ingredients (`composedOf`, the runbookAsTool law) whose ingredient was
+        // renamed or never registered fails the BUILD by name, instead of failing
+        // its first run inside a stage. Tools delivered by a ToolProvider are
+        // invisible to this check (no build-time list — the 9.72.0 caveat), so
+        // with a provider configured an unmatched name is a dev-mode heads-up
+        // rather than a refusal: the ingredient may genuinely arrive at dispatch.
+        for (const [composedName, registered] of registryByName) {
+            for (const ingredient of registered.composedOf ?? []) {
+                if (registryByName.has(ingredient))
+                    continue;
+                if (this.externalToolProvider !== undefined) {
+                    if ((0, footprintjs_2.isDevMode)()) {
+                        // eslint-disable-next-line no-console
+                        console.warn(`[agentfootprint] tool '${composedName}' declares composedOf ingredient ` +
+                            `'${ingredient}', which is not in the static catalog. A ToolProvider is ` +
+                            `configured, so it may arrive at dispatch — but provider-delivered tools ` +
+                            `cannot be drift-checked at build. If '${ingredient}' is static, this is ` +
+                            `the rename the check exists to catch.`);
+                    }
+                    continue;
+                }
+                throw new Error(`Agent: tool '${composedName}' declares composedOf ingredient '${ingredient}', ` +
+                    `but no tool of that name is registered on this agent. The declaration names ` +
+                    `the tools its procedure calls through ctx.tools, and an ingredient that is ` +
+                    `not in the dispatch map fails at its first inner call — refused at build ` +
+                    `instead. Register '${ingredient}' (or fix the name in composedOf).`);
+            }
+        }
         // Late-bind toolSchemas into the seed stage's deps (the factory was
         // built earlier with a getter; this resolves the actual value).
         toolSchemasResolved = toolSchemas;
@@ -3041,6 +3072,11 @@ class Agent extends RunnerBase_js_1.RunnerBase {
             .filter(([, tool]) => tool.argumentsFrom !== undefined)
             .map(([name, tool]) => [name, tool.argumentsFrom]));
         this.integrityDanglingPresent = toolGrounding.size > 0;
+        // The staged-refs join's other half (grounded numbers): `Tool.wants` by
+        // tool name, harvested the same way and with the same ToolProvider caveat.
+        // Consumed only by the evidence gate (the callLLM nudge and the recheck
+        // correction), so an agent without the gate never reads it.
+        const toolWants = (0, stagedRefs_js_1.toolWantsOf)(registryByName);
         const toolsSubflow = (0, buildToolsSlot_js_1.buildToolsSlot)({
             tools: toolSchemas,
             ...(toolOwners.size > 0 && { toolOwners }),
@@ -3074,6 +3110,10 @@ class Agent extends RunnerBase_js_1.RunnerBase {
             // The declared argument-ground edges (9.60.0) — value-conditional, so
             // an agent whose tools declare none runs the exact bytes it always did.
             ...(toolGrounding.size > 0 && { toolGrounding }),
+            // The staged-refs nudge (grounded numbers) — armed only when the dial
+            // is ON and a registered tool declares `wants`; otherwise the stage
+            // reads nothing new and every request keeps its exact bytes.
+            ...(this.evidenceGate?.nudge === true && toolWants.size > 0 && { toolWants }),
             // The external-ground door (9.72.0) — value-conditional for the same
             // reason: no provider, no key, byte-identical corpus assembly.
             ...(this.externalGrounds !== undefined && { externalGrounds: this.externalGrounds }),
@@ -3319,7 +3359,19 @@ class Agent extends RunnerBase_js_1.RunnerBase {
             ...(this.evidenceGate !== undefined && {
                 hasEvidenceGate: true,
                 ...(this.evidenceGate.posture !== 'assist' && {
-                    evidenceRecheckStage: (0, evidenceRecheck_js_1.buildEvidenceRecheckStage)(this.evidenceGate),
+                    evidenceRecheckStage: (0, evidenceRecheck_js_1.buildEvidenceRecheckStage)(this.evidenceGate, 
+                    // The staged-refs join (grounded numbers) — the correction names
+                    // the refs and the spender when the run declared both. Threaded
+                    // whenever a `wants` tool exists (not gated on `nudge`: a
+                    // revision that cannot say HOW to compute leaves the model to
+                    // head-math again); absent for every agent without one, so the
+                    // correction keeps its exact bytes.
+                    toolWants.size > 0
+                        ? {
+                            toolWants,
+                            staticToolNames: () => toolSchemasResolved.map((t) => t.name),
+                        }
+                        : undefined),
                 }),
             }),
             // Escalation (9.19.0): the grouped chart threads `skillEscalated`