agentfootprint 9.104.0 → 9.106.0

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 — 115 typed events across 25 domains
+### Observability — 119 typed events across 27 domains
 
 ```typescript
 agent.on('agentfootprint.context.injected', (e) =>

package/CHANGELOG.md

@@ -5,6 +5,138 @@ 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.106.0] - 2026-09-17
+
+### Added — the ontology: a declared map of what exists and where, never a way to fetch it
+
+- **`agentfootprint/ontology`** — a new door (the seventeenth): `defineOntology(spec)`
+  takes an `OntologySpec` — `nodes` (an `OntologyNode` per term: `meaning`,
+  `unit`, `aliases`, and the `sources` that hold it, each an
+  `OntologyNodeSource` with the registered tools that read it from there
+  (`via`) and the author's `coverage` sentence), `sources` (an
+  `OntologySource` per place data is held: `meaning`, `coverage`,
+  `configured` — a boolean the author wrote, or absent, which means unknown
+  and is never assumed) and `edges` (an `OntologyEdge`: `from`, `to`, the
+  author's `relation` word, `meaning`) — and returns an `Ontology`:
+  validated, detached, deep-frozen, with a `hash`. Every fault is refused
+  by name (an id that is not identifier-safe, an edge to a node nobody
+  declared, a node held by a source nobody declared, an empty or over-long
+  text, a repeated alias / `via` / edge, a count past `ONTOLOGY_LIMITS`). A
+  node with no source is legal: known, nowhere collected here.
+  `ontologyHash` fingerprints the five declared fields through the
+  receipt's own `stableJson` (key-order independent; edge order is part of
+  the identity).
+- **`.ontology(map)`** (`AgentOptions.ontology`, `AgentBuilder.ontology`;
+  once per agent, the option form goes through the same door). At
+  `.build()` every `via` tool name is checked against the agent's tool
+  registry — a name no registry carries is refused, naming the ontology,
+  the tool, the node and the source. At run `seed` writes the whole map
+  ONCE as the run constant `AgentState.ontology` (`OntologyRecord`: `id`,
+  `version`, `hash`, `spec`), so the wire, the rebuild and a lens need
+  nothing but the record.
+- **The served piece.** Every model call is served ONE request-only system
+  piece composed by the pure `ontologyPiece` (`OntologyPiece`, `source:
+  'ontology'` — a new `ContextSource`): a constant header quoting the
+  context contract's `domainDefinitions`, `limitations` and `evidenceRefs`
+  meanings, then `nodes:`, `sources:`, `held by:`, `relations:` and `known,
+  not held here:` — every line the declaration's, nodes and sources sorted
+  by id, edges in declaration order, `ONTOLOGY_PIECE_LIMITS` lines per
+  section with the overflow stated, an empty section omitted, no per-call
+  byte (an unchanged map reuses the cached system prefix). Joined after the
+  recovery piece and before the findings piece — injections → recovery →
+  ontology → findings, fixed — never as an injection; hashed on the receipt
+  and rebuilt byte-equal by `servedAt` in both chart shapes (the grouped
+  chart crosses the key into `sf-llm-call` under the arm).
+- **The ask.** `ONTOLOGY_INSTRUCTION` (`ONTOLOGY_INSTRUCTION_ID`), an
+  always-on instruction the `outputSchema()` way: say which declared
+  source, tool or neighbouring node the map names for a need the results
+  did not meet — as a proposal, never as a claim that data exists there;
+  never invent a value from the map; report a node listed as known but not
+  held here as declared. Judged by `unprovable` in the model-facing
+  inventory, beside the piece.
+- **`agentfootprint.ontology.served`** `{ iteration, id, version, hash,
+  nodes, sources, edges }` — once per call that served the piece;
+  identities and numbers only. A new domain, `ontology`, with its
+  wildcard: 26 → 27 domains, 118 → 119 events.
+- **The law.** The library never decides that a node "has no data": absence
+  is the model's or the tool's to report; the map only lets the model SAY
+  where a need would be met. Nothing is executed or fetched through it;
+  nothing is inferred from it. An agent without `.ontology()` is
+  byte-identical to one built before the map existed — no key, no piece,
+  no instruction, no event (the 19 byte-identity references untouched; one
+  new reference `agent-ontology`). What the map is measured on — tool calls
+  before the honest answer on questions whose data is not collected, and
+  whether that answer names the source — is a bench on the first host after
+  the release, not here (`docs/design/2026-09-ontology.md`).
+
+## [9.105.0] - 2026-09-17
+
+### Added — tool choice by classifier: a second reading beside the model's call, and a narrowing dial
+
+- **`.toolChoice({ classifier, serve, alwaysServe })`** (`AgentOptions.toolChoice`,
+  `AgentBuilder.toolChoice`). At every model call the tools slot asks the
+  classifier ONE `choice` question — id `TOOL_CHOICE_QUESTION` (`'tool'`),
+  criteria the tools about to be served by name with their own descriptions
+  (the merged wire minus the always-served doors), state the user's message
+  plus the active skill id — and files a `ToolChoiceRow` under
+  `AgentState.toolChoices` BEFORE the call: `offered`, `ranked` (the
+  provider's distribution as sent, highest first, an unscored tool absent —
+  never padded, never renormalised), `chosen` (the provider's own pick,
+  absent when it named nothing offered), `confidence`, `usage`, `latencyMs`,
+  `served` (the names the slot committed) and `narrowed`. After the reply
+  `callLLM` files a `ToolChoiceOutcomeRow`: `called` (the model's tool calls
+  in order, empty on an answer), `firstAgrees` (`chosen === called[0]`,
+  absent when either is absent) and `miss` (the names called outside a
+  narrowed served list). A failed classifier call is a `ToolChoiceErrorRow`
+  (status, message, latency) and the full set is served — fail open, never
+  fail narrow. The model's call is the emission; the pick is a second
+  reading marked `source: 'classifier'`, never substituted, never merged.
+- **Advisory by default** (`serve: 'all'`): the wire is byte for byte the
+  unarmed agent's — every request equal, every receipt equal; the record
+  gains the rows and nothing else.
+- **The narrowing dial** (`serve: { top: N }`): the slot commits the
+  classifier's top-N plus the doors — `read_skill`, `list_skills`,
+  `skip_step`, `present` (`ALWAYS_SERVED_TOOLS`) and the app's `alwaysServe`
+  — in the merged wire's order, at the ONE decoration site, so
+  `dynamicToolSchemas`, the receipt's `tools.schemaHashes` and
+  `servedAt(k).tools.schemas` are the narrowed list by construction (no new
+  `SERVED_GAPS` kind; `toolsInjections` follows the served set). The full
+  wire is served with the reason on the row (`narrowedSkipped`:
+  `NarrowSkipReason`) when the classifier failed or scored fewer than N
+  (`unavailable`), fewer than N + 1 candidates were offered (`too-few`), the
+  previous call's outcome carried a miss (`after-miss`) or the call is the
+  out-of-budget wrap-up (`wrap-up`). A miss — the model naming a
+  narrowed-away tool — is recorded on the outcome row and answered by the
+  dispatcher's off-wire path exactly as before (`tools.answered_off_wire`);
+  the next call serves the full wire. `reactMode: 'classic'` is refused at
+  build (the `.findings()` precedent).
+- **Three events**, `agentfootprint.tool_choice.picked` (`chosen`,
+  `confidence`, `offered` and `served` as counts, `narrowed`,
+  `narrowedSkipped`, `latencyMs`, tokens), `agentfootprint.tool_choice.outcome`
+  (`called`, `firstAgrees`, `missed`) and `agentfootprint.tool_choice.failed`
+  (`status`, `latencyMs`) — identities, enums, numbers and a boolean only
+  (payloads `ToolChoicePickedPayload`, `ToolChoiceOutcomePayload`,
+  `ToolChoiceFailedPayload`); 115 → 118 typed events, 25 → 26 domains.
+- **Root exports**: `ToolChoiceRow`, `ToolChoiceErrorRow`,
+  `ToolChoiceOutcomeRow`, `ToolChoiceEntry`, `ToolChoiceLedger`,
+  `ToolChoiceScore`, `NarrowSkipReason`, `TOOL_CHOICE_QUESTION`,
+  `ALWAYS_SERVED_TOOLS`. The asker (`src/core/agent/toolChoice/pick.ts`) is
+  loaded through `import()` by the slot and is deliberately not exported.
+- **`npm run bench:tool-choice`** — the mock provider, one skill of eight
+  tools, six scripted steps, a scripted classifier ranking the right tool
+  first / second / a wrong pair, under `advisory` and `top-2`: `first-agrees`,
+  `misses`, `extra-calls`, `tools-slot-bytes` (from the receipt's
+  `requestMeasurement`), `pick-tokens`, `pick-latency-ms`; the cost line
+  first; exits non-zero if the unarmed twin's tools-slot bytes move or an
+  advisory row's differ from the twin's. On 2026-09-17: 1745 bytes unarmed
+  and on every advisory row, 743 under `top-2` with a right ranking, 1172
+  under a wrong pair (three misses, the full wire on the call after each,
+  zero extra calls).
+- Byte identity: the 18 unarmed references untouched; one new reference
+  `agent-tool-choice` (`test/core/tools/byte-identity.test.ts`), generated
+  alone. Design: `docs/design/2026-09-scored-choice.md` § Step 4; README:
+  `src/core/agent/toolChoice/README.md`.
+
 ## [9.104.0] - 2026-09-17
 
 ### Added — a calibrated judge beside the model's own standings

package/CLAUDE.md

@@ -68,6 +68,8 @@ not in this table, search `src/index.ts` for the nearest noun before writing cod
 | subscribing to every event in one domain at once | `DomainWildcard` | `src/events/dispatcher.ts` | 9.4.0 |
 | pausing a run for a person and resuming it later | `checkInApproved` / `checkInDeclined` (`{ by, note?, value? }`; a decline is NOT an abort — the model gets a "declined by human" tool result and adapts in-loop) | `src/core/checkin.ts` | 7.5.0 |
 | a SECOND source judging every tool result — a calibrated classifier asked what a result is worth for the declared proposition (never why the tool was called), its distribution and cost on the record beside the model's own standing, never merged, never served in its place (policy A) | `.findings({ judge })` + `Classifier` / `typesafe` / `mockClassifier` (`agentfootprint/classify`) + `JudgmentRow` / `JudgmentErrorRow` + `classifierScorer` (the scored entry choice, `agentfootprint/skill-graph`) | `src/classify/` | 9.104.0 |
+| a classifier's reading of WHICH TOOL beside every model call — the ranking, the pick and the cost on the record before the call, the model's call and the agreement after it; optionally the served list narrowed to the top-N plus the doors, on the committed record the receipt hashes and the served view rebuilds; a miss recorded and the full wire served next call, never a refusal, never an override | `.toolChoice({ classifier, serve, alwaysServe })` + `ToolChoiceRow` + `ToolChoiceOutcomeRow` + `ToolChoiceErrorRow` + `ALWAYS_SERVED_TOOLS` + `recordToolChoice` + `narrowServed` (events `agentfootprint.tool_choice.*`, bench `npm run bench:tool-choice`) | `src/core/agent/toolChoice/` | 9.105.0 |
+| a MAP of the domain the model can reason over when a result holds nothing — what each term IS (meaning, unit), how terms RELATE, which SOURCE holds a term (with the author's coverage sentence) and which registered TOOL reads it from there; declared once, validated against the tool registry at build, on the record as one run constant, served as one request-only system piece per call, never a fetch path and never inferred from | `defineOntology` + `.ontology(map)` (`AgentOptions.ontology`) + `AgentState.ontology` + `ontologyPiece` / `ONTOLOGY_INSTRUCTION` (`agentfootprint/ontology`) + `agentfootprint.ontology.served` | `src/ontology/` | 9.106.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
@@ -84,7 +86,7 @@ does not exist, so the table can go out of date by OMISSION but can never lie
 about what it names.
 
 ## Module map
-Entry points — SIXTEEN doors, and `package.json` `exports` is exhaustive, so a path not on this list does not resolve at all: `.` core API · `/providers` everything you plug a backend into (mock/anthropic/openai/bedrock/browser*, embedders, staticTools/gatedTools/skillScopedTools/mcpClient, thinking handlers, code runners) · `/memory` (defineMemory, MEMORY_TYPES, InMemoryStore, mockEmbedder, redis/agentcore/bedrockAgentMemory stores) · `/rag` index-time loaders/splitters/indexCorpus · `/cache` prompt caching (+ registerCacheStrategy; side-effectful, hence its own door) · `/observe` the whole watching story (recorders, recordRun, strategies + attach*, vendor sinks, run-autopsy finders, toSSE, status, locales) · `/events` typed event system · `/context` the injection engine (defineInjection/Skill/Fact/Instruction/Steering, decideSkill) · `/resilience` provider decorators + the reliability RULES · `/hosting` nodeHost/httpHost/standingAgent + session stores · `/security` permissions + tool credentials (it absorbed the old identity door) · `/reliability` the retained alias, kept ONLY because it is the sole home of the gate's `CircuitOpenError` · `/skill-graph` the framework-neutral routing layer · `/recipes` the declared unit of agent CONFIGURATION (defineAgentRecipe → `.recipe()`; authoring-time vocabulary, so it stays off the main barrel) · `/maps` the mount kernel's vocabulary (9.58.0: Claim<T> + the engagement lease machine + its renewal feed — pure data and pure functions, no run entry point; mounted via `.maps()`) · `/classify` the calibrated-classifier port (9.104.0: `Classifier`, `typesafe`, `mockClassifier`, `ClassifierError` — a backend that SCORES declared candidates; spent by `.findings({ judge })` and by `classifierScorer` on `/skill-graph`). 9.0.0 removed sixteen older paths (`/llm-providers`, `/injection-engine`, `/tool-providers`, `/strategies`, `/observability-providers`, `/identity`, `/stream`, `/thinking`, `/status`, `/locales`, `/debug`, `/debug/finders`, `/memory-providers`, `/embedders`, `/hosting-providers`, `/observability/contextError/finders`) — it removed PATHS, not code; each name still ships through the door that absorbed it. This list is pinned against `package.json` by test/api-conformance/documented-doors.test.ts, and the removed sixteen by subpath-exports.test.ts. **Main barrel does NOT export** mock/browser*/defineMemory/defineSkill/skillGraph/mcpClient/InMemoryStore — import from the doors above.
+Entry points — SEVENTEEN doors, and `package.json` `exports` is exhaustive, so a path not on this list does not resolve at all: `.` core API · `/providers` everything you plug a backend into (mock/anthropic/openai/bedrock/browser*, embedders, staticTools/gatedTools/skillScopedTools/mcpClient, thinking handlers, code runners) · `/memory` (defineMemory, MEMORY_TYPES, InMemoryStore, mockEmbedder, redis/agentcore/bedrockAgentMemory stores) · `/rag` index-time loaders/splitters/indexCorpus · `/cache` prompt caching (+ registerCacheStrategy; side-effectful, hence its own door) · `/observe` the whole watching story (recorders, recordRun, strategies + attach*, vendor sinks, run-autopsy finders, toSSE, status, locales) · `/events` typed event system · `/context` the injection engine (defineInjection/Skill/Fact/Instruction/Steering, decideSkill) · `/resilience` provider decorators + the reliability RULES · `/hosting` nodeHost/httpHost/standingAgent + session stores · `/security` permissions + tool credentials (it absorbed the old identity door) · `/reliability` the retained alias, kept ONLY because it is the sole home of the gate's `CircuitOpenError` · `/skill-graph` the framework-neutral routing layer · `/recipes` the declared unit of agent CONFIGURATION (defineAgentRecipe → `.recipe()`; authoring-time vocabulary, so it stays off the main barrel) · `/maps` the mount kernel's vocabulary (9.58.0: Claim<T> + the engagement lease machine + its renewal feed — pure data and pure functions, no run entry point; mounted via `.maps()`) · `/classify` the calibrated-classifier port (9.104.0: `Classifier`, `typesafe`, `mockClassifier`, `ClassifierError` — a backend that SCORES declared candidates; spent by `.findings({ judge })` and by `classifierScorer` on `/skill-graph`) · `/ontology` the declared map (9.106.0: `defineOntology`, `ontologyHash`, `ontologyPiece`, `ONTOLOGY_INSTRUCTION`, the shapes — what each term IS, how terms RELATE, which SOURCE holds a term and which registered TOOL reads it; pure data and pure functions, no run entry point, no fetch path; mounted via `.ontology()`, served as one request-only system piece per call). 9.0.0 removed sixteen older paths (`/llm-providers`, `/injection-engine`, `/tool-providers`, `/strategies`, `/observability-providers`, `/identity`, `/stream`, `/thinking`, `/status`, `/locales`, `/debug`, `/debug/finders`, `/memory-providers`, `/embedders`, `/hosting-providers`, `/observability/contextError/finders`) — it removed PATHS, not code; each name still ships through the door that absorbed it. This list is pinned against `package.json` by test/api-conformance/documented-doors.test.ts, and the removed sixteen by subpath-exports.test.ts. **Main barrel does NOT export** mock/browser*/defineMemory/defineSkill/skillGraph/mcpClient/InMemoryStore — import from the doors above.
 
 | src/ | one job |
 |---|---|
@@ -100,6 +102,7 @@ Entry points — SIXTEEN doors, and `package.json` `exports` is exhaustive, so a
 | recorders/core/ | bridges footprintjs events → typed EventDispatcher (ContextRecorder, EmitBridge, typedEmit) — auto-attached by Agent.createExecutor; most factories also exported via `/observe` for manual wiring (EmitBridge itself stays internal) |
 | recorders/observability/ | consumer recorders over the typed stream (RunStepRecorder, FlowchartRecorder, Status, Trace replay) + `recordRun` — THE producer of a recording `{snapshot, events, structure}` (the shape lens's `observeRecording` consumes; `structure` = `getSpec().buildTimeStructure`, which no snapshot carries). Anything that saves a run goes through it |
 | rag/ | (8.10.0, door `/rag`) index-TIME: `DocumentLoader` adapters (text/markdown/html zero-dep, pdf via lazy `unpdf`) + `Splitter` factories + `indexCorpus` — a REAL footprintjs chart whose commit log IS the indexing report. `defineRAG` deliberately stays on the MAIN barrel (run-time wiring); this door is the half that runs once, before any agent exists |
+| ontology/ | (9.106.0) the declared map — `defineOntology` (validate, detach, freeze, `ontologyHash` through the receipt's `stableJson`) + `serve.ts · ontologyPiece` (the ONE composer, called by `callLLM` and by `servedView.viewOf`; every line quotes the declaration under a constant header that quotes the context contract's three meanings) + `instruction.ts` (the always-on ask). Behind the `/ontology` door; `Agent.buildChart` checks every `via` tool name against `registryByName` at build; `seed` writes `AgentState.ontology` once; the grouped chart crosses the key into `sf-llm-call` under `hasOntology` |
 | lib/ | first-party sub-libraries: injection-engine/, context-bisect/ (localizeContextBug, toBacktrackTrace + sliceToBacktrackTrace — the atui board serializers), influence-core/, trace-toolpack/ (selfExplain; 6 tools incl. variable-first `backtrack(variable, element?)`), context-ledger/ (which pieces EARNED their tokens — post-run offers/uses/outcomes bookkeeping + demote-never-starve gates `ledgerToolGate`/`ledgerEntryScorer`/`ledgerGated`; grouped-mode folds sf-llm-call inner logs, unmeterable runs → undefined; /observe), mcp/, rag/, tool-lint/ |
 | memory/ | store/ (MemoryStore port) + pipeline presets + stages + beats/facts + causal/ (dev-only, TOP_K+search()-only) + wire/mountMemoryPipeline + retrieval/ (8.8.0: the `RetrievalStrategy` seam + `RetrievalEvidence`, the record a retrieval leaves — `topK()` is what every earlier release did unnamed) |
 | maps/ | (9.58.0, door `/maps`) the mount kernel: claim/ (`Claim<T>` honesty primitive) + engagement/ (lease machine `advanceEngagement` + renewal feed `renewalEvidenceOf` + vocabulary). Pure data/functions; the ONE framework hook is `ctx.parkedIds` in the evaluator (the `leaseActiveIds` mirror), fed by the Evaluate stage; state rides `AgentState.mapEngagement` as a TOP-LEVEL array (the StepPointerCarrier law) |
@@ -158,7 +161,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/** → 115 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).
+- **events/** → 119 typed events across 27 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

@@ -932,6 +932,8 @@ The flowchart, recorders, and tests don't change between dev and prod.
 - 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
+- Tool choice by classifier — `.toolChoice({ classifier, serve })` asks a calibrated classifier (`agentfootprint/classify`) at every model call which of the tools about to be served answers the current step, and files its ranking, its pick and its cost as a `pick` row beside the model's own call, then an `outcome` row after the reply (`firstAgrees`, any `miss`). The model's call is never overridden. `serve: { top: N }` narrows the served list to the classifier's top-N plus the doors (`read_skill`, `skip_step`, `present`, your `alwaysServe`), on the committed record the receipt hashes and `servedAt` rebuilds; a failed classifier serves the full set, a miss serves the full set on the next call. `npm run bench:tool-choice` measures agreement, misses and tools-slot bytes from the record. An agent without `.toolChoice()` is byte-identical
+- The ontology — `.ontology(map)` mounts a declared map of the domain (`defineOntology` on `agentfootprint/ontology`): what each term IS (meaning, unit), how terms RELATE, which SOURCE holds a term with the author's coverage sentence, and which registered TOOL reads it from there. A map, not a door — it provides no way to get data, nothing is fetched through it and the library infers nothing from it; it is on the record once as `AgentState.ontology`, served as one request-only system piece per call (every line the declaration's; a node nobody holds is `known, not held here`), hashed on the receipt and rebuilt by `servedAt`, and the model is asked to name the source or neighbouring node a need points at — as a proposal. `via` tool names are checked against the registry at build. An agent without `.ontology()` is byte-identical
 - 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));
 ```
 
-**115 typed events across 25 domains.** Two subscription shapes and no third:
+**119 typed events across 27 domains.** Two subscription shapes and no third:
 `'*'` (every event) and `'agentfootprint.<domain>.*'` (one domain). **`'agentfootprint.*'`
 is not a pattern** — TypeScript rejects it, and at runtime it would match nothing.
 

package/dist/core/Agent.js

@@ -287,6 +287,21 @@ class Agent extends RunnerBase_js_1.RunnerBase {
      *  armed agent with a window, where `stages/window.ts · buildWindowStage`
      *  spends it as the `'ledger-fact'` pin ceiling. */
     findingsOptions;
+    /** Tool choice by classifier (9.105.0, `.toolChoice()`): the classifier,
+     *  the serve dial and the app's own doors. Threaded to the tools slot (the
+     *  pick and the narrowing), to call-llm (`toolChoice: true`, the outcome
+     *  row) and to both chart builders (`hasToolChoice`, the mount args) on an
+     *  armed agent only — an unarmed agent hands each stage exactly the deps it
+     *  always did. */
+    toolChoiceOptions;
+    /** The declared ontology (9.106.0, `.ontology()`): the frozen map. Threaded
+     *  to seed (the whole map, written once as the run constant `ontology`),
+     *  to call-llm (`ontology: true`, the gate on every read of that key) and
+     *  to both chart builders (`hasOntology`, the grouped boundary's crossing)
+     *  on an armed agent only — an unarmed agent hands each stage exactly the
+     *  deps it always did. The tool names its `via` edges name are checked
+     *  against the registry in `buildChart`, beside `buildToolRegistry`. */
+    ontology;
     /** The opt-in tool-result ceiling in characters (9.11.0). Absent → results
      *  are never measured. See {@link AgentOptions.maxToolResultChars}. */
     maxToolResultChars;
@@ -661,6 +676,10 @@ class Agent extends RunnerBase_js_1.RunnerBase {
             this.toolArgValidation = opts.toolArgValidation;
         if (opts.findings !== undefined)
             this.findingsOptions = opts.findings;
+        if (opts.toolChoice !== undefined)
+            this.toolChoiceOptions = opts.toolChoice;
+        if (opts.ontology !== undefined)
+            this.ontology = opts.ontology;
         // 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.
@@ -757,6 +776,16 @@ class Agent extends RunnerBase_js_1.RunnerBase {
             }
             this.keepLedgerFacts = resolveKeepLedgerFacts(this.findingsOptions.keepLedgerFacts ?? opts.keepLedgerFacts);
         }
+        // Tool choice by classifier (9.105.0) needs the same per-call recomposition
+        // the ledger does — the pick is made where the served list is built, and
+        // a narrowed list committed on turn 1 would be served on every later call
+        // with no pick behind it. The same refusal, at the same place.
+        if (this.toolChoiceOptions !== undefined && this.reactMode === 'classic') {
+            throw new Error("Agent: .toolChoice() requires per-iteration slot recomposition — reactMode 'classic' " +
+                'caches the tools slot on turn 1, so the classifier would be asked once and a narrowed ' +
+                "list would be served on every later call. Use the default 'dynamic' mode (or " +
+                "'dynamic-grouped').");
+        }
         // Refused at construction, never mid-run — a misspelled posture that was
         // ignored would leave the liveness theorems switched off in an agent
         // that believes they are on (the concurrency-mode precedent).
@@ -2585,6 +2614,28 @@ class Agent extends RunnerBase_js_1.RunnerBase {
                 getRunContext: getRunCtx,
             }));
         }
+        // Same wiring for `agentfootprint.tool_choice.*` (9.105.0) — the three
+        // events `recordToolChoice` files on scope. Attached only under
+        // `.toolChoice()`, for the same reason.
+        if (this.toolChoiceOptions !== undefined) {
+            attachObserver(new EmitBridge_js_1.EmitBridge({
+                id: 'agentfootprint.tool-choice-bridge',
+                prefix: 'agentfootprint.tool_choice.',
+                dispatcher,
+                getRunContext: getRunCtx,
+            }));
+        }
+        // Same wiring for `agentfootprint.ontology.*` (9.106.0) — the one event
+        // `callLLM` emits when the declared map is served. Attached only under
+        // `.ontology()`, for the same reason.
+        if (this.ontology !== undefined) {
+            attachObserver(new EmitBridge_js_1.EmitBridge({
+                id: 'agentfootprint.ontology-bridge',
+                prefix: 'agentfootprint.ontology.',
+                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
@@ -3221,6 +3272,11 @@ class Agent extends RunnerBase_js_1.RunnerBase {
                     return l;
                 },
             }),
+            // The declared ontology (9.106.0): the whole frozen map, which seed
+            // writes ONCE as the run constant `ontology` — the `findingsServe`
+            // precedent, a build-time fact the rebuild reads from the RECORD. An
+            // unarmed agent hands seed exactly the deps object it always did.
+            ...(this.ontology !== undefined && { ontology: this.ontology }),
             // 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
@@ -3285,6 +3341,26 @@ class Agent extends RunnerBase_js_1.RunnerBase {
             // armed may a registry tool's own `_findings` be refused.
             ...(this.findingsOptions !== undefined && { findings: true }),
         });
+        // The declared ontology's tool edges (9.106.0): every name a node's `via`
+        // names must be a tool this registry can dispatch — the static registry,
+        // the framework's doors and every skill's tools, `registryByName` being
+        // the ONE map that holds all of them. Refused at BUILD, naming the
+        // ontology and the tool: a map that points a need at a tool nobody can
+        // call is a map that lies, and only the operator can fix it. Provider-
+        // served tools are only met at dispatch and cannot be named here.
+        if (this.ontology !== undefined) {
+            for (const [nodeId, node] of Object.entries(this.ontology.nodes)) {
+                for (const held of node.sources ?? []) {
+                    for (const toolName of held.via ?? []) {
+                        if (!registryByName.has(toolName)) {
+                            throw new Error(`Agent: ontology '${this.ontology.id}' names tool '${toolName}' that is not ` +
+                                `registered (node '${nodeId}', source '${held.source}'). Register the tool ` +
+                                `with .tool() or on a skill, or drop it from the node's \`via\`.`);
+                        }
+                    }
+                }
+            }
+        }
         // A statically registered tool that declares `wants` on an agent with no
         // store is configuration that lies: every call would be refused at
         // dispatch for a gap only the operator can close. Refused at BUILD,
@@ -3549,6 +3625,19 @@ class Agent extends RunnerBase_js_1.RunnerBase {
             // 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 }),
+            // Tool choice by classifier (9.105.0): the pick and the narrowing live
+            // inside this slot too, at the same site; value-conditional.
+            ...(this.toolChoiceOptions !== undefined && {
+                toolChoice: {
+                    classifier: this.toolChoiceOptions.classifier,
+                    ...(typeof this.toolChoiceOptions.serve === 'object' && {
+                        top: this.toolChoiceOptions.serve.top,
+                    }),
+                    ...(this.toolChoiceOptions.alwaysServe !== undefined && {
+                        alwaysServe: this.toolChoiceOptions.alwaysServe,
+                    }),
+                },
+            }),
         });
         // callLLM extracted to ./agent/stages/callLLM.ts (v2.11.2). Same
         // late-binding pattern as seed for toolSchemas (computed below).
@@ -3575,6 +3664,12 @@ class Agent extends RunnerBase_js_1.RunnerBase {
                 }),
             }),
             ...(this.answerValidationConfig !== undefined && { suppressDraftTokens: true }),
+            // Tool choice by classifier (9.105.0): the outcome row after the reply.
+            ...(this.toolChoiceOptions !== undefined && { toolChoice: true }),
+            // The declared ontology (9.106.0): the piece served from the run
+            // constant on every call, under the one gate — an unarmed agent reads
+            // no new key.
+            ...(this.ontology !== undefined && { ontology: true }),
             // The receipt's salt (9.88.0) — read per call, like seed's own accessor.
             getRunId: () => this.currentRunContext?.runId,
             // …and its off switch. Value-conditional, so an agent on the default
@@ -3941,6 +4036,12 @@ class Agent extends RunnerBase_js_1.RunnerBase {
             // grammar as the slot's `findings` and callLLM's `hasFindingsLedger`,
             // so the three can never disagree about whether the ledger is armed.
             ...(this.findingsOptions !== undefined && { hasFindingsLedger: true }),
+            // Tool choice by classifier (9.105.0): the mount args on the Tools
+            // branch and the key across the sf-llm-call boundary, under the arm.
+            ...(this.toolChoiceOptions !== undefined && { hasToolChoice: true }),
+            // The declared ontology (9.106.0): the grouped chart carries the run
+            // constant across the sf-llm-call boundary, under the arm.
+            ...(this.ontology !== undefined && { hasOntology: true }),
             // `.limitsTravelWithTheAnswer()` (this release) — value-conditional, the
             // `resolvedModel` precedent: absent from the deps object entirely for an
             // agent that did not ask, so both builders mount the final-branch stage