Skip to content

Local-first 🧠 memory for Hermes Agent that lives in your Obsidian vault and remembers project context. Nightly 😴 dream passes turn repeat corrections into confirmed preferences with measurable confidence. Adapters ship for Claude Code, Codex, and OpenClaw, with an MCP server for anything else.

TypeScript

feat(brain): context-pack economics and observability (1.25.0) (#126)

Sol Aitkenfe2c0be22383
diff --git a/.claude-plugin/plugin.json b/.claude-plugin/plugin.json
index 0dc97149..8bea12b9 100644
--- a/.claude-plugin/plugin.json
+++ b/.claude-plugin/plugin.json
@@ -1,6 +1,6 @@
{
"name": "open-second-brain",
- "version": "1.24.0",
+ "version": "1.25.0",
"description": "Plugin-first second brain package for AI agents and humans.",
"author": {
"name": "Open Second Brain contributors"
diff --git a/.codex-plugin/plugin.json b/.codex-plugin/plugin.json
index c54848fc..839d8056 100644
--- a/.codex-plugin/plugin.json
+++ b/.codex-plugin/plugin.json
@@ -1,6 +1,6 @@
{
"name": "open-second-brain",
- "version": "1.24.0",
+ "version": "1.25.0",
"description": "Plugin-first second brain package for Codex, Hermes, Claude Code, OpenClaw, and other agent runtimes.",
"skills": "./skills",
"hooks": "./hooks/hooks.json",
diff --git a/CHANGELOG.md b/CHANGELOG.md
index a3044e73..454c8ed4 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -5,6 +5,71 @@ 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).
+## [1.25.0] - 2026-07-07
+
+An economics and observability layer for the context pack. Five new
+opt-in surfaces make the value of memory measurable and close the
+quality feedback loop, each off by default with byte-identical output
+when unconfigured. The kernel still calls no LLM.
+
+### Added
+
+- **Value-per-token density ranking in the context pack.** With
+ `density_ranking_context_pack` on (default off), the context-pack
+ builder adds a deterministic density comparator that breaks within-tier
+ ties after session focus and before recency, ordering candidates by
+ structural signal per estimated token rather than only by freshness.
+ Tier stays the coarse gate so a peripheral page never outranks a core
+ one; off/absent keeps the density field off the item and the ordering
+ byte-identical. The score is a language-agnostic count (evidence-ref
+ grounding plus `[[wikilink]]` connectivity plus a fixed epistemic
+ weight), never a wordlist or LLM judgement.
+- **Durable token-impact ledger.** With `token_impact_ledger_enabled`
+ on (default off), every context pack posts one `token_impact` sample
+ carrying the tokenizer-exact prompt-token delta
+ (`baseline_tokens` − `packed_tokens`, labelled `method: exact` or
+ `fallback`) plus an optional modeled inference-avoidance estimate.
+ `brain_token_impact` `record` posts a sample, `outcome` posts a
+ `first_pass` / `repair` / `retry` result used only to calibrate the
+ modeled figure, and `summary` keeps the two ledgers strictly
+ separate: `prompt_token_delta` reports the measured net, saved, and
+ added tokens with a per-method split, while
+ `modeled_inference_avoidance` reports the raw modeled figure and a
+ `calibrated_savings_tokens` value dampened by the observed
+ first-pass rate (null until an outcome exists, uncalibrated not
+ zero). `list` reads raw samples. Writes are payload-safe (counts and
+ an opaque `pack_id` only); reads ignore the gate. Aggregates are
+ recomputed from the continuity store on every read, so they survive
+ restarts.
+- **Agent-operable context-pack outcome loop.** With
+ `context_pack_outcome_enabled` on (default off),
+ `brain_context_pack_outcome` `post` records one compact outcome row
+ for a carried context-pack quality-sample id: first-pass, repair,
+ and retry counters plus three strictly separate token signals
+ (`exact_prompt_token_savings`, `modeled_inference_avoidance`,
+ `observed_provider_tokens`), and composes the token-impact ledger
+ by posting a matching first-pass, repair, and retry calibration
+ outcome. `list` and `summary` read the rows keeping the signals
+ separate. A field the caller omits is never invented; writes are
+ payload-safe (counters and an opaque `sample_id` only); reads ignore
+ the gate.
+- **Route-level MCP tool latency metrics.** With
+ `mcp_route_metrics_enabled` on (default off), the MCP server emits
+ one `mcp_route_latency` continuity record per tool call: tool name,
+ scope, status (`ok` / `error`), duration, and the sorted set of
+ argument key names only, never argument values. `brain_route_metrics`
+ `list` returns raw records and `summary` rolls each tool up into
+ count, error count, min, avg, max, and p50, p95, p99 latency ordered
+ slowest-first, so an operator can identify which endpoint blocks an
+ agent turn by route rather than by aggregate benchmark. Read-only;
+ the emit is gated and fail-open.
+- **Proactive active-memory budget-pressure watermark.** The active
+ budget now reports a pressure signal before the pack is forced to
+ trim, so an operator or agent can react to approaching limits
+ instead of only observing the trim after it happens. The signal is
+ derived from existing budget metadata; behavior is byte-identical
+ when no consumer reads it.
+
## [1.24.0] - 2026-07-06
A hardening and correctness pass over the PR #121 refactor. Thirteen fixes
diff --git a/README.md b/README.md
index 00caa69d..0a368c60 100644
--- a/README.md
+++ b/README.md
@@ -8,7 +8,7 @@ Open Second Brain plugs into [Hermes Agent](https://github.com/NousResearch/herm
## What is new
-Open Second Brain 1.24.0 is a hardening and correctness pass. The search index rebuild is now guarded by a separate reindex lock so a concurrent or interrupted reindex cannot swap an empty or stale database over the live index, and an unreadable index self-heals instead of surfacing a raw read error. Wikilink resolution runs over a new `documents.basename` column and index instead of a per-link SUBSTR scan, and the entity, backlink, and heal hot paths are memoized so they are not rebuilt on every query. Continuity records now require a full canonical timestamp, card snippet truncation no longer splits an astral character into a lone replacement character, and `since` / `until` filtering handles second precision consistently. The secret-exec audit trail redacts the command field before it is persisted, and the CJK bigram tokenizer stays inside contiguous Han spans. The `basename` column requires a schema bump, so every existing install reindexes once on next open. The kernel still calls no LLM.
+Open Second Brain 1.25.0 adds an optional economics and observability layer for the context pack, each surface off by default with byte-identical output when unconfigured. A value-per-token density ranking comparator breaks within-tier ties in the context pack after session focus and before recency, so a dense high-signal page can outrank a sparse recent one inside the same tier (tier stays the coarse gate). A durable token-impact ledger records the tokenizer-exact prompt-token delta every context pack saves (baseline minus packed), kept strictly separate from a modeled inference-avoidance estimate that outcomes can later calibrate, so a measured count is never averaged in with a model. An agent-operable context-pack outcome loop closes the quality feedback path: the agent posts first-pass, repair, and retry counters per carried sample, and three token signals stay separate rather than merged. Route-level MCP tool latency metrics show which endpoint blocks an agent turn by route rather than by aggregate benchmark, and an active-memory budget-pressure watermark surfaces proactive pressure before the pack is forced to trim. Every ledger is payload-safe (counts and opaque ids only, never prompts or recalled text), reads ignore the write gate, and the kernel still calls no LLM.
## Why
diff --git a/docs/brainstorm/context-pack-economics-observability/cli-output/claude.md b/docs/brainstorm/context-pack-economics-observability/cli-output/claude.md
new file mode 100644
index 00000000..e081996b
--- /dev/null
+++ b/docs/brainstorm/context-pack-economics-observability/cli-output/claude.md
@@ -0,0 +1,29 @@
+### Variant 1 — Five parallel verticals
+Approach: Ship each card as a self-contained vertical that mirrors the existing `recall-telemetry.ts` triplet (`emit*` / `list*` / `summarize*`), each with its own new `ContinuityRecordKind`, its own gate (config flag or opt-in option), and its own reader verb. The only cross-module edge is Card 5 importing Card 3's ledger API; everything else is isolated. Card 1 slots a density comparator into the existing within-tier sort exactly as `sessionFocus` already does (byte-identical when the score map is empty).
+Trade-offs:
+- Maximum independence: each card's default-off branch is trivially and locally provable byte-identical, and each is genuinely PR-shippable alone.
+- Reader surface fragments into five new summaries with duplicated list/filter/reverse/limit boilerplate, and no single "prompt-economics" view ties Cards 2/3/4/5 together.
+- Two shared files still collide (`context-pack.ts` for Cards 1+3; `continuity/types.ts` for Cards 2+3+5), so drive order still has to serialize them regardless of the isolation.
+Complexity: medium
+Risk: low
+
+### Variant 2 — Economics ledger spine first
+Approach: Build Card 3's durable token-impact + quality ledger first as a unifying substrate — one economics kind-family, one reader framework, one `/outcome`-style calibration endpoint — then hang Cards 2 (route latency), 4 (budget-pressure watermark), and 5 (outcome loop) onto that spine as thin emitters, leaving Card 1 as the sole standalone ordering change. One consolidated economics reader surfaces all four signals.
+Trade-offs:
+- Cohesive single prompt-economics surface with minimal reader duplication; Card 5 sits on Card 3 with almost no glue, and the "three token signals kept strictly separate" invariant is enforced once in the shared schema.
+- Front-loads the largest, highest-schema-risk card and couples the quick p4 wins to it, weakening the "five independently shippable signals" requirement and delaying byte-identical-off verification behind a broad substrate.
+- If the shared schema needs to change after Cards 2/4 land on it, every dependent card's persisted records and readers churn together.
+Complexity: large
+Risk: medium
+
+### Variant 3 — Thin shared kernel, parallel modules, priority-ordered drive
+Approach: Add only the reuse that is real — extend `ContinuityRecordKind` with the new kinds in one small commit and introduce one tiny shared list/summarize helper that each card's reader composes — while keeping every card's pure logic in its own module behind its own gate. Drive in priority-and-collision order: Card 2 (isolated in `tools.ts`) → Card 1 (`context-pack.ts` sort comparator) → Card 3 (`context-pack.ts` `finalizeContextPackReport` emit region + ledger) → Card 4 (`active-budget.ts` `SECTION_PRIORITIES` reuse → `doctor.ts`) → Card 5 (on Card 3's ledger).
+Trade-offs:
+- Balances cohesion and independence: one small helper removes 5× reader boilerplate without coupling card schemas, and each card keeps a locally-provable byte-identical off-branch.
+- Drive order resolves both shared-file collisions — Card 1 (sort) and Card 3 (finalize) touch disjoint regions of `context-pack.ts` in sequence, and the three `types.ts` kind additions serialize cleanly.
+- The shared reader helper is a modest new abstraction to maintain, and the ordering discipline must be honored on the branch or the two `context-pack.ts` cards rebase-conflict.
+Complexity: medium
+Risk: low
+
+### Recommended: Variant 3
+It honors the release's stated shape — five deterministic, independently-shippable signals that reuse existing machinery — without either fragmenting the reader surface (Variant 1) or over-coupling the cards to a premature spine (Variant 2). The thin kernel captures exactly the reuse the codebase already rewards: `emitGatedTelemetry`'s fail-open no-work-when-off contract, the continuity store's append/list model, and the `sessionFocus` within-tier-boost precedent that makes Card 1's density score byte-identical when disabled. Its priority-ordered drive (p4 quick wins → p3 measurement → p2 capstone) matches the only hard dependency (Card 3 → Card 5) while serializing the `context-pack.ts` and `continuity/types.ts` collisions, so each card lands and ships on its own. The one new abstraction is small and earns its place by eliminating five copies of list/filter/summarize boilerplate.
diff --git a/docs/brainstorm/context-pack-economics-observability/cli-output/prompt.md b/docs/brainstorm/context-pack-economics-observability/cli-output/prompt.md
new file mode 100644
index 00000000..8d41f135
--- /dev/null
+++ b/docs/brainstorm/context-pack-economics-observability/cli-output/prompt.md
@@ -0,0 +1,144 @@
+# Consultant prompt — context-pack memory-economics & observability
+
+You are a senior backend architect. Produce architectural variants for a single
+shippable release of **Open Second Brain (o2b)**. Read the context below
+carefully; every design MUST respect o2b's hard invariants.
+
+## Output contract (MANDATORY)
+
+Output EXACTLY three variant sections then ONE recommendation. No code. Nothing
+outside these sections. Each variant:
+
+```
+### Variant N — <short name>
+Approach: <2-3 sentences>
+Trade-offs:
+- <bullet>
+- <bullet>
+Complexity: small | medium | large
+Risk: low | medium | high
+```
+
+Then exactly:
+
+```
+### Recommended: Variant N
+<rationale, 3-5 sentences>
+```
+
+Do not add an introduction, summary, or closing.
+
+## Project
+
+- Name: `open-second-brain` (o2b), v1.23.0.
+- Language/runtime: TypeScript, ESM, runs on Bun + Node. `type: module`.
+- What it is: an Obsidian-native memory layer for AI agents. Plain Markdown in a
+ vault (`Brain/` directory). Deterministic CLI + MCP tools. **The kernel calls
+ no LLM** — this is a core, load-bearing invariant.
+- Conventions (hard): deterministic, byte-identical-when-off for any new field
+ or switch; pure functions do the work, IO shells stay thin; everything is
+ language-agnostic (no English wordlists); additive optional fields absent by
+ default; privacy-preserving telemetry (no raw prompts, recalled text, or
+ secrets); persistence via the continuity store (append-only, month-sharded
+ JSONL under `<vault>/Brain/logs/continuity/`, reloaded on startup); config
+ flags are explicit opt-in.
+
+## The release problem
+
+Releases v1.18–v1.23 repeatedly improved recall *precision* (coverage, rerank,
+dedup, provenance) with **zero gain in measuring the value that precision
+delivers**. o2b can enforce token/char budgets and record recall/gate telemetry,
+but it cannot answer: "how many prompt tokens did the memory layer keep out of
+(or add to) the agent call?", "which MCP route is slow?", "is the active-memory
+body near its budget before it silently truncates?", or "did this recall sample
+lead to a first-pass success or force repair/retries?" This release closes that
+gap with five deterministic, independently-shippable signals that REUSE existing
+budget/telemetry machinery.
+
+## In-scope cards (ship together, driven one-at-a-time on one branch)
+
+### Card 1 — `t_affa3bd9` (p4): value-per-token density in context-pack
+Today `src/core/brain/context-pack.ts` orders candidates by:
+1. tier ascending importance (core → supporting → peripheral);
+2. created_at desc;
+3. id asc.
+Then fills the token budget greedily; overflow goes to `pagesSkipped`.
+There is NO per-item density/impact score, so as the vault grows the budget fills
+with recent-but-low-value entries and skips denser high-signal ones.
+Requirement: a computed heuristic density score (signal markers / links /
+evidence weight per estimated token) — NOT an LLM judgement. Tier can remain a
+coarse gate; density ranks within/across tier. Default-off switch → byte-identical
+ordering when disabled. `estimateTokens` lives in `src/core/brain/text/tokenizer.ts`
+(`ceil(utf8_bytes/4)`).
+
+### Card 2 — `t_6c9a3e5c` (p4): route-level latency metrics for MCP tools
+o2b records some latency for generation reports and memory benchmarks, but not
+per-MCP-route. Operators need to see which tool blocks a turn by endpoint.
+Requirement: a latency wrapper around the tool registry/handlers
+(`src/mcp/tools.ts` `ToolDefinition.handler`, assembled in `buildToolTable`)
+recording tool name, duration, status, and optionally argument-shape hashes —
+never raw prompt or note content. Persist via the continuity store. Surface as a
+reader (CLI/MCP summary) consistent with existing `recall-telemetry` /
+`generation-report` readers.
+
+### Card 3 — `t_a8926bd0` (p3): durable token-impact + context-pack-quality ledger
+A durable, bounded, privacy-preserving ledger measuring the prompt-economics
+impact of the memory/context layer: tokenizer-exact prompt-token deltas per
+context pack, persisted, reloaded on startup, with honest "fallback estimation"
+labeling when a tokenizer is unavailable. A second ledger separates EXACT
+prompt-token savings from MODELED/counterfactual inference-avoidance
+(retries/repairs avoided), with an `/outcome`-style endpoint to post outcomes and
+calibrate the modeled estimate. Store no raw prompts or recalled text. Reuse the
+continuity store. Distinct from Card 1 (ranking) and Card 5 (outcome loop) — this
+is the passive measurement/telemetry layer.
+
+### Card 4 — `t_dfda8adb` (p3): proactive active-memory budget-pressure watermark
+Today `src/core/brain/active-budget.ts` truncates the rendered `active.md`
+injection REACTIVELY at render time, dropping sections in priority order
+(retired → quarantine → most-applied; confirmed survives) and printing
+`ACTIVE_TRUNCATION_NOTICE`. Nothing reports "active.md is at 85% of budget" or
+names stale entries you could archive — content silently disappears.
+Requirement: a proactive watermark probe (fill-rate metric + ranked eviction
+CANDIDATES, reusing the existing `SECTION_PRIORITIES` model). Deterministic
+(byte/section counting, no LLM). "Empty output = healthy" keeps it quiet on
+healthy vaults. Candidates are SUGGESTIONS, never auto-deleted. Use a distinct
+term (e.g. "active budget pressure") — do NOT reuse the unrelated `WatermarkState`
+cursor in `skill-proposals.ts`. Surface through `doctor.ts` / hygiene.
+
+### Card 5 — `t_f2140bae` (p2): agent-operable context-pack outcome loop
+Layered on Card 3's ledger: the agent carries the latest recall/context-pack
+quality-sample id through its session as bounded local state, then on completion
+posts a compact outcome row — first-pass-success, repair-required, retry-count,
+follow-up-token, provider-token counters. Three token signals kept strictly
+separate: exact prompt-token savings (tokenizer-aware delta), modeled inference
+avoidance (confidence-banded counterfactual), observed provider usage
+(provider-reported). Compact counters only; never raw text/secrets; agent omits a
+field rather than inventing it. Best sequenced AFTER Card 3 lands. Nearest
+existing surface is Brain's `brain_apply_evidence` outcome field
+(preference-level, not recall/context-pack-level).
+
+## Cross-cutting constraints
+
+- The five cards are independent modules EXCEPT Card 5 depends on Card 3's
+ ledger. They reuse: the continuity store (Cards 2, 3, 5), `estimateTokens`
+ (Cards 1, 3), the tool registry (Card 2), `SECTION_PRIORITIES` (Card 4),
+ `emitGatedTelemetry`/fail-open emission (all).
+- Each card's off/default branch must be provably byte-identical to today.
+- Recommend a drive order (one-at-a-time on the shared branch) that resolves file
+ collisions. The only structural dependency is Card 3 → Card 5.
+- No web dashboard (o2b has none). No shared/hosted control plane. No LLM in any
+ kernel logic.
+
+## Recent git history (for convention grounding)
+
+```
+67bcb71c refactor: DRY and decomposition (Phases 0-2) (#121)
+b9bbcb16 feat(brain): semantic entity dedup and cross-encoder rerank (1.23.0) (#120)
+b8d709ee fix: keep full MCP status output and normalize codegraph paths (#116)
+a98bed1d feat(brain): retrieval precision and quality loop (v1.22.0) (#118)
+42816058 feat(brain): integrity & safety hardening suite (1.21.0) (#115)
+33b4fba5 feat: recall precision, coverage, and provenance hardening (v1.18.0) (#110)
+da2e3ccd feat: memory subsystem alignment - honest pinned budgets, atomic batch writes (v1.16.0) (#107)
+```
+
+Now produce the three variants and the single recommendation.
diff --git a/docs/brainstorm/context-pack-economics-observability/design.md b/docs/brainstorm/context-pack-economics-observability/design.md
new file mode 100644
index 00000000..d5a6b747
--- /dev/null
+++ b/docs/brainstorm/context-pack-economics-observability/design.md
@@ -0,0 +1,224 @@
+# Design — Context-pack memory-economics & observability
+
+Branch: `feat/context-pack-economics-observability`
+Slug: `context-pack-economics-observability`
+Cards: C1 `t_affa3bd9`, C2 `t_6c9a3e5c`, C3 `t_a8926bd0`, C4 `t_dfda8adb`, C5 `t_f2140bae`
+
+## Problem
+
+Releases v1.18–v1.23 repeatedly improved recall *precision* (coverage, rerank,
+entity dedup, epistemic provenance, cross-encoder rerank) with **zero gain in
+measuring the value that precision delivers**. o2b can enforce token/char budgets
+and record recall/gate telemetry, but it cannot answer five distinct operational
+questions that are now the binding constraint on further precision work:
+
+1. **Is the context pack shipping the densest signal per token?**
+ `context-pack.ts` orders candidates by tier → recency → id and fills the token
+ budget greedily. As the vault grows this fills the budget with recent-but-
+ low-value entries and skips denser high-signal ones (`pagesSkipped` overflow of
+ important content). There is no per-item density/impact score.
+2. **Which MCP route is slow?** o2b records latency for generation reports and
+ memory benchmarks, but not per-MCP-route. When a specific tool blocks a turn,
+ the operator has only aggregate numbers, not an endpoint breakdown.
+3. **How many prompt tokens did the memory layer actually keep out of (or add to)
+ the agent call?** Budget code enforces limits; nothing measures the realized
+ prompt-token delta per context pack. The core value-of-memory metric is absent.
+4. **Is the active-memory body near its budget before it silently truncates?**
+ `active-budget.ts` truncates the `active.md` injection REACTIVELY at render
+ time. Content disappears with a notice; there is no proactive fill-rate signal
+ and no named eviction candidates.
+5. **Did this recall sample lead to a first-pass success or force repair/retries?**
+ Brain records per-preference `outcome` via `brain_apply_evidence`, but nothing
+ closes the loop on *recall quality*. Recall precision stays a guessed metric.
+
+This release closes the gap with five deterministic, independently-shippable
+signals that REUSE existing budget/telemetry machinery.
+
+## Scope
+
+All five cards ship in this release, driven one at a time on the shared branch:
+
+- **C2** `t_6c9a3e5c` (p4) — route-level latency metrics for MCP tools.
+- **C1** `t_affa3bd9` (p4) — value-per-token density ranking in context-pack.
+- **C3** `t_a8926bd0` (p3) — durable token-impact + context-pack-quality ledger
+ (tokenizer-exact, exact-vs-modeled separation, persisted, reload-on-startup).
+- **C4** `t_dfda8adb` (p3) — proactive active-memory budget-pressure watermark +
+ ranked eviction candidates.
+- **C5** `t_f2140bae` (p2) — agent-operable context-pack outcome loop (carries
+ sample id; posts measured/modeled/observed outcome rows on completion).
+
+## Out of scope
+
+- A web dashboard (o2b has none; every new signal ships as CLI/MCP readers).
+- Any LLM inside kernel logic. Every new score, metric, and threshold is
+ deterministic (byte/section/token counting, structural heuristics).
+- A server-managed shared control plane, hosted "Spaces", per-agent billing
+ tokens, or anything that sends vault content off-host.
+- The capture-once projection unification refactor (`t_b4297898`, p2) — left in
+ triage as a future generalization path; this release composes existing surfaces
+ rather than refactoring them.
+- Migrating existing JSONL or stored Markdown. New ledger kinds are additive; old
+ continuity records are read as-is (v1 schema contract).
+- Auto-deletion of any vault content. C4 eviction entries are suggestions only.
+
+## Chosen approach
+
+**Variant 3 — thin shared kernel, parallel modules, priority-ordered drive.**
+
+Extend `ContinuityRecordKind` with the new kinds in one small commit and
+introduce one tiny shared list/summarize helper that each card's reader composes,
+while keeping every card's pure logic in its own module behind its own gate.
+This captures exactly the reuse the codebase already rewards —
+`emitGatedTelemetry`'s fail-open no-work-when-off contract, the continuity
+store's append/list model, and the `sessionFocus` within-tier-boost precedent
+that makes C1's density score byte-identical when disabled — without either
+fragmenting the reader surface into five near-duplicate triplets (Variant 1) or
+front-loading the largest, highest-schema-risk card behind a premature shared
+spine that couples the quick p4 wins to it (Variant 2).
+
+Each card lands as a self-contained module behind its own explicit switch whose
+off-branch is provably byte-identical to today. The only hard dependency is
+C3 → C5 (the outcome loop writes into C3's ledger).
+
+### Drive order: C2 → C1 → C3 → C4 → C5
+
+Resolves both real shared-file collisions:
+- **C1 → C3** (both touch `context-pack.ts`): C1 adds the density comparator to
+ the within-tier sort (the `candidates.sort(...)` region); C3 adds the
+ token-impact emit to `finalizeContextPackReport`. Disjoint regions, sequenced.
+- **C2 → C3 → C5** (all touch `continuity/types.ts`): the new `ContinuityRecordKind`
+ additions serialize cleanly in drive order.
+- **C3 → C5** (hard dependency): C5 composes C3's ledger emit API.
+
+## Design decisions
+
+### Shared kernel (lands in the C2 commit, reused by C3/C5)
+- `src/core/brain/continuity/types.ts` — add new kinds: `mcp_route_latency`
+ (C2), `token_impact` (C3), `context_pack_outcome` (C5). Additive; legacy records
+ read as v1 (schema-stamp contract). C1 and C4 add NO new continuity kind — they
+ are pure ordering/health modules.
+- `src/core/brain/continuity/readers.ts` (new, tiny) — one shared
+ `listRecordsByKind(vault, kind, filter)` + `summarizeCounters(records, keys)`
+ helper each card's reader composes, eliminating 5× list/filter/reverse/limit
+ boilerplate. Pure, deterministic. No schema coupling — each card owns its own
+ payload shape.
+- Every emitter routes through `emitGatedTelemetry` so a broken/absent option is
+ a no-op (fail-open), identical to `recall-telemetry`/`generation-reports`.
+
+### C1 — value-per-token density (t_affa3bd9)
+- New pure module `src/core/brain/context-density.ts` exporting
+ `densityScore(item, tokens)` → number, computed from structural signals already
+ on the candidate (signal markers, `evidenceRefs` count/wikilink density,
+ evidence weight) divided by `estimateTokens(body)`. Language-agnostic by
+ construction (no wordlists — same approach as `deriveEpistemicStatus`).
+- `context-pack.ts`: add `densityRanking?: boolean` to `ContextPackOptions`. When
+ true, insert a density comparator INTO the existing within-tier sort, AFTER
+ `sessionFocus` (which already occupies the between-tier-and-recency slot): the
+ full chain becomes tier → sessionFocus → density → recency → id. Compute a
+ `densityScore` per candidate into a map (0 for every candidate when disabled →
+ the map is empty and the sort is byte-identical to today). Focus dominates
+ density so a static content-quality heuristic can never override the user's
+ active session target; density only breaks focus ties, then recency → id. Tier
+ remains the coarse gate; a peripheral page can never outrank a core one.
+- No new continuity kind; the score is computed, not persisted. Density MAY be
+ surfaced as an optional field on `ContextPackItem` (absent when off →
+ byte-identical).
+
+### C2 — MCP route-level latency (t_6c9a3e5c)
+- New module `src/core/brain/mcp-route-latency.ts`: `emitRouteLatency(vault,
+ {tool, durationMs, status, argShapeHash?})` → `ContinuityRecord` of kind
+ `mcp_route_latency`. Payload records tool name, duration, status, and an
+ OPTIONAL argument-shape hash (structural — `createHash` over the arg keys/types,
+ never values) — never raw prompt or note content. `listRouteLatency` /
+ `summarizeRouteLatency` compose the shared reader.
+- `src/mcp/tools.ts`: wrap `ToolDefinition.handler` in `buildToolTable` with a
+ timing+status collector that emits one `mcp_route_latency` record per call.
+ Gated by a config flag (`mcp_route_latency_enabled`, default false) so
+ unconfigured deployments are byte-identical and write nothing. On emission
+ failure the tool result is unchanged (fail-open).
+
+### C3 — durable token-impact + quality ledger (t_a8926bd0)
+- New module `src/core/brain/token-impact-ledger.ts`:
+ - `emitTokenImpact(vault, {packReceiptId, exactTokens, modeledAvoidance?,
+ counterfactual?, basis})` where `basis: "tokenizer_exact" | "fallback_est"`
+ labels honesty (when a real tokenizer is unavailable, basis is
+ `fallback_est` and the value comes from `estimateTokens`).
+ - Strict separation enforced in the payload schema: `exact.prompt_token_delta`
+ vs `modeled.inference_avoidance` (confidence-banded counterfactual, e.g.
+ retries/repairs avoided) are never merged.
+ - Persisted via continuity store → reloaded on startup (existing
+ list-by-kind reader), bounded by the store's month-shard + redaction.
+- An outcome-calibration endpoint (CLI/MCP `brain_token_impact_outcome`) lets the
+ agent post first-pass/repair/retry outcomes to recalibrate the modeled band —
+ this is the passive endpoint C5's loop writes into.
+- `context-pack.ts` `finalizeContextPackReport`: when a new opt-in flag is set,
+ emit one `token_impact` record with the tokenizer-exact delta of the packed
+ body vs an un-packed baseline. Default-off → no record, byte-identical.
+
+### C4 — active-memory budget-pressure watermark (t_dfda8adb)
+- New pure module `src/core/brain/active-budget-pressure.ts`:
+ `computeActiveBudgetPressure(body, budgetChars)` → `{fillRate, status:
+ "healthy"|"elevated"|"critical", candidates: Array<{sectionKey, bytes,
+ priority}>}`. Reuses `SECTION_PRIORITIES` from `active-budget.ts` (extracted to
+ a shared constant if not already) and the same section-split logic.
+- "Empty output = healthy": when `fillRate` is at or below the warn threshold
+ (a constant owned by the new `active-budget-pressure.ts` module, not a
+ pre-existing symbol), the probe emits nothing on the `doctor` surface (quiet on
+ healthy vaults). Above threshold it
+ lists ranked eviction CANDIDATES (highest-priority-to-drop first) as
+ suggestions — never auto-deleted.
+- Distinct term "active budget pressure" — NOT the `WatermarkState` cursor in
+ `skill-proposals.ts`. Surfaced through `doctor.ts` (new check) and the hygiene
+ surface.
+
+### C5 — agent-operable context-pack outcome loop (t_f2140bae)
+- New module `src/core/brain/context-pack-outcome.ts`:
+ `emitContextPackOutcome(vault, {sampleId, firstPassSuccess, repairRequired?,
+ retryCount?, followUpTokens?, providerTokens?, tokenSignal})` where
+ `tokenSignal` is one of `exact` | `modeled` | `observed`, keeping the three
+ token signals strictly separate (never merged into one field).
+- Composes C3's ledger: writes a `context_pack_outcome` continuity record AND
+ posts to C3's calibration endpoint so the modeled band tightens. Compact
+ counters only; agent omits a field rather than inventing it.
+- The agent carries the latest sample id as bounded local state (carried in the
+ context-pack report/receipt, not a new daemon). On completion it posts the
+ outcome row. Sequenced AFTER C3 (hard dependency).
+
+## File changes (summary; per-card detail in plan.md)
+
+- `src/core/brain/continuity/types.ts` — 3 new `ContinuityRecordKind` entries.
+- `src/core/brain/continuity/readers.ts` — NEW shared list/summarize helper.
+- `src/core/brain/context-density.ts` — NEW (C1).
+- `src/core/brain/mcp-route-latency.ts` — NEW (C2).
+- `src/core/brain/token-impact-ledger.ts` — NEW (C3).
+- `src/core/brain/active-budget-pressure.ts` — NEW (C4).
+- `src/core/brain/context-pack-outcome.ts` — NEW (C5).
+- `src/core/brain/context-pack.ts` — density comparator (C1) + token-impact emit
+ in finalize (C3).
+- `src/core/brain/active-budget.ts` / `doctor.ts` — C4 pressure check + candidate
+ listing.
+- `src/mcp/tools.ts` — latency wrapper in `buildToolTable` (C2); new MCP/CLI
+ readers for C2/C3/C5 summaries.
+- Tests under `tests/core/brain/` and `tests/mcp/` per card (TDD).
+- `CHANGELOG.md`, `docs/observability.md` — document the new signals.
+
+## Risks
+
+- **Byte-identity regression (C1).** A density comparator that fires by default
+ reorders every pack and breaks the determinism contract. Mitigation:
+ default-off flag; when off the score map is empty and the sort is identical to
+ today; a dedicated bit-identity test (pack with flag off == pack without the
+ flag at all).
+- **Shared-file conflict (C1+C3 in `context-pack.ts`).** Mitigation: drive order
+ C1 → C3 touches disjoint regions (sort vs finalize); each card pulls before
+ starting.
+- **Privacy leak via latency/argument logging (C2).** Mitigation: record tool
+ name/duration/status + arg-shape hash over KEYS only, never values; redaction
+ through the continuity store's `safeContinuityPayload`; default-off flag.
+- **Overclaiming token savings (C3/C5).** Mitigation: strict exact-vs-modeled
+ separation in the payload schema; honest `basis` label; modeled values are
+ confidence-banded; the three token signals in C5 never merge.
+- **Name clash with `WatermarkState` (C4).** Mitigation: distinct term "active
+ budget pressure"; grep guard in tests.
+- **Schema churn coupling.** Variant 2's risk, avoided here: each card owns its
+ payload shape; the shared kernel is only list/summarize plumbing.
diff --git a/docs/brainstorm/context-pack-economics-observability/plan.md b/docs/brainstorm/context-pack-economics-observability/plan.md
new file mode 100644
index 00000000..1bf9a110
--- /dev/null
+++ b/docs/brainstorm/context-pack-economics-observability/plan.md
@@ -0,0 +1,188 @@
+# Implementation plan — Context-pack memory-economics & observability
+
+Branch: `feat/context-pack-economics-observability`. Cards are driven ONE AT A
+TIME on this shared branch. Each worker MUST `git pull` / build on the commits
+previously-driven in-scope cards already landed, and must not duplicate or
+conflict with sibling tasks. Follow TDD: write the failing test first.
+
+Combined design: `docs/brainstorm/context-pack-economics-observability/design.md`.
+Drive order: **C2 → C1 → C3 → C4 → C5**.
+
+In-scope cards (ship together in this one release):
+- `t_6c9a3e5c` (C2, p4) — route-level latency metrics for MCP tools
+- `t_affa3bd9` (C1, p4) — value-per-token density ranking in context-pack
+- `t_a8926bd0` (C3, p3) — durable token-impact + context-pack-quality ledger
+- `t_dfda8adb` (C4, p3) — proactive active-memory budget-pressure watermark
+- `t_f2140bae` (C5, p2) — agent-operable context-pack outcome loop
+
+---
+
+## C2 — `t_6c9a3e5c` — Route-level latency metrics for MCP tools (driven first)
+
+### Files
+- `src/core/brain/continuity/types.ts` — add `mcp_route_latency` to
+ `ContinuityRecordKind`. (Shared-kernel commit; also lands the
+ `token_impact` + `context_pack_outcome` kinds so C3/C5 don't re-touch this
+ file.)
+- `src/core/brain/continuity/readers.ts` — NEW shared
+ `listRecordsByKind(vault, kind, filter)` + `summarizeCounters(records, keys)`
+ helpers (pure, deterministic; composes the continuity store's existing
+ month-shard list + reverse/limit/filter).
+- `src/core/brain/mcp-route-latency.ts` — NEW.
+ `emitRouteLatency(vault, {tool, durationMs, status, argShapeHash?})` →
+ `ContinuityRecord` (kind `mcp_route_latency`); `listRouteLatency(vault,
+ filter)`; `summarizeRouteLatency(vault, filter)` (top slow tools, p95-ish
+ counters, by status). Payload: tool name, duration_ms, status, optional
+ arg-shape hash over KEYS only (structural), never raw prompt/note content.
+ Redaction through `safeContinuityPayload`.
+- `src/mcp/tools.ts` — in `buildToolTable`, wrap each `ToolDefinition.handler`
+ with a timing+status collector emitting one `mcp_route_latency` record per
+ call. Gated by config flag `mcp_route_latency_enabled` (default false). On
+ emission failure the tool result is unchanged (fail-open).
+- `src/mcp/...` (or CLI `o2b`) — add a reader verb exposing the summary.
+- `tests/core/brain/mcp-route-latency.test.ts` + `tests/mcp/tools-latency.test.ts`.
+
+### Acceptance (passing test)
+A test in `tests/mcp/tools-latency.test.ts` that:
+1. With `mcp_route_latency_enabled=false`, calling a tool produces byte-identical
+ output and writes NO `mcp_route_latency` record (bit-identity + zero-write
+ guard).
+2. With the flag true, calling a slow tool emits one record with the correct
+ tool name, a positive duration, and status; the summary reader returns it;
+3. Asserts the payload contains NO argument VALUES (only a key-shape hash at
+ most) — a redaction/privacy assertion.
+
+### Depends on
+None. Isolated in `tools.ts`. Driven first (opens the shared-kernel commit).
+
+---
+
+## C1 — `t_affa3bd9` — Value-per-token density ranking in context-pack
+
+### Files
+- `src/core/brain/context-density.ts` — NEW. `densityScore({body, evidenceRefs,
+ topic, principle}, tokens)` → number; computed from structural signals
+ (evidence-ref/wikilink density, signal markers) per estimated token.
+ Language-agnostic (no wordlists; same construction as
+ `deriveEpistemicStatus`). Pure, deterministic.
+- `src/core/brain/context-pack.ts` — add `densityRanking?: boolean` to
+ `ContextPackOptions`. When true, compute a `densityScore` per candidate into a
+ `densityScore` map and insert a density comparator INTO the existing
+ `candidates.sort(...)`, AFTER `sessionFocus` (full chain: tier → sessionFocus
+ → density → recency → id; map empty → default sort byte-identical). Tier stays
+ the coarse gate; tie-break recency → id. Optionally add `density?` to `ContextPackItem`
+ (absent when off → byte-identical).
+- `tests/core/brain/context-density.test.ts` + extend `context-pack` ordering
+ tests.
+
+### Acceptance (passing test)
+A test in `tests/core/brain/context-pack.test.ts` (or density test) that:
+1. Asserts the pack with `densityRanking` OFF is byte-identical to a pack with
+ the option absent entirely (the bit-identity guard);
+2. With `densityRanking` ON, a denser lower-recency entry ranks above a sparser
+ recent one WITHIN the same tier;
+3. Asserts a peripheral page NEVER outranks a core page regardless of density
+ (tier remains the coarse gate).
+
+### Depends on
+None (orthogonal). Driven second. NOTE: this card touches the
+`candidates.sort(...)` region of `context-pack.ts`; C3 (later) touches the
+`finalizeContextPackReport` region — disjoint, but pull before starting.
+
+---
+
+## C3 — `t_a8926bd0` — Durable token-impact + context-pack-quality ledger
+
+### Files
+- `src/core/brain/token-impact-ledger.ts` — NEW.
+ `emitTokenImpact(vault, {packReceiptId, exactTokens, modeledAvoidance?,
+ counterfactual?, basis})` where `basis: "tokenizer_exact" | "fallback_est"`.
+ Strict schema separation: `exact.prompt_token_delta` vs
+ `modeled.inference_avoidance` (confidence-banded) never merged. Persisted via
+ continuity store (kind `token_impact`, added in the C2 shared-kernel commit),
+ reloaded on startup through the shared reader.
+- `src/core/brain/context-pack.ts` — in `finalizeContextPackReport`, when a new
+ opt-in flag is set (`token_impact_ledger_enabled` / option), emit one
+ `token_impact` record: tokenizer-exact delta of the packed body vs an
+ un-packed baseline, with `basis` set honestly. Default-off → no record,
+ byte-identical.
+- CLI/MCP `brain_token_impact_outcome` — outcome-calibration endpoint: posts
+ first-pass/repair/retry outcomes to recalibrate the modeled band (the passive
+ endpoint C5 writes into). Reader `summarizeTokenImpact(vault, filter)`.
+- `tests/core/brain/token-impact-ledger.test.ts`.
+
+### Acceptance (passing test)
+A test in `tests/core/brain/token-impact-ledger.test.ts` that:
+1. Emits a token_impact record with `basis: "tokenizer_exact"` and asserts exact
+ and modeled fields are stored SEPARATELY (no merged field);
+2. Emits with `basis: "fallback_est"` and asserts the fallback label is present;
+3. Asserts the record survives a reload (persisted, listable) and contains NO
+ raw prompt/recalled text (privacy assertion);
+4. With the flag off, `finalizeContextPackReport` writes no record (bit-identity).
+
+### Depends on
+C2's shared-kernel commit (the `token_impact` kind + shared reader). Driven
+third.
+
+---
+
+## C4 — `t_dfda8adb` — Proactive active-memory budget-pressure watermark
+
+### Files
+- `src/core/brain/active-budget-pressure.ts` — NEW.
+ `computeActiveBudgetPressure(body, budgetChars)` → `{fillRate, status:
+ "healthy"|"elevated"|"critical", candidates: Array<{sectionKey, bytes,
+ priority}>}`. Reuses `SECTION_PRIORITIES` from `active-budget.ts` (extract to a
+ shared constant in `text-budget.ts` or `active-budget.ts` if not already
+ exported) and the same section-split logic.
+- `src/core/brain/active-budget.ts` — export `SECTION_PRIORITIES` (and the
+ split helper if shared) for reuse; no behavior change.
+- `src/core/brain/doctor.ts` — add a proactive pressure check: when `fillRate`
+ exceeds the warn threshold, list ranked eviction CANDIDATES (highest-priority-
+ to-drop first) as suggestions; "empty output = healthy" (quiet on healthy
+ vaults). Never auto-deletes.
+- `tests/core/brain/active-budget-pressure.test.ts`.
+
+### Acceptance (passing test)
+A test in `tests/core/brain/active-budget-pressure.test.ts` that:
+1. With `fillRate <= threshold`, `status` is `healthy` and the doctor check emits
+ NOTHING (quiet-on-healthy contract);
+2. With a body over budget, `status` is elevated/critical and candidates are
+ returned ranked by drop-priority (retired before confirmed);
+3. Asserts the term "active budget pressure" / does NOT collide with
+ `WatermarkState` in `skill-proposals.ts` (grep guard);
+4. Asserts no vault content is mutated (suggestions only).
+
+### Depends on
+None. Driven fourth. (If `SECTION_PRIORITIES` extraction touches
+`active-budget.ts`, that is the only shared-file seam; pull before starting.)
+
+---
+
+## C5 — `t_f2140bae` — Agent-operable context-pack outcome loop (capstone)
+
+### Files
+- `src/core/brain/context-pack-outcome.ts` — NEW.
+ `emitContextPackOutcome(vault, {sampleId, firstPassSuccess, repairRequired?,
+ retryCount?, followUpTokens?, providerTokens?, tokenSignal})` where
+ `tokenSignal: "exact" | "modeled" | "observed"` keeps the three token signals
+ strictly separate (never merged into one field). Writes a
+ `context_pack_outcome` continuity record AND posts to C3's calibration
+ endpoint. Compact counters only; agent omits a field rather than inventing it.
+- `src/core/brain/context-pack.ts` (or the receipt/report path) — carry the
+ latest sample id as bounded local state in the pack report/receipt (not a
+ daemon). On completion the agent posts the outcome row.
+- MCP/CLI surface to post the outcome row.
+- `tests/core/brain/context-pack-outcome.test.ts`.
+
+### Acceptance (passing test)
+A test in `tests/core/brain/context-pack-outcome.test.ts` that:
+1. Posts an outcome row and asserts the three token signals (exact/modeled/
+ observed) are stored as SEPARATE fields, never merged;
+2. Asserts the record contains only compact counters — NO raw prompts,
+ completions, source text, or secrets (privacy assertion);
+3. Asserts a missing field is OMITTED, not invented (omit-don't-invent guard);
+4. Asserts the outcome also appears in C3's ledger calibration (composes C3).
+
+### Depends on
+C3 (hard dependency — the outcome loop writes into C3's ledger). Driven last.
diff --git a/docs/brainstorm/context-pack-economics-observability/variants.md b/docs/brainstorm/context-pack-economics-observability/variants.md
new file mode 100644
index 00000000..c652aa55
--- /dev/null
+++ b/docs/brainstorm/context-pack-economics-observability/variants.md
@@ -0,0 +1,60 @@
+# Variants — Context-pack memory-economics & observability
+
+Verbatim consultant output (`claude-opus-4-8`) + final rationale.
+
+## Variant 1 — Five parallel verticals
+Approach: Ship each card as a self-contained vertical that mirrors the existing `recall-telemetry.ts` triplet (`emit*` / `list*` / `summarize*`), each with its own new `ContinuityRecordKind`, its own gate (config flag or opt-in option), and its own reader verb. The only cross-module edge is Card 5 importing Card 3's ledger API; everything else is isolated. Card 1 slots a density comparator into the existing within-tier sort exactly as `sessionFocus` already does (byte-identical when the score map is empty).
+Trade-offs:
+- Maximum independence: each card's default-off branch is trivially and locally provable byte-identical, and each is genuinely PR-shippable alone.
+- Reader surface fragments into five new summaries with duplicated list/filter/reverse/limit boilerplate, and no single "prompt-economics" view ties Cards 2/3/4/5 together.
+- Two shared files still collide (`context-pack.ts` for Cards 1+3; `continuity/types.ts` for Cards 2+3+5), so drive order still has to serialize them regardless of the isolation.
+Complexity: medium
+Risk: low
+
+## Variant 2 — Economics ledger spine first
+Approach: Build Card 3's durable token-impact + quality ledger first as a unifying substrate — one economics kind-family, one reader framework, one `/outcome`-style calibration endpoint — then hang Cards 2 (route latency), 4 (budget-pressure watermark), and 5 (outcome loop) onto that spine as thin emitters, leaving Card 1 as the sole standalone ordering change. One consolidated economics reader surfaces all four signals.
+Trade-offs:
+- Cohesive single prompt-economics surface with minimal reader duplication; Card 5 sits on Card 3 with almost no glue, and the "three token signals kept strictly separate" invariant is enforced once in the shared schema.
+- Front-loads the largest, highest-schema-risk card and couples the quick p4 wins to it, weakening the "five independently shippable signals" requirement and delaying byte-identical-off verification behind a broad substrate.
+- If the shared schema needs to change after Cards 2/4 land on it, every dependent card's persisted records and readers churn together.
+Complexity: large
+Risk: medium
+
+## Variant 3 — Thin shared kernel, parallel modules, priority-ordered drive
+Approach: Add only the reuse that is real — extend `ContinuityRecordKind` with the new kinds in one small commit and introduce one tiny shared list/summarize helper that each card's reader composes — while keeping every card's pure logic in its own module behind its own gate. Drive in priority-and-collision order: Card 2 (isolated in `tools.ts`) → Card 1 (`context-pack.ts` sort comparator) → Card 3 (`context-pack.ts` `finalizeContextPackReport` emit region + ledger) → Card 4 (`active-budget.ts` `SECTION_PRIORITIES` reuse → `doctor.ts`) → Card 5 (on Card 3's ledger).
+Trade-offs:
+- Balances cohesion and independence: one small helper removes 5× reader boilerplate without coupling card schemas, and each card keeps a locally-provable byte-identical off-branch.
+- Drive order resolves both shared-file collisions — Card 1 (sort) and Card 3 (finalize) touch disjoint regions of `context-pack.ts` in sequence, and the three `types.ts` kind additions serialize cleanly.
+- The shared reader helper is a modest new abstraction to maintain, and the ordering discipline must be honored on the branch or the two `context-pack.ts` cards rebase-conflict.
+Complexity: medium
+Risk: low
+
+## Recommended: Variant 3
+It honors the release's stated shape — five deterministic, independently-shippable signals that reuse existing machinery — without either fragmenting the reader surface (Variant 1) or over-coupling the cards to a premature spine (Variant 2). The thin kernel captures exactly the reuse the codebase already rewards: `emitGatedTelemetry`'s fail-open no-work-when-off contract, the continuity store's append/list model, and the `sessionFocus` within-tier-boost precedent that makes Card 1's density score byte-identical when disabled. Its priority-ordered drive (p4 quick wins → p3 measurement → p2 capstone) matches the only hard dependency (Card 3 → Card 5) while serializing the `context-pack.ts` and `continuity/types.ts` collisions, so each card lands and ships on its own. The one new abstraction is small and earns its place by eliminating five copies of list/filter/summarize boilerplate.
+
+---
+
+## Final decision: Variant 3
+
+**Agreed with the consultant's recommendation.** Variant 3 is the right fit
+because it preserves o2b's two load-bearing invariants that the other variants
+strain:
+
+1. **Byte-identity-when-off.** Each card keeps a locally-provable off-branch
+ (empty score map for C1, no-op emit for C2/C3/C5, quiet-when-healthy for C4).
+ Variant 2's shared spine would force byte-identity verification across a broad
+ substrate and couple the quick p4 wins to the largest card's schema risk.
+2. **Independently shippable signals.** The release's whole premise is five
+ signals that compose existing machinery rather than refactor it. Variant 1
+ satisfies independence but fragments the reader surface into five
+ near-duplicate triplets — a DRY violation the codebase explicitly avoids
+ (`applyCharBudget`, `emitGatedTelemetry` already exist to prevent exactly
+ this).
+
+The thin shared kernel (3 new continuity kinds + one list/summarize helper) is
+the minimum reuse that is real, and the priority-ordered drive
+(C2 → C1 → C3 → C4 → C5) serializes the only two genuine shared-file collisions
+(`context-pack.ts` sort-vs-finalize regions; `continuity/types.ts` kind additions)
+while honoring the one hard dependency (C3 → C5).
+
+Drive order: **C2 → C1 → C3 → C4 → C5**.
diff --git a/docs/mcp.md b/docs/mcp.md
index 16c4b8a3..a0ab4471 100644
--- a/docs/mcp.md
+++ b/docs/mcp.md
@@ -50,6 +50,9 @@ flags for a narrower per-process full server.
| `brain_context_pack` | Budgeted context slice; pass `lanes: true` to return directives, constraints, and consider lanes. Filtered items include `safety.reasons`. Each item carries a structural `epistemic` status (`observed` \| `derived` \| `hypothesis` \| `plan` \| `unknown`) plus `evidence_refs` derived from existing graph metadata; fields are absent when the status is `unknown`. | `max_tokens` |
| `brain_context_receipts` | List or show opt-in prompt context receipt continuity records with budgets, hashes, source refs, safety/redaction metadata, and item IDs. | `operation` |
| `brain_recall_telemetry` | List or summarise opt-in recall telemetry records for search, context-pack, and pre-compress calls. | `operation` |
+| `brain_route_metrics` | List or summarise opt-in route-level MCP tool latency (`mcp_route_latency` records); `summary` rolls each tool up into count, error count, and min/avg/max + p50/p95/p99 latency, slowest-first. Emitted only when `mcp_route_metrics_enabled` is on; payload-safe (tool, scope, status, duration, arg key names). Read-only. | `operation` |
+| `brain_token_impact` | Durable value-of-memory ledger: `record` posts a context pack's tokenizer-exact prompt-token delta (`baseline` − `packed`, `method` exact/fallback) plus an optional modeled inference-avoidance estimate; `outcome` posts first-pass/repair/retry to calibrate the model; `summary` keeps EXACT prompt-token savings strictly separate from the MODELED (outcome-calibrated) figure; `list` reads raw samples. Writes gated on `token_impact_ledger_enabled` (default off); payload-safe (counts + opaque pack id only). Reads ignore the gate. | `operation` |
+| `brain_context_pack_outcome`| Agent-operable outcome loop over the context-pack quality ledger: `post` records one compact outcome row for a carried context-pack quality-sample id — first-pass/repair/retry counters plus three STRICTLY SEPARATE token signals (`exact_prompt_token_savings`, `modeled_inference_avoidance`, `observed_provider_tokens`) — and composes the token-impact ledger by posting a matching first-pass/repair/retry calibration outcome; `list`/`summary` read the rows keeping the signals separate. Writes gated on `context_pack_outcome_enabled` (default off); payload-safe (counters + opaque sample id only), a field the caller omits is never invented. Reads ignore the gate. | `operation` |
| `brain_knowledge_gaps` | Aggregate the persisted cross-query demand log into recurring queries the vault answers poorly, ranked by frequency × (1 − IDF-weighted coverage). Read-only; the log is written only by opt-in recall telemetry. | — |
| `brain_generation_reports` | Inbound, opt-in LLM generation tracing: `record` posts a generation's usage for a handoff (gated, default off; stores prompt hash + token counts only); `list`/`summary` read records and join them to memory paths. Kernel never calls an LLM. | `action` |
| `brain_obligation` | Recurring obligations under `Brain/obligations/` with a deterministic cadence-driven next-due date: `add`, `done` (advances next_due by one cadence interval), `list` (optionally overdue-only), `show`, `remove`. Cadences: daily/weekly/biweekly/monthly/quarterly/yearly/every-<N>-days. | `operation` |
@@ -337,6 +340,15 @@ decision when the `recall_gate_telemetry` config key is `"true"`
never the raw prompt. `brain_recall_telemetry` gains `gate_list` /
`gate_summary` operations.
+The MCP server emits one `mcp_route_latency` continuity record per tool
+call when the `mcp_route_metrics_enabled` config key
+(`OPEN_SECOND_BRAIN_MCP_ROUTE_METRICS_ENABLED`) is `"true"` (default
+off): tool name, scope, status (`ok`/`error`), duration, and the sorted
+set of argument KEY NAMES only - never argument values. The emit is
+gated and fail-open, so it can never fail or slow-fail the call it
+measures beyond one synchronous continuity append. `brain_route_metrics`
+reads them back (`operation: "list"|"summary"`).
+
The full observability contract behind these tools - event kinds,
always-on vs opt-in status, correlation IDs, payload safety, and the
continuity schema version - lives in `docs/observability.md`.
diff --git a/docs/observability.md b/docs/observability.md
index 20e73466..1a858e38 100644
--- a/docs/observability.md
+++ b/docs/observability.md
@@ -37,6 +37,10 @@ Every continuity record shares one envelope: `schema`, `id`, `kind`, `createdAt`
| `context_receipt` | opt-in per call (`receipt` option/param) | `packContext`, `buildPreCompressPack` |
| `gate_telemetry` | config key `recall_gate_telemetry` (default off) | `brain_recall_gate` MCP handler |
| `generation_report` | opt-in per call (`enable`) or config key `generation_trace_enabled` (default off) | inbound agent report after a generation handoff (`brain_generation_reports` action `record`, `o2b brain generation-reports record`) |
+| `mcp_route_latency` | config key `mcp_route_metrics_enabled` (default off) | the MCP server's tool-call seam (`MCPServer.invokeToolHandler` in `src/mcp/server.ts`) - one record per `tools/call` and per CLI-bridge `callTool`; payload carries the tool name, scope, status, duration, and argument KEY NAMES only, never argument values |
+| `token_impact` | config key `token_impact_ledger_enabled` (default off) | `brain_token_impact` action `record` (`emitTokenImpact` in `src/core/brain/token-impact.ts`) - one sample per context pack; payload carries the tokenizer-exact prompt-token counts (`baseline_tokens`, `packed_tokens`, signed `delta_tokens`), the `method` label (`exact`/`fallback`), an optional opaque `pack_id`, and the optional modeled inference-avoidance estimate - never raw prompts or recalled text |
+| `token_impact_outcome` | config key `token_impact_ledger_enabled` (default off) | `brain_token_impact` action `outcome` (`recordTokenImpactOutcome`) - one first-pass/repair/retry post used only to calibrate the modeled ledger |
+| `context_pack_outcome` | config key `context_pack_outcome_enabled` (default off) | `brain_context_pack_outcome` action `post` (`emitContextPackOutcome` in `src/core/brain/context-pack-outcome.ts`) - one compact per-sample outcome row for a carried context-pack quality-sample id: first-pass/repair/retry counters plus three STRICTLY SEPARATE token signals (`exact_prompt_token_savings`, `modeled_inference_avoidance`, `observed_provider_tokens`), never merged; also composes a matching `token_impact_outcome` calibration post; payload carries counters + an opaque `sample_id` only, never raw prompts or recalled text, and a caller-omitted field is not invented |
| `session_turn`, `session_summary_node` | always-on within its operation | session-recall import (`src/core/brain/session-recall.ts`) - the write IS the operation |
| `pre_compact_extract` | always-on within its operation | explicit pre-compact extraction (`src/core/brain/pre-compact-extract.ts`) |
| `source_invalidation` | always-on within its operation | source drift detection (`appendContinuitySourceInvalidation`) |
@@ -74,6 +78,7 @@ Every continuity payload passes `safeContinuityPayload()` (`src/core/brain/conti
- The sanitized payload is deep-frozen; nothing mutates it after the flags are computed.
- `gate_telemetry` never stores the raw prompt by construction - only a SHA-256 prefix (`prompt_hash`) and the length (`prompt_chars`). The test suite asserts this against the persisted files, not just returned values.
- `generation_report` follows the same rule: the handoff prompt is hashed and counted but never persisted - only `prompt_hash` (full SHA-256 hex) and `prompt_chars` land on disk, plus token counts. The kernel never calls an LLM; the report is the agent's INBOUND record after it performed a generation for a brain handoff, so the local token estimate (`local_estimate.input_tokens`) is always present while the agent-reported `usage` block is present only when supplied - absent is reported as absent, never fabricated. A grep-guarded regression test pins that no `fetch`/provider HTTP call exists under `src/core` for this feature, and a persisted-file assertion confirms no raw prompt survives.
+- `mcp_route_latency` records the route (tool name), MCP scope, status, duration, and the sorted set of argument KEY NAMES only - the tool's own JSON-Schema property names, never operator-supplied argument values - so no prompt, note body, or preference id can land on disk. A persisted-file test asserts key names survive while values never do.
- Read-side consumers (trajectory export, bench) get the masking policy from the read-model: records flagged `private` are dropped by default and kept only on explicit request; masked text is never un-masked.
## Fail-open rules
@@ -90,6 +95,8 @@ No-consumer regression tests cover each gated surface, so a future call site can
- `brain_recall_telemetry` (MCP) and `o2b brain recall-telemetry list|summary|gate-list|gate-summary` aggregate recall and gate records.
- `brain_recall_telemetry` `operation: "cost"` (MCP) and `o2b brain recall-telemetry cost` fold WRITE volume against the read telemetry above: memory-write ops (Brain-log `feedback`/`apply-evidence`/`note` verbs plus `host_memory_write` continuity records) are counted per period and reported alongside reads as a write-vs-read ratio, a `write_heavy` flag, and a rough weighted cost signal. Weights (`--write-cost`/`--read-cost`, default 1 each) model "some tools charge on write, some on read"; `--write-heavy-ratio` (default 1) sets the write-heavy threshold. Read-only; period-scoped by `--since`/`--until`. `brain_create_note` file creation emits no telemetry event today and is not counted.
- `brain_context_receipts` and `o2b brain context-receipts` inspect served-context receipts.
+- `brain_route_metrics` (MCP, `operation: "list"|"summary"`) reads route-level MCP tool latency. `list` returns raw `mcp_route_latency` records (filter by `tool`/`status`/`since`/`until`/`limit`); `summary` rolls each tool up into count, error count, and min/avg/max plus p50/p95/p99 latency, ordered slowest-first so an operator can identify which endpoint blocks an agent turn by route rather than by aggregate benchmark. Records are emitted only when `mcp_route_metrics_enabled` is on (default off); read-only.
+- `brain_token_impact` (MCP, `operation: "record"|"outcome"|"list"|"summary"`) is the durable value-of-memory ledger. `record` posts one context pack's tokenizer-exact prompt-token delta (`baseline_tokens` − `packed_tokens`, labelled `method: exact|fallback`) plus an optional modeled inference-avoidance estimate (`modeled_avoided_inferences` × `modeled_tokens_per_inference`); `outcome` posts a `first_pass`/`repair`/`retry` result. `summary` keeps the two ledgers STRICTLY SEPARATE: `prompt_token_delta` reports the measured net/saved/added tokens with a per-`method` split (so an exact count is never averaged in with a fallback estimate), while `modeled_inference_avoidance` reports the raw modeled figure and a `calibrated_savings_tokens` dampened by the observed first-pass rate from posted outcomes (null until an outcome exists — uncalibrated, not zero). `list` returns raw samples (filter by `pack_id`/`method`/`host`/`since`/`until`/`limit`); `summary` accepts `max_samples` to bound aggregation. Writes are emitted only when `token_impact_ledger_enabled` is on (default off) and are payload-safe (counts + opaque `pack_id` only, never prompts or recalled text); `list`/`summary` read regardless of the gate. Aggregates are recomputed from the continuity store on every read, so they survive restarts.
- `brain_event_trace` (MCP) and `o2b brain event-trace` join the Brain log to the continuity store: given a logged event (by day, `--at` stamp, kind, or `--session-id`), they resolve the continuity records attached to it via the stable correlation ids above (`session_id`, `turn_id`, and artifact `sourceRefs`), so an operator can answer "which context was supplied to this action?" from one surface. Each attached record reports `joinedBy` (`session` / `turn` / `artifact`); open the full record through the per-kind readers (`context-receipts show`, `recall-telemetry`, `generation-reports show`). Read-only; `private` records are dropped unless explicitly kept.
- `brain_generation_reports` (MCP, actions `record`/`list`/`summary`) and `o2b brain generation-reports record|list|summary|show` post and read inbound LLM generation traces. `summary` rolls up call counts, the always-present local token estimate, agent-reported usage where present, and a per-path linkage map so a memory path resolves back to the generation reports that produced or consumed it.
- `o2b brain continuity export --format atof|atif` renders the store as standard trajectory formats (ATOF JSONL event stream; ATIF v1.7 one document per session) for replay and eval tooling. Read-only; `private` records never reach an export file. Mapping decisions: `docs/brainstorm/memory-observability-suite/atof-atif-mapping.md`.
diff --git a/openclaw.plugin.json b/openclaw.plugin.json
index bbfc3e2f..2588efc9 100644
--- a/openclaw.plugin.json
+++ b/openclaw.plugin.json
@@ -2,7 +2,7 @@
"id": "open-second-brain",
"name": "Open Second Brain",
"description": "Second brain for AI agents using Obsidian-compatible Markdown vaults.",
- "version": "1.24.0",
+ "version": "1.25.0",
"activation": { "onStartup": true },
"skills": ["./skills"],
"contracts": {
diff --git a/package.json b/package.json
index a1cf287e..28ed0af3 100644
--- a/package.json
+++ b/package.json
@@ -1,6 +1,6 @@
{
"name": "open-second-brain",
- "version": "1.24.0",
+ "version": "1.25.0",
"private": false,
"description": "Second brain for AI agents using Obsidian-compatible Markdown vaults. Works with Hermes, Claude Code, Codex, and OpenClaw.",
"keywords": [
diff --git a/plugin.yaml b/plugin.yaml
index e803f447..e163cf42 100644
--- a/plugin.yaml
+++ b/plugin.yaml
@@ -1,5 +1,5 @@
name: open-second-brain
-version: "1.24.0"
+version: "1.25.0"
description: "Open Second Brain - native Hermes memory provider backed by an Obsidian-compatible Markdown vault."
author: "Open Second Brain contributors"
memory_provider: true
diff --git a/plugins/codex/.codex-plugin/plugin.json b/plugins/codex/.codex-plugin/plugin.json
index f0544400..120210a6 100644
--- a/plugins/codex/.codex-plugin/plugin.json
+++ b/plugins/codex/.codex-plugin/plugin.json
@@ -1,6 +1,6 @@
{
"name": "open-second-brain",
- "version": "1.24.0",
+ "version": "1.25.0",
"description": "Plugin-first second brain package for Codex, Hermes, Claude Code, OpenClaw, and other agent runtimes.",
"author": {
"name": "Open Second Brain contributors",
diff --git a/plugins/hermes/plugin.yaml b/plugins/hermes/plugin.yaml
index e803f447..e163cf42 100644
--- a/plugins/hermes/plugin.yaml
+++ b/plugins/hermes/plugin.yaml
@@ -1,5 +1,5 @@
name: open-second-brain
-version: "1.24.0"
+version: "1.25.0"
description: "Open Second Brain - native Hermes memory provider backed by an Obsidian-compatible Markdown vault."
author: "Open Second Brain contributors"
memory_provider: true
diff --git a/pyproject.toml b/pyproject.toml
index a29556b6..6eda7ca6 100644
--- a/pyproject.toml
+++ b/pyproject.toml
@@ -10,7 +10,7 @@ build-backend = "setuptools.build_meta"
# CLI entry points (those moved to `package.json` `bin`).
[project]
name = "open-second-brain"
-version = "1.24.0"
+version = "1.25.0"
description = "Hermes Python shim for Open Second Brain. Most of the project (CLI, MCP server, OpenClaw plugin) is TypeScript on Bun; see package.json."
readme = "README.md"
requires-python = ">=3.11"
diff --git a/src/core/brain/active-budget-pressure.ts b/src/core/brain/active-budget-pressure.ts
new file mode 100644
index 00000000..f878de86
--- /dev/null
+++ b/src/core/brain/active-budget-pressure.ts
@@ -0,0 +1,150 @@
+/**
+ * Proactive active-memory budget-pressure watermark
+ * (context-pack-economics-observability, C4 / t_dfda8adb).
+ *
+ * `Brain/active.md` is enforced REACTIVELY: `active-budget.ts` drops
+ * sections at render/inject time once the body overflows the byte
+ * budget, and prints a one-line truncation notice. Nothing warns the
+ * operator BEFORE the wall - content simply disappears from the
+ * injection.
+ *
+ * This module adds the missing PROACTIVE signal. It measures how full
+ * the active body is against its byte budget (a "water level" /
+ * fill-rate), classifies it into a health status, and - only when
+ * pressure crosses the warn threshold - names the specific sections an
+ * operator could archive to relieve it. The eviction candidates reuse
+ * the exact drop order the reactive truncation uses
+ * (`SECTION_PRIORITIES` from `active-budget.ts`), so the advance
+ * warning matches what would actually be dropped.
+ *
+ * Contract:
+ * - **Empty output = healthy.** At or below the warn threshold the
+ * status is `healthy` and `candidates` is empty; the doctor/hygiene
+ * surfaces stay quiet on healthy vaults.
+ * - **Keep-guard.** Priority-0 content (the document preamble and the
+ * Confirmed rules) is a live rule/config the probe never proposes
+ * for eviction - only pure stale history (retired, quarantine,
+ * most-applied, unknown future sections) is a candidate.
+ * - **Suggestions only.** Candidates are surfaced to the operator /
+ * dream; nothing here mutates the vault or auto-archives anything.
+ * - **Pure and deterministic.** Byte/section counting, no LLM, no
+ * clock, no I/O. Identical inputs produce identical output.
+ *
+ * NOTE: "active budget pressure" is deliberately distinct from the
+ * unrelated last-processed-cursor state in `skill-proposals.ts` - same
+ * English word ("watermark"), different concept. This module never
+ * reuses that identifier.
+ */
+
+import { KEEP_GUARD_PRIORITY, priorityFor, splitSections } from "./active-budget.ts";
+
+/**
+ * Fill-rate at or below this is `healthy` (quiet). Between this and
+ * {@link CRITICAL_THRESHOLD} is `elevated`; at or above the critical
+ * threshold is `critical`. Owned here, not derived from any
+ * pre-existing symbol.
+ */
+export const ELEVATED_THRESHOLD = 0.75;
+export const CRITICAL_THRESHOLD = 0.9;
+
+export type BudgetPressureStatus = "healthy" | "elevated" | "critical";
+
+/**
+ * One section an operator could archive to relieve pressure, ranked in
+ * the order the reactive truncation would drop it (highest-priority-to-
+ * drop first). `sectionKey` is the section's `## ` heading (or
+ * `"preamble"` for the leading block, which never appears as a
+ * candidate since it shares the keep-guard priority).
+ */
+export interface EvictionCandidate {
+ readonly sectionKey: string;
+ /** Byte length of the section text. */
+ readonly bytes: number;
+ /** Drop priority (higher drops first); always > {@link KEEP_GUARD_PRIORITY}. */
+ readonly priority: number;
+}
+
+export interface ActiveBudgetPressure {
+ /** `body.length / budgetChars`, clamped at 0 for a non-positive budget. */
+ readonly fillRate: number;
+ readonly status: BudgetPressureStatus;
+ /** Byte length of the measured body. */
+ readonly bytes: number;
+ /** The budget the body was measured against. */
+ readonly budgetChars: number;
+ /**
+ * Ranked eviction candidates, highest-priority-to-drop first. Empty
+ * when the status is `healthy` (empty output = healthy) or when the
+ * body has no droppable (non-keep-guard) sections.
+ */
+ readonly candidates: ReadonlyArray<EvictionCandidate>;
+}
+
+/** First `## ` heading of a section slice, or `"preamble"`. */
+function sectionHeading(text: string): string {
+ const firstLine = text.slice(0, text.indexOf("\n") === -1 ? undefined : text.indexOf("\n"));
+ return firstLine.startsWith("## ") ? firstLine : "preamble";
+}
+
+function statusFor(fillRate: number): BudgetPressureStatus {
+ if (fillRate >= CRITICAL_THRESHOLD) return "critical";
+ if (fillRate > ELEVATED_THRESHOLD) return "elevated";
+ return "healthy";
+}
+
+/**
+ * Measure `body` against `budgetChars` and, when pressure crosses the
+ * warn threshold, return the sections an operator could archive to
+ * relieve it. See the module docblock for the full contract.
+ *
+ * A non-positive or non-finite budget is treated as fully saturated
+ * (`fillRate` of `Infinity`, `critical`): a zero budget means every
+ * byte overflows.
+ */
+export function computeActiveBudgetPressure(
+ body: string,
+ budgetChars: number,
+): ActiveBudgetPressure {
+ const bytes = body.length;
+ const budget = Number.isFinite(budgetChars) ? budgetChars : 0;
+ const fillRate = budget > 0 ? bytes / budget : bytes > 0 ? Infinity : 0;
+ const status = statusFor(fillRate);
+
+ // Empty output = healthy: no candidates unless pressure is real.
+ if (status === "healthy") {
+ return Object.freeze({
+ fillRate,
+ status,
+ bytes,
+ budgetChars: budget,
+ candidates: Object.freeze([]),
+ });
+ }
+
+ const sections = splitSections(body);
+ const candidates: Array<EvictionCandidate & { readonly index: number }> = [];
+ sections.forEach((section, index) => {
+ const heading = sectionHeading(section.text);
+ // `splitSections` assigns the preamble/first-heading slice priority
+ // 0; re-derive from the heading so the classification is explicit
+ // and robust to the merged-preamble slice.
+ const priority = heading === "preamble" ? KEEP_GUARD_PRIORITY : priorityFor(heading);
+ if (priority <= KEEP_GUARD_PRIORITY) return; // keep-guard: live rule/config
+ candidates.push({ sectionKey: heading, bytes: section.text.length, priority, index });
+ });
+
+ // Rank in the exact reactive drop order: highest priority first,
+ // ties broken by later render position first (matches
+ // `leastImportantIndex` in text-budget.ts).
+ candidates.sort((a, b) => b.priority - a.priority || b.index - a.index);
+
+ return Object.freeze({
+ fillRate,
+ status,
+ bytes,
+ budgetChars: budget,
+ candidates: Object.freeze(
+ candidates.map(({ sectionKey, bytes: b, priority }) => ({ sectionKey, bytes: b, priority })),
+ ),
+ });
+}
diff --git a/src/core/brain/active-budget.ts b/src/core/brain/active-budget.ts
index 4d59f3eb..e87c425c 100644
--- a/src/core/brain/active-budget.ts
+++ b/src/core/brain/active-budget.ts
@@ -24,17 +24,32 @@ export const ACTIVE_TRUNCATION_NOTICE =
* The preamble (everything before the first `## `) shares priority 0
* with Confirmed. Unknown future sections sit between most-applied
* and quarantine.
+ *
+ * Exported so the proactive budget-pressure probe
+ * (`active-budget-pressure.ts`) ranks eviction candidates against the
+ * exact same drop order this reactive truncation uses - the two
+ * surfaces must never disagree about which section goes first.
*/
-const SECTION_PRIORITIES: ReadonlyArray<{ readonly prefix: string; readonly priority: number }> = [
+export const SECTION_PRIORITIES: ReadonlyArray<{
+ readonly prefix: string;
+ readonly priority: number;
+}> = [
{ prefix: "## Confirmed", priority: 0 },
{ prefix: "## Most-applied", priority: 1 },
{ prefix: "## Quarantine", priority: 3 },
{ prefix: "## Recently retired", priority: 4 },
];
-const UNKNOWN_SECTION_PRIORITY = 2;
+/**
+ * Priority shared by the preamble and any priority-0 section (Confirmed).
+ * A section at this priority is a live rule/config the pressure probe
+ * treats as a keep-guard: it is never proposed as an eviction candidate.
+ */
+export const KEEP_GUARD_PRIORITY = 0;
-function priorityFor(heading: string): number {
+export const UNKNOWN_SECTION_PRIORITY = 2;
+
+export function priorityFor(heading: string): number {
for (const { prefix, priority } of SECTION_PRIORITIES) {
if (heading.startsWith(prefix)) return priority;
}
@@ -44,8 +59,11 @@ function priorityFor(heading: string): number {
/**
* Split a rendered active.md body into `## `-delimited sections,
* keeping the preamble attached to the front of the first slice.
+ *
+ * Exported for reuse by the budget-pressure probe so both surfaces
+ * split identically.
*/
-function splitSections(body: string): BudgetSection[] {
+export function splitSections(body: string): BudgetSection[] {
const lines = body.split("\n");
const sections: BudgetSection[] = [];
let currentKey = "preamble";
diff --git a/src/core/brain/context-density.ts b/src/core/brain/context-density.ts
new file mode 100644
index 00000000..3e5d03f3
--- /dev/null
+++ b/src/core/brain/context-density.ts
@@ -0,0 +1,86 @@
+/**
+ * Value-per-token density scoring for context-pack candidates
+ * (impact-per-token allocation, t_affa3bd9).
+ *
+ * As a vault grows, a tier + recency ordering fills a fixed token
+ * budget with recent-but-low-value pages and skips denser high-signal
+ * ones (`pagesSkipped` overflow of important content). This module
+ * computes a deterministic, no-LLM "impact per estimated token" score
+ * from structural signals ALREADY on a candidate - grounding evidence,
+ * internal connectivity, and epistemic status - so the pack can rank
+ * the densest signal first WITHIN a tier without a language-specific
+ * wordlist or a model judgement.
+ *
+ * Language-agnostic by construction: every signal is a structural count
+ * (wikilink markers, evidence-ref count) or a fixed epistemic token,
+ * never natural-language vocabulary - the same approach as
+ * `deriveEpistemicStatus`.
+ *
+ * Pure and deterministic: the same inputs always yield the same score,
+ * so a density-ranked pack stays reproducible across runs.
+ */
+
+import { EPISTEMIC_STATUS, type EpistemicStatus } from "./provenance/epistemic.ts";
+
+/** The structural signals a density score reads off a candidate. */
+export interface DensitySignalSource {
+ /** Surfaced body (post-safety), scanned for internal wikilink markers. */
+ readonly body: string;
+ /** `evidenced_by` wikilinks grounding the page; each is a grounding signal. */
+ readonly evidenceRefs: ReadonlyArray<string>;
+ /** Epistemic grounding of the page (observed → unknown). */
+ readonly epistemic: EpistemicStatus;
+}
+
+/**
+ * Epistemic grounding weight, most-grounded first. A source-backed fact
+ * carries more signal per token than an unconfirmed conjecture; a
+ * contested/unknown page carries none. A fixed structural token set,
+ * never natural-language vocabulary.
+ */
+const EPISTEMIC_WEIGHT: Readonly<Record<EpistemicStatus, number>> = Object.freeze({
+ [EPISTEMIC_STATUS.observed]: 3,
+ [EPISTEMIC_STATUS.derived]: 2,
+ [EPISTEMIC_STATUS.hypothesis]: 1,
+ [EPISTEMIC_STATUS.plan]: 1,
+ [EPISTEMIC_STATUS.unknown]: 0,
+});
+
+/** Signal weight per cited evidence link (grounding). */
+const EVIDENCE_WEIGHT = 2;
+/** Signal weight per internal `[[wikilink]]` in the body (connectivity). */
+const LINK_WEIGHT = 1;
+
+const WIKILINK = /\[\[[^\]]+\]\]/g;
+
+/**
+ * Count `[[...]]` wikilink markers in a body. Structural marker match
+ * only - no vocabulary, so it counts links in any script.
+ */
+export function countWikilinks(body: string): number {
+ const matches = body.match(WIKILINK);
+ return matches ? matches.length : 0;
+}
+
+/**
+ * Aggregate structural signal for a candidate: grounding evidence,
+ * internal connectivity, and epistemic weight. Never negative; a bare,
+ * link-less, contested page scores 0.
+ */
+export function signalWeight(source: DensitySignalSource): number {
+ const evidence = source.evidenceRefs.length * EVIDENCE_WEIGHT;
+ const links = countWikilinks(source.body) * LINK_WEIGHT;
+ const epistemic = EPISTEMIC_WEIGHT[source.epistemic] ?? 0;
+ return evidence + links + epistemic;
+}
+
+/**
+ * Value-per-token density: structural signal divided by the estimated
+ * token cost of the body. Higher means more useful signal packed into
+ * fewer tokens. `tokens <= 0` (or non-finite) yields 0 - a body that
+ * costs nothing to emit cannot displace a real one on density grounds.
+ */
+export function densityScore(source: DensitySignalSource, tokens: number): number {
+ if (!Number.isFinite(tokens) || tokens <= 0) return 0;
+ return signalWeight(source) / tokens;
+}
diff --git a/src/core/brain/context-pack-outcome.ts b/src/core/brain/context-pack-outcome.ts
new file mode 100644
index 00000000..f1cb6910
--- /dev/null
+++ b/src/core/brain/context-pack-outcome.ts
@@ -0,0 +1,364 @@
+/**
+ * Agent-operable context-pack outcome loop
+ * (context-pack-economics-observability suite, C5).
+ *
+ * The token-impact ledger ({@link ./token-impact.ts}) measures the
+ * prompt-token cost of the memory layer, but nothing closed the loop on
+ * *recall quality*: whether the context OSB assembled actually led to a
+ * first-pass success or forced a repair/retry. This surface is that loop.
+ *
+ * The agent carries the latest recall/context-pack quality-sample id (a
+ * context-receipt id from {@link ContextPackReport.receiptId}) through its
+ * session as BOUNDED LOCAL STATE - {@link SampleCarrier}, a small ring, not
+ * a daemon - then on completion posts one compact OUTCOME ROW correlated to
+ * that sample.
+ *
+ * THREE STRICTLY SEPARATED TOKEN SIGNALS, never merged into one headline
+ * number - each lands in its own payload key:
+ *
+ * 1. EXACT prompt-token savings (`exact_prompt_token_savings`) - a
+ * tokenizer-aware delta, a real measurement.
+ * 2. MODELED inference avoidance (`modeled_inference_avoidance`) - a
+ * confidence-banded counterfactual, a model, not a measurement.
+ * 3. OBSERVED provider usage (`observed_provider_tokens`) - what the
+ * provider actually reported.
+ *
+ * Compact counters only: the payload never carries a raw prompt, completion,
+ * source text, or secret, and the whole payload still passes
+ * `safeContinuityPayload` redaction. The agent OMITS a field it does not
+ * have rather than inventing a zero - every optional counter is written only
+ * when the caller supplies it.
+ *
+ * Composes C3: every outcome row also posts a first-pass/repair/retry
+ * calibration record to the token-impact ledger (via
+ * {@link recordTokenImpactOutcome}), correlated by the same sample id, so the
+ * modeled figure there is calibrated by measured recall outcomes.
+ *
+ * Gated + fail-open: emits route through {@link emitGatedTelemetry}, so with
+ * the gate off no payload is built and no write happens, and a throwing write
+ * never fails the operation being measured.
+ */
+
+import { emitGatedTelemetry } from "./continuity/emit.ts";
+import { appendContinuityRecord, listContinuityRecords } from "./continuity/store.ts";
+import type { ContinuityRecord } from "./continuity/types.ts";
+import { recordTokenImpactOutcome, type TokenImpactOutcome } from "./token-impact.ts";
+
+export interface ContextPackOutcomeInput {
+ readonly createdAt?: string;
+ readonly host?: string;
+ readonly sessionId?: string;
+ readonly turnId?: string;
+ /**
+ * The carried recall/context-pack quality-sample id - a context-receipt
+ * id ({@link ContextPackReport.receiptId}) or an opaque request hash. Never
+ * a raw prompt or recalled text.
+ */
+ readonly sampleId: string;
+ /** Whether the packed context led to a first-pass success (no repair/retry). */
+ readonly firstPassSuccess: boolean;
+ /** Whether the agent had to repair the first completion. */
+ readonly repairRequired?: boolean;
+ /** How many retries the completion needed. */
+ readonly retryCount?: number;
+ /** Compact count of tokens spent on follow-up turns after the first pass. */
+ readonly followUpTokens?: number;
+ /** EXACT tokenizer-aware prompt-token savings (measurement). */
+ readonly exactPromptTokenSavings?: number;
+ /** MODELED confidence-banded inference-avoidance estimate (a model). */
+ readonly modeledInferenceAvoidance?: number;
+ /** OBSERVED provider-reported token usage for this inference. */
+ readonly observedProviderTokens?: number;
+}
+
+export interface ContextPackOutcomeFilter {
+ readonly host?: string;
+ readonly sampleId?: string;
+ readonly since?: string;
+ readonly until?: string;
+ readonly limit?: number;
+ /**
+ * Cap the number of most-recent rows aggregated by
+ * {@link summarizeContextPackOutcomes}. Keeps a long-lived ledger bounded
+ * at aggregation time without truncating the durable log.
+ */
+ readonly maxSamples?: number;
+}
+
+export interface ContextPackOutcomeSummary {
+ readonly total: number;
+ readonly first_pass_success: number;
+ readonly repair_required: number;
+ /** Sum of posted `retry_count` across rows. */
+ readonly retries: number;
+ /** `first_pass_success / total`, rounded to 4 dp; null when no rows. */
+ readonly first_pass_rate: number | null;
+ /** The three token signals kept strictly separate - never a merged total. */
+ readonly token_signals: {
+ readonly exact: { readonly samples: number; readonly prompt_token_savings: number };
+ readonly modeled: { readonly samples: number; readonly inference_avoidance: number };
+ readonly observed: { readonly samples: number; readonly provider_tokens: number };
+ };
+ readonly follow_up: { readonly samples: number; readonly tokens: number };
+}
+
+/**
+ * Emit one `context_pack_outcome` row, gated and fail-open, AND post a
+ * matching first-pass/repair/retry calibration record to the token-impact
+ * ledger (C3). `gate` doubles as the opt-in switch: with
+ * `false | null | undefined` no payload is built and no write happens
+ * (returns `null`). A throwing build - including a blank sample id - is
+ * swallowed and reported as `null` so the loop can never fail the operation
+ * it measures. Returns the `context_pack_outcome` record (the calibration
+ * record is a durable side effect, listable via `listTokenImpactOutcomes`).
+ */
+export function emitContextPackOutcome<G>(
+ vault: string,
+ input: ContextPackOutcomeInput,
+ gate: G | false | null | undefined,
+): ContinuityRecord | null {
+ return emitGatedTelemetry(gate, (openGate) => {
+ const sampleId = requireSampleId(input.sampleId);
+ if (typeof input.firstPassSuccess !== "boolean") {
+ throw new TypeError("context pack outcome: firstPassSuccess must be a boolean");
+ }
+ const createdAt = input.createdAt ?? new Date().toISOString();
+ const payload: Record<string, unknown> = {
+ ...(input.host !== undefined ? { host: input.host } : {}),
+ ...(input.sessionId !== undefined ? { session_id: input.sessionId } : {}),
+ ...(input.turnId !== undefined ? { turn_id: input.turnId } : {}),
+ sample_id: sampleId,
+ first_pass_success: input.firstPassSuccess,
+ // Omit-don't-invent: every optional counter is written only when supplied.
+ ...(input.repairRequired !== undefined ? { repair_required: input.repairRequired } : {}),
+ ...(input.retryCount !== undefined
+ ? { retry_count: nonNegativeCount("retry_count", input.retryCount) }
+ : {}),
+ ...(input.followUpTokens !== undefined
+ ? { follow_up_tokens: nonNegativeCount("follow_up_tokens", input.followUpTokens) }
+ : {}),
+ // Three strictly separate token signals - never a merged headline field.
+ ...(input.exactPromptTokenSavings !== undefined
+ ? {
+ exact_prompt_token_savings: nonNegativeCount(
+ "exact_prompt_token_savings",
+ input.exactPromptTokenSavings,
+ ),
+ }
+ : {}),
+ ...(input.modeledInferenceAvoidance !== undefined
+ ? {
+ modeled_inference_avoidance: nonNegativeCount(
+ "modeled_inference_avoidance",
+ input.modeledInferenceAvoidance,
+ ),
+ }
+ : {}),
+ ...(input.observedProviderTokens !== undefined
+ ? {
+ observed_provider_tokens: nonNegativeCount(
+ "observed_provider_tokens",
+ input.observedProviderTokens,
+ ),
+ }
+ : {}),
+ };
+ const record = appendContinuityRecord(vault, {
+ kind: "context_pack_outcome",
+ createdAt,
+ sourceRefs: [],
+ payload,
+ });
+ // Compose C3: calibrate the token-impact ledger with the measured
+ // recall outcome, correlated by the same sample id. `recordTokenImpactOutcome`
+ // is itself gated + fail-open, so it never throws through this thunk.
+ recordTokenImpactOutcome(
+ vault,
+ {
+ createdAt,
+ ...(input.host !== undefined ? { host: input.host } : {}),
+ ...(input.sessionId !== undefined ? { sessionId: input.sessionId } : {}),
+ packId: sampleId,
+ outcome: deriveOutcome(input),
+ ...(input.observedProviderTokens !== undefined
+ ? { tokensPerInference: input.observedProviderTokens }
+ : {}),
+ },
+ openGate,
+ );
+ return record;
+ });
+}
+
+/**
+ * Extract the recall/context-pack quality-sample id from a pack report to
+ * carry through the session. The context-receipt id ({@link
+ * ContextPackReport.receiptId}) is the durable sample id; the telemetry id is
+ * a fallback when only telemetry was emitted. Returns null when the pack
+ * emitted neither (no opt-in receipt/telemetry) - there is then no sample to
+ * post an outcome against. Deliberately reads the report's PUBLIC ids rather
+ * than mutating its shape, so an opted-out pack stays byte-identical.
+ */
+export function contextPackSampleId(report: {
+ readonly receiptId?: string;
+ readonly telemetryId?: string;
+}): string | null {
+ return report.receiptId ?? report.telemetryId ?? null;
+}
+
+/** List `context_pack_outcome` rows newest-first, after applying filters. */
+export function listContextPackOutcomes(
+ vault: string,
+ filter: ContextPackOutcomeFilter = {},
+): ReadonlyArray<ContinuityRecord> {
+ let records = listContinuityRecords(vault, {
+ kind: "context_pack_outcome",
+ ...(filter.since !== undefined ? { since: filter.since } : {}),
+ ...(filter.until !== undefined ? { until: filter.until } : {}),
+ }).filter((record) => matchesFilter(record, filter));
+ records = records.toReversed();
+ if (filter.limit !== undefined) records = records.slice(0, Math.max(0, Math.floor(filter.limit)));
+ return Object.freeze(records);
+}
+
+/**
+ * Roll the outcome rows up into a summary that keeps the three token
+ * signals strictly separated and reports a measured first-pass rate. A
+ * `limit` bounds only the raw list; `maxSamples` bounds aggregation.
+ */
+export function summarizeContextPackOutcomes(
+ vault: string,
+ filter: ContextPackOutcomeFilter = {},
+): ContextPackOutcomeSummary {
+ const { limit: _limit, maxSamples, ...summaryFilter } = filter;
+ let rows = listContextPackOutcomes(vault, summaryFilter);
+ if (maxSamples !== undefined) rows = rows.slice(0, Math.max(0, Math.floor(maxSamples)));
+
+ let firstPass = 0;
+ let repair = 0;
+ let retries = 0;
+ const exact = { samples: 0, sum: 0 };
+ const modeled = { samples: 0, sum: 0 };
+ const observed = { samples: 0, sum: 0 };
+ const followUp = { samples: 0, sum: 0 };
+
+ for (const record of rows) {
+ const payload = record.payload;
+ if (payload["first_pass_success"] === true) firstPass += 1;
+ if (payload["repair_required"] === true) repair += 1;
+ const retry = numberOr(payload["retry_count"], null);
+ if (retry !== null) retries += retry;
+ accumulate(exact, payload["exact_prompt_token_savings"]);
+ accumulate(modeled, payload["modeled_inference_avoidance"]);
+ accumulate(observed, payload["observed_provider_tokens"]);
+ accumulate(followUp, payload["follow_up_tokens"]);
+ }
+
+ return Object.freeze({
+ total: rows.length,
+ first_pass_success: firstPass,
+ repair_required: repair,
+ retries,
+ first_pass_rate: rows.length > 0 ? round4(firstPass / rows.length) : null,
+ token_signals: Object.freeze({
+ exact: Object.freeze({ samples: exact.samples, prompt_token_savings: exact.sum }),
+ modeled: Object.freeze({ samples: modeled.samples, inference_avoidance: modeled.sum }),
+ observed: Object.freeze({ samples: observed.samples, provider_tokens: observed.sum }),
+ }),
+ follow_up: Object.freeze({ samples: followUp.samples, tokens: followUp.sum }),
+ });
+}
+
+/**
+ * Bounded local state that carries the latest recall/context-pack
+ * quality-sample ids through a session - a small most-recent ring, NOT a
+ * daemon. `remember` de-dupes an id to most-recent without growing; `latest`
+ * returns the head to post an outcome against on completion.
+ */
+export class SampleCarrier {
+ private readonly capacity: number;
+ private readonly ids: string[] = [];
+
+ constructor(capacity = 8) {
+ this.capacity = Math.max(1, Math.floor(capacity));
+ }
+
+ /** Record a sample id as the most-recent, evicting the oldest past capacity. */
+ remember(sampleId: string): void {
+ const trimmed = typeof sampleId === "string" ? sampleId.trim() : "";
+ if (trimmed === "") return;
+ const existing = this.ids.indexOf(trimmed);
+ if (existing !== -1) this.ids.splice(existing, 1);
+ this.ids.push(trimmed);
+ while (this.ids.length > this.capacity) this.ids.shift();
+ }
+
+ /** The most-recent carried sample id, or null when none has been seen. */
+ latest(): string | null {
+ return this.ids.length > 0 ? (this.ids[this.ids.length - 1] as string) : null;
+ }
+
+ has(sampleId: string): boolean {
+ return this.ids.includes(typeof sampleId === "string" ? sampleId.trim() : "");
+ }
+
+ /** All carried ids, oldest-first. */
+ all(): ReadonlyArray<string> {
+ return Object.freeze([...this.ids]);
+ }
+
+ get size(): number {
+ return this.ids.length;
+ }
+}
+
+/**
+ * Map a compact outcome row onto the token-impact ledger's single outcome
+ * enum. A retry dominates (it implies more than a repair); a repair dominates
+ * a clean first pass; only a flagged first-pass success with no repair/retry
+ * is `first_pass`. Anything else (not first-pass, no explicit repair/retry)
+ * is honestly recorded as a `repair`.
+ */
+function deriveOutcome(input: ContextPackOutcomeInput): TokenImpactOutcome {
+ if ((input.retryCount ?? 0) > 0) return "retry";
+ if (input.repairRequired === true) return "repair";
+ if (input.firstPassSuccess === true) return "first_pass";
+ return "repair";
+}
+
+function accumulate(acc: { samples: number; sum: number }, raw: unknown): void {
+ const value = numberOr(raw, null);
+ if (value !== null) {
+ acc.samples += 1;
+ acc.sum += value;
+ }
+}
+
+function requireSampleId(raw: unknown): string {
+ if (typeof raw !== "string" || raw.trim().length === 0) {
+ throw new TypeError("context pack outcome: sampleId must be a non-empty string");
+ }
+ return raw.trim();
+}
+
+function nonNegativeCount(field: string, value: number): number {
+ if (typeof value !== "number" || !Number.isFinite(value) || value < 0) {
+ throw new TypeError(`context pack outcome: ${field} must be a finite number >= 0`);
+ }
+ return value;
+}
+
+function numberOr(value: unknown, fallback: number | null): number | null {
+ return typeof value === "number" && Number.isFinite(value) ? value : fallback;
+}
+
+function matchesFilter(record: ContinuityRecord, filter: ContextPackOutcomeFilter): boolean {
+ const payload = record.payload;
+ if (filter.host !== undefined && payload["host"] !== filter.host) return false;
+ if (filter.sampleId !== undefined && payload["sample_id"] !== filter.sampleId) return false;
+ return true;
+}
+
+function round4(value: number): number {
+ return Math.round(value * 10000) / 10000;
+}
diff --git a/src/core/brain/context-pack.ts b/src/core/brain/context-pack.ts
index e1e03c88..1b5c5931 100644
--- a/src/core/brain/context-pack.ts
+++ b/src/core/brain/context-pack.ts
@@ -32,6 +32,7 @@ import {
type EpistemicStatus,
} from "./provenance/epistemic.ts";
import { estimateTokens } from "./text/tokenizer.ts";
+import { densityScore } from "./context-density.ts";
import { normalizeForDedup } from "./text/normalize.ts";
import { applyCharBudget, type CharBudgetDegradationMode } from "./recall-budget.ts";
import { emitContextReceipt, type ContextReceiptOptions } from "./context-receipts.ts";
@@ -88,6 +89,13 @@ export interface ContextPackItem extends ContextTransformAnnotations {
readonly epistemic: EpistemicStatus;
/** `evidenced_by` wikilinks grounding this item; empty when it cites none. */
readonly evidenceRefs: ReadonlyArray<string>;
+ /**
+ * Value-per-token density score (impact-per-token allocation,
+ * t_affa3bd9): structural signal per estimated token that broke this
+ * item's within-tier tie. Present only when `densityRanking` is on;
+ * absent otherwise so the default report stays byte-identical.
+ */
+ readonly density?: number;
/** Present when the surfaced body was filtered or explicitly trusted. */
readonly safety?: ContextSafetyReport;
}
@@ -163,6 +171,19 @@ export interface ContextPackOptions {
* on the `search_focus_context_pack` config key.
*/
readonly sessionFocus?: SearchSessionFocus | null;
+ /**
+ * Value-per-token density ranking (impact-per-token allocation,
+ * t_affa3bd9). When true, a deterministic density score (structural
+ * signal per estimated token) breaks ties WITHIN a tier - inserted
+ * into the sort AFTER `sessionFocus` and BEFORE recency, so the full
+ * chain is tier → focus → density → recency → id. Tier stays the
+ * coarse gate: a peripheral page can never outrank a core one, and an
+ * active session focus always dominates a static content heuristic.
+ * Omitted/false keeps the density map empty and the ordering
+ * byte-identical to the legacy tier → recency pack. Callers gate this
+ * on the `density_ranking_context_pack` config key.
+ */
+ readonly densityRanking?: boolean;
}
interface Candidate {
@@ -302,6 +323,24 @@ export function packContext(vault: string, opts: ContextPackOptions): ContextPac
}
}
+ // Value-per-token density (impact-per-token allocation, t_affa3bd9):
+ // computed once per candidate ONLY when opted in, so with the flag off
+ // the map is empty, the density comparator is a no-op, and the sort
+ // stays byte-identical to the legacy tier → recency ordering.
+ const densityRanking = opts.densityRanking === true;
+ const densityScoreById = new Map<string, number>();
+ if (densityRanking) {
+ for (const c of candidates) {
+ densityScoreById.set(
+ c.id,
+ densityScore(
+ { body: c.body, evidenceRefs: c.evidenceRefs, epistemic: c.epistemic },
+ c.tokens,
+ ),
+ );
+ }
+ }
+
candidates.sort((a, b) => {
const tierA = TIER_ORDER.indexOf(a.tier);
const tierB = TIER_ORDER.indexOf(b.tier);
@@ -309,6 +348,12 @@ export function packContext(vault: string, opts: ContextPackOptions): ContextPac
const focusA = focusScore.get(a.id) ?? 0;
const focusB = focusScore.get(b.id) ?? 0;
if (focusA !== focusB) return focusB - focusA;
+ // Density breaks within-tier ties after focus, before recency. The
+ // map is empty when the flag is off, so both sides read 0 and the
+ // comparator falls straight through to recency → id.
+ const densA = densityScoreById.get(a.id) ?? 0;
+ const densB = densityScoreById.get(b.id) ?? 0;
+ if (densA !== densB) return densB - densA;
if (a.createdAtMs !== b.createdAtMs) return b.createdAtMs - a.createdAtMs;
return a.id < b.id ? -1 : a.id > b.id ? 1 : 0;
});
@@ -352,6 +397,17 @@ export function packContext(vault: string, opts: ContextPackOptions): ContextPac
trimmed,
epistemic: c.epistemic,
evidenceRefs: c.evidenceRefs,
+ // When the per-memory char budget trimmed this item, recompute density
+ // from the emitted (post-trim) body/tokens so the surfaced value reflects
+ // the actual content/token-cost the agent receives, not the pre-budget
+ // candidate. Untrimmed items reuse the pre-computed score.
+ ...(densityRanking
+ ? {
+ density: trimmed
+ ? densityScore({ body, evidenceRefs: c.evidenceRefs, epistemic: c.epistemic }, tokens)
+ : (densityScoreById.get(c.id) ?? 0),
+ }
+ : {}),
...(c.safety ? { safety: c.safety } : {}),
});
used += tokens;
diff --git a/src/core/brain/continuity/types.ts b/src/core/brain/continuity/types.ts
index bb99c4ca..fc6aba13 100644
--- a/src/core/brain/continuity/types.ts
+++ b/src/core/brain/continuity/types.ts
@@ -19,6 +19,10 @@ export type ContinuityRecordKind =
| "session_summary_node"
| "session_summary_digest"
| "generation_report"
+ | "mcp_route_latency"
+ | "token_impact"
+ | "token_impact_outcome"
+ | "context_pack_outcome"
| "host_memory_write"
| "source_invalidation";
diff --git a/src/core/brain/doctor.ts b/src/core/brain/doctor.ts
index a47b7431..aa561dc0 100644
--- a/src/core/brain/doctor.ts
+++ b/src/core/brain/doctor.ts
@@ -41,6 +41,7 @@ import { join, relative } from "node:path";
import { REMOVED_TOOLS } from "../removed-surfaces.ts";
import { extractWikilinks, listVaultBasenames, parseFrontmatter } from "../vault.ts";
+import { computeActiveBudgetPressure } from "./active-budget-pressure.ts";
import { resolveVaultScope } from "../vault-scope/index.ts";
import { buildBacklinkIndex } from "./backlinks.ts";
import { buildEntityIndex } from "./entities/index-builder.ts";
@@ -64,6 +65,7 @@ import {
BRAIN_GUARDRAIL_DEFAULTS,
BRAIN_HEALTH_DEFAULTS,
BrainConfigError,
+ INJECT_BUDGET_CHARS_DEFAULT,
loadBrainConfigDetailed,
resolveHealth,
} from "./policy.ts";
@@ -73,7 +75,7 @@ import {
type VerificationDeltaSummaryCounts,
} from "./trust/compute-verification-delta.ts";
import { checkInstructionFileCeiling } from "./trust/instruction-file-ceiling.ts";
-import { brainConfigPath, brainDirs } from "./paths.ts";
+import { brainActivePath, brainConfigPath, brainDirs } from "./paths.ts";
import { BrainStatusFolderMismatchError, parsePreference, parseRetired } from "./preference.ts";
import {
reconcileSemanticHealth,
@@ -365,6 +367,16 @@ export function runDoctor(vault: string, opts: RunDoctorOptions = {}): RunDoctor
} catch {
/* doctor never throws */
}
+ // Proactive active-memory budget-pressure watermark (C4). When the
+ // rendered active.md is crossing its injection byte budget, warn
+ // BEFORE the reactive truncation silently drops content and list the
+ // sections an operator could archive to relieve pressure. Quiet on
+ // healthy vaults (empty output = healthy); suggestions only.
+ try {
+ checkActiveBudgetPressure(vault, issues, cfg?.active?.inject_budget_chars);
+ } catch {
+ /* doctor never throws */
+ }
try {
checkMalformedEvidenceRange(logRecords, issues);
} catch {
@@ -1171,6 +1183,58 @@ function checkDanglingWorkruns(vault: string, issues: DoctorIssue[]): void {
}
}
+/**
+ * `active-budget-pressure` (C4, context-pack-economics-observability):
+ * proactive watermark over `Brain/active.md`. Reads the rendered body,
+ * measures its fill-rate against the SessionStart injection byte budget
+ * (`active.inject_budget_chars`, else the default), and - only when
+ * pressure crosses the warn threshold - emits ONE warning naming the
+ * ranked eviction candidates an operator could archive to relieve it.
+ *
+ * "Empty output = healthy": a healthy or missing active.md produces no
+ * warning. The candidates are SUGGESTIONS surfaced for the operator /
+ * dream; nothing here mutates the vault - the reactive truncation in
+ * `active-budget.ts` is the only thing that ever drops content, and it
+ * does so at render time, not here.
+ */
+function checkActiveBudgetPressure(
+ vault: string,
+ issues: DoctorIssue[],
+ injectBudgetChars: number | undefined,
+): void {
+ const path = brainActivePath(vault);
+ if (!existsSync(path)) return;
+ let body: string;
+ try {
+ [, body] = parseFrontmatter(path);
+ } catch {
+ // A corrupted active.md is a derived-view problem the dream loop
+ // rewrites; not this probe's concern.
+ return;
+ }
+ const budget = injectBudgetChars ?? INJECT_BUDGET_CHARS_DEFAULT;
+ const pressure = computeActiveBudgetPressure(body.trim(), budget);
+ if (pressure.status === "healthy") return; // quiet on healthy vaults
+
+ const pct = Math.round(pressure.fillRate * 100);
+ const ranked = pressure.candidates
+ .map((c) => `${c.sectionKey.replace(/^## /, "")} (${c.bytes}B)`)
+ .join(", ");
+ const suggestion =
+ pressure.candidates.length > 0
+ ? ` Archive candidates, highest-priority-to-drop first: ${ranked}.`
+ : " No stale sections to archive - trim the confirmed rule set instead.";
+ issues.push({
+ severity: "warning",
+ code: "active-budget-pressure",
+ path,
+ message:
+ `active.md is at ${pct}% of the ${budget}-char injection budget (${pressure.status}).` +
+ " Content will be dropped at inject time once it overflows." +
+ suggestion,
+ });
+}
+
/**
* `malformed-evidence-range`: walks every `apply-evidence` event,
* runs the artifact wikilink through {@link parseArtifactRef}, and
diff --git a/src/core/brain/mcp-route-metrics.ts b/src/core/brain/mcp-route-metrics.ts
new file mode 100644
index 00000000..a1d231cf
--- /dev/null
+++ b/src/core/brain/mcp-route-metrics.ts
@@ -0,0 +1,221 @@
+/**
+ * Route-level latency metrics for MCP tools (context-pack-economics-
+ * observability suite).
+ *
+ * Open Second Brain already records recall latency (`recall_telemetry`)
+ * and inbound generation latency (`generation_report`), but neither
+ * captures the operational latency of an individual MCP tool as an
+ * operator experiences it - "which endpoint is blocking the agent
+ * turn?". This surface records one `mcp_route_latency` continuity record
+ * per `tools/call` (and per CLI bridge `callTool`) so slow surfaces can
+ * be identified by route rather than only by aggregate benchmark or
+ * generation-report numbers.
+ *
+ * Gated + fail-open by construction: the emit routes through
+ * `emitGatedTelemetry`, so with the gate off (config key
+ * `mcp_route_metrics_enabled` unset/false) no payload is built and no
+ * write happens, and a throwing write never fails the tool call it is
+ * measuring.
+ *
+ * Payload-safe by construction: only the tool name, MCP scope, status,
+ * duration, and the SORTED SET OF ARGUMENT KEY NAMES land on disk.
+ * Argument key names are the tool's own JSON-Schema property names
+ * (`query`, `max_tokens`, ...), never operator-supplied values - so no
+ * prompt, note body, or preference id is ever recorded. The whole
+ * payload still passes `safeContinuityPayload` redaction.
+ */
+
+import { emitGatedTelemetry } from "./continuity/emit.ts";
+import { appendContinuityRecord, listContinuityRecords } from "./continuity/store.ts";
+import type { ContinuityRecord } from "./continuity/types.ts";
+
+export type McpRouteStatus = "ok" | "error";
+
+export interface McpRouteLatencyInput {
+ readonly createdAt?: string;
+ /** MCP tool name, e.g. `brain_search`. */
+ readonly tool: string;
+ /** Advertised tool scope of the process that served the call (`full`/`writer`/`catalog`). */
+ readonly scope?: string;
+ readonly status: McpRouteStatus;
+ readonly durationMs: number;
+ /**
+ * Argument KEY NAMES supplied on the call (schema property names only).
+ * Recorded as a sorted, de-duplicated set to identify call variants
+ * without ever persisting argument values.
+ */
+ readonly argKeys?: ReadonlyArray<string>;
+}
+
+export interface McpRouteLatencyFilter {
+ readonly tool?: string;
+ readonly status?: McpRouteStatus;
+ readonly since?: string;
+ readonly until?: string;
+ readonly limit?: number;
+}
+
+/** Per-route latency roll-up (nearest-rank percentiles over the route's durations). */
+export interface McpRouteStats {
+ readonly tool: string;
+ readonly count: number;
+ readonly error_count: number;
+ readonly min_ms: number;
+ readonly max_ms: number;
+ readonly avg_ms: number;
+ readonly p50_ms: number;
+ readonly p95_ms: number;
+ readonly p99_ms: number;
+}
+
+export interface McpRouteLatencySummary {
+ readonly total: number;
+ readonly error_count: number;
+ readonly by_status: Partial<Record<McpRouteStatus, number>>;
+ /** One entry per tool, slowest-first by p95 latency. */
+ readonly routes: ReadonlyArray<McpRouteStats>;
+}
+
+export function isMcpRouteStatus(value: unknown): value is McpRouteStatus {
+ return value === "ok" || value === "error";
+}
+
+/**
+ * Emit one `mcp_route_latency` continuity record, gated and fail-open.
+ *
+ * `gate` doubles as the opt-in switch: with `false | null | undefined`
+ * the build thunk never runs (no payload, no write) and the function
+ * returns `null`. A throwing build is swallowed and reported as `null`
+ * so route metrics can never fail the tool call being measured.
+ */
+export function emitMcpRouteLatency<G>(
+ vault: string,
+ input: McpRouteLatencyInput,
+ gate: G | false | null | undefined,
+): ContinuityRecord | null {
+ return emitGatedTelemetry(gate, () => {
+ const tool = input.tool;
+ if (typeof tool !== "string" || tool.length === 0) {
+ throw new TypeError("mcp route latency: tool must be a non-empty string");
+ }
+ const createdAt = input.createdAt ?? new Date().toISOString();
+ const argKeys = normalizeArgKeys(input.argKeys);
+ // Guard against non-finite durations: Math.round/Math.max pass NaN/Infinity
+ // through, and JSON.stringify silently turns them into null, corrupting the
+ // persisted record. Not reachable from the server seam today (always a
+ // performance.now() diff) but hardened for future misuse.
+ const safeDurationMs = Number.isFinite(input.durationMs) ? input.durationMs : 0;
+ const payload: Record<string, unknown> = {
+ tool,
+ ...(input.scope !== undefined ? { scope: input.scope } : {}),
+ status: input.status,
+ duration_ms: Math.max(0, Math.round(safeDurationMs)),
+ ...(argKeys.length > 0 ? { arg_keys: argKeys } : {}),
+ };
+ return appendContinuityRecord(vault, {
+ kind: "mcp_route_latency",
+ createdAt,
+ sourceRefs: [],
+ payload,
+ });
+ });
+}
+
+function normalizeArgKeys(raw: ReadonlyArray<string> | undefined): string[] {
+ if (!Array.isArray(raw)) return [];
+ const seen = new Set<string>();
+ for (const key of raw) {
+ if (typeof key === "string" && key.length > 0) seen.add(key);
+ }
+ return [...seen].toSorted();
+}
+
+/** List `mcp_route_latency` records newest-first, after applying filters. */
+export function listMcpRouteLatency(
+ vault: string,
+ filter: McpRouteLatencyFilter = {},
+): ReadonlyArray<ContinuityRecord> {
+ let records = listContinuityRecords(vault, {
+ kind: "mcp_route_latency",
+ ...(filter.since !== undefined ? { since: filter.since } : {}),
+ ...(filter.until !== undefined ? { until: filter.until } : {}),
+ }).filter((record) => matchesFilter(record, filter));
+ records = records.toReversed();
+ if (filter.limit !== undefined) records = records.slice(0, Math.max(0, Math.floor(filter.limit)));
+ return Object.freeze(records);
+}
+
+/** Aggregate route latency into per-tool percentile stats, slowest-first. */
+export function summarizeMcpRouteLatency(
+ vault: string,
+ filter: McpRouteLatencyFilter = {},
+): McpRouteLatencySummary {
+ // Summary always spans the full filtered window - `limit` bounds the
+ // list operation only, never the roll-up.
+ const { limit: _limit, ...summaryFilter } = filter;
+ const records = listMcpRouteLatency(vault, summaryFilter);
+ const byStatus: Partial<Record<McpRouteStatus, number>> = {};
+ const durationsByTool = new Map<string, number[]>();
+ const errorsByTool = new Map<string, number>();
+ let errorCount = 0;
+
+ for (const record of records) {
+ const payload = record.payload;
+ const tool = typeof payload["tool"] === "string" ? payload["tool"] : "unknown";
+ const status = payload["status"];
+ if (isMcpRouteStatus(status)) {
+ byStatus[status] = (byStatus[status] ?? 0) + 1;
+ if (status === "error") {
+ errorCount += 1;
+ errorsByTool.set(tool, (errorsByTool.get(tool) ?? 0) + 1);
+ }
+ }
+ const duration = payload["duration_ms"];
+ if (typeof duration === "number" && Number.isFinite(duration)) {
+ const bucket = durationsByTool.get(tool);
+ if (bucket) bucket.push(duration);
+ else durationsByTool.set(tool, [duration]);
+ }
+ }
+
+ const routes: McpRouteStats[] = [];
+ for (const [tool, durations] of durationsByTool) {
+ const sorted = durations.toSorted((a, b) => a - b);
+ const sum = sorted.reduce((acc, value) => acc + value, 0);
+ routes.push({
+ tool,
+ count: sorted.length,
+ error_count: errorsByTool.get(tool) ?? 0,
+ min_ms: sorted[0] ?? 0,
+ max_ms: sorted[sorted.length - 1] ?? 0,
+ avg_ms: sorted.length > 0 ? Math.round((sum / sorted.length) * 10) / 10 : 0,
+ p50_ms: percentile(sorted, 50),
+ p95_ms: percentile(sorted, 95),
+ p99_ms: percentile(sorted, 99),
+ });
+ }
+ // Slowest surface first, tie-broken by name for a stable order.
+ routes.sort((a, b) => b.p95_ms - a.p95_ms || a.tool.localeCompare(b.tool));
+
+ return Object.freeze({
+ total: records.length,
+ error_count: errorCount,
+ by_status: Object.freeze(byStatus),
+ routes: Object.freeze(routes),
+ });
+}
+
+/** Nearest-rank percentile over an ascending-sorted array; 0 for empty input. */
+function percentile(sortedAsc: ReadonlyArray<number>, p: number): number {
+ if (sortedAsc.length === 0) return 0;
+ const rank = Math.ceil((p / 100) * sortedAsc.length);
+ const idx = Math.min(sortedAsc.length - 1, Math.max(0, rank - 1));
+ return sortedAsc[idx] ?? 0;
+}
+
+function matchesFilter(record: ContinuityRecord, filter: McpRouteLatencyFilter): boolean {
+ const payload = record.payload;
+ if (filter.tool !== undefined && payload["tool"] !== filter.tool) return false;
+ if (filter.status !== undefined && payload["status"] !== filter.status) return false;
+ return true;
+}
diff --git a/src/core/brain/token-impact.ts b/src/core/brain/token-impact.ts
new file mode 100644
index 00000000..d74f108b
--- /dev/null
+++ b/src/core/brain/token-impact.ts
@@ -0,0 +1,450 @@
+/**
+ * Token-impact + context-pack-quality telemetry ledger
+ * (context-pack-economics-observability suite).
+ *
+ * Open Second Brain enforces token/char budgets (`recall-budget.ts`,
+ * `text-budget.ts`, `active-budget.ts`) and records recall/gate decision
+ * telemetry (`recall-telemetry.ts`, `gate-telemetry.ts`), but it could not
+ * answer the core value-of-memory question: "how many prompt tokens did the
+ * memory layer actually keep out of (or add to) the agent call?". This
+ * surface is the durable ledger that measures exactly that.
+ *
+ * TWO STRICTLY SEPARATED LEDGERS, never conflated into one headline number:
+ *
+ * 1. EXACT prompt-token delta - the real, measured token cost the memory
+ * layer contributed. `delta_tokens = baseline_tokens - packed_tokens`
+ * (positive = tokens KEPT OUT of the prompt, negative = tokens ADDED).
+ * Each sample is labelled `method: "exact" | "fallback"` so a
+ * tokenizer-exact count (posted by a host that ran a real BPE
+ * tokenizer) is never silently averaged in with a heuristic
+ * `estimateTokens` fallback. The summary keeps a per-method split so
+ * the honesty of the number is always inspectable.
+ *
+ * 2. MODELED inference-avoidance - a counterfactual estimate of the
+ * inferences (repairs/retries) the memory layer avoided, valued at
+ * `avoided_inferences * tokens_per_inference`. This is a model, not a
+ * measurement, so it lives in its own block and is CALIBRATED (never
+ * replaced) by real first-pass/repair/retry outcomes posted through
+ * {@link recordTokenImpactOutcome}: `calibrated = raw * first_pass_rate`
+ * (null until at least one outcome is posted).
+ *
+ * Durable + restart-surviving: samples are `token_impact` continuity
+ * records and outcomes are `token_impact_outcome` records, so aggregates are
+ * recomputed from disk on every read and survive a restart for free (the
+ * continuity store is the byte-durable, month-sharded sink). The summary
+ * accepts a `maxSamples` cap so a long-lived ledger stays bounded at
+ * aggregation time.
+ *
+ * Privacy-preserving by construction: only COUNTS and an opaque `pack_id`
+ * (a receipt id or request hash the caller chooses) ever land on disk - no
+ * raw prompt, no recalled text. The whole payload still passes
+ * `safeContinuityPayload` redaction.
+ *
+ * Gated + fail-open: emits route through `emitGatedTelemetry`, so with the
+ * gate off no payload is built and no write happens, and a throwing write
+ * never fails the operation being measured.
+ */
+
+import { emitGatedTelemetry } from "./continuity/emit.ts";
+import { appendContinuityRecord, listContinuityRecords } from "./continuity/store.ts";
+import type { ContinuityRecord } from "./continuity/types.ts";
+
+/** How the prompt-token counts on a sample were obtained. */
+export type TokenCountMethod = "exact" | "fallback";
+
+/** First-pass/repair/retry outcome posted to calibrate the modeled ledger. */
+export type TokenImpactOutcome = "first_pass" | "repair" | "retry";
+
+export interface TokenImpactInput {
+ readonly createdAt?: string;
+ readonly host?: string;
+ readonly sessionId?: string;
+ readonly turnId?: string;
+ /**
+ * Opaque correlation id for the context pack this sample measures - a
+ * context-receipt id or a request hash the caller chooses. Never a raw
+ * prompt or recalled text.
+ */
+ readonly packId?: string;
+ /** Prompt-token cost WITHOUT the memory layer's compaction/selection. */
+ readonly baselineTokens: number;
+ /** Prompt-token cost the memory layer actually shipped. */
+ readonly packedTokens: number;
+ /** Whether the counts are tokenizer-exact or a heuristic fallback estimate. */
+ readonly method: TokenCountMethod;
+ /** Modeled count of inferences (repairs/retries) the layer is estimated to have avoided. */
+ readonly modeledAvoidedInferences?: number;
+ /** Modeled average prompt tokens per avoided inference. */
+ readonly modeledTokensPerInference?: number;
+}
+
+export interface TokenImpactOutcomeInput {
+ readonly createdAt?: string;
+ readonly host?: string;
+ readonly sessionId?: string;
+ readonly packId?: string;
+ readonly outcome: TokenImpactOutcome;
+ /** Observed prompt tokens for the inference this outcome describes. */
+ readonly tokensPerInference?: number;
+}
+
+export interface TokenImpactFilter {
+ readonly host?: string;
+ readonly packId?: string;
+ readonly method?: TokenCountMethod;
+ readonly since?: string;
+ readonly until?: string;
+ readonly limit?: number;
+ /**
+ * Cap the number of most-recent samples aggregated by
+ * {@link summarizeTokenImpact}. Keeps a long-lived ledger bounded at
+ * aggregation time without truncating the durable log.
+ */
+ readonly maxSamples?: number;
+}
+
+export interface TokenImpactMethodStats {
+ readonly samples: number;
+ readonly net_savings_tokens: number;
+}
+
+/** EXACT-type prompt-token delta ledger (real measurement). */
+export interface PromptTokenDeltaSummary {
+ readonly total_samples: number;
+ /** Sum of `delta_tokens` over all samples (signed: + kept out, − added). */
+ readonly net_savings_tokens: number;
+ /** Sum of positive deltas (tokens the layer kept out of the prompt). */
+ readonly saved_tokens: number;
+ /** Sum of |negative deltas| (tokens the layer added to the prompt). */
+ readonly added_tokens: number;
+ /** `net_savings_tokens / total_samples`, rounded to 1 dp; 0 for no samples. */
+ readonly mean_savings_tokens: number;
+ readonly by_method: {
+ readonly exact: TokenImpactMethodStats;
+ readonly fallback: TokenImpactMethodStats;
+ };
+}
+
+export interface TokenImpactCalibration {
+ readonly total_outcomes: number;
+ readonly first_pass: number;
+ readonly repair: number;
+ readonly retry: number;
+ /** `first_pass / total_outcomes`, rounded to 4 dp; null when no outcomes. */
+ readonly first_pass_rate: number | null;
+ /** Mean of posted `tokens_per_inference`, rounded to 1 dp; null when none. */
+ readonly mean_tokens_per_inference: number | null;
+}
+
+/** MODELED counterfactual inference-avoidance ledger (strictly separate). */
+export interface ModeledInferenceAvoidanceSummary {
+ readonly samples: number;
+ /** Sum of `modeled_savings_tokens` over samples that carry a modeled estimate. */
+ readonly raw_savings_tokens: number;
+ readonly calibration: TokenImpactCalibration;
+ /**
+ * `raw_savings_tokens * first_pass_rate`, rounded to 1 dp. Null until at
+ * least one outcome has been posted - the modeled figure is uncalibrated,
+ * not zero, so we refuse to imply precision we do not have.
+ */
+ readonly calibrated_savings_tokens: number | null;
+}
+
+export interface TokenImpactSummary {
+ readonly total_samples: number;
+ readonly prompt_token_delta: PromptTokenDeltaSummary;
+ readonly modeled_inference_avoidance: ModeledInferenceAvoidanceSummary;
+}
+
+export function isTokenCountMethod(value: unknown): value is TokenCountMethod {
+ return value === "exact" || value === "fallback";
+}
+
+export function isTokenImpactOutcome(value: unknown): value is TokenImpactOutcome {
+ return value === "first_pass" || value === "repair" || value === "retry";
+}
+
+/**
+ * Emit one `token_impact` sample, gated and fail-open. `gate` doubles as the
+ * opt-in switch: with `false | null | undefined` no payload is built and no
+ * write happens (returns `null`). A throwing build - including invalid
+ * counts - is swallowed and reported as `null` so the ledger can never fail
+ * the operation it measures.
+ */
+export function emitTokenImpact<G>(
+ vault: string,
+ input: TokenImpactInput,
+ gate: G | false | null | undefined,
+): ContinuityRecord | null {
+ return emitGatedTelemetry(gate, () => {
+ if (!isTokenCountMethod(input.method)) {
+ throw new TypeError("token impact: method must be 'exact' or 'fallback'");
+ }
+ const baseline = nonNegativeCount("baseline_tokens", input.baselineTokens);
+ const packed = nonNegativeCount("packed_tokens", input.packedTokens);
+ const delta = baseline - packed;
+ const modeled = resolveModeled(input);
+ const payload: Record<string, unknown> = {
+ ...(input.host !== undefined ? { host: input.host } : {}),
+ ...(input.sessionId !== undefined ? { session_id: input.sessionId } : {}),
+ ...(input.turnId !== undefined ? { turn_id: input.turnId } : {}),
+ ...(input.packId !== undefined ? { pack_id: input.packId } : {}),
+ method: input.method,
+ baseline_tokens: baseline,
+ packed_tokens: packed,
+ delta_tokens: delta,
+ ...(modeled !== null
+ ? {
+ modeled_avoided_inferences: modeled.avoided,
+ modeled_tokens_per_inference: modeled.perInference,
+ modeled_savings_tokens: modeled.savings,
+ }
+ : {}),
+ };
+ return appendContinuityRecord(vault, {
+ kind: "token_impact",
+ createdAt: input.createdAt ?? new Date().toISOString(),
+ sourceRefs: [],
+ payload,
+ });
+ });
+}
+
+/**
+ * Record one first-pass/repair/retry outcome (the `/outcome` calibration
+ * hook), gated and fail-open. Used only to calibrate the modeled ledger -
+ * it never touches the exact prompt-token delta figures.
+ */
+export function recordTokenImpactOutcome<G>(
+ vault: string,
+ input: TokenImpactOutcomeInput,
+ gate: G | false | null | undefined,
+): ContinuityRecord | null {
+ return emitGatedTelemetry(gate, () => {
+ if (!isTokenImpactOutcome(input.outcome)) {
+ throw new TypeError("token impact outcome: outcome must be first_pass | repair | retry");
+ }
+ const payload: Record<string, unknown> = {
+ ...(input.host !== undefined ? { host: input.host } : {}),
+ ...(input.sessionId !== undefined ? { session_id: input.sessionId } : {}),
+ ...(input.packId !== undefined ? { pack_id: input.packId } : {}),
+ outcome: input.outcome,
+ ...(input.tokensPerInference !== undefined
+ ? {
+ tokens_per_inference: nonNegativeCount(
+ "tokens_per_inference",
+ input.tokensPerInference,
+ ),
+ }
+ : {}),
+ };
+ return appendContinuityRecord(vault, {
+ kind: "token_impact_outcome",
+ createdAt: input.createdAt ?? new Date().toISOString(),
+ sourceRefs: [],
+ payload,
+ });
+ });
+}
+
+/** List `token_impact` samples newest-first, after applying filters. */
+export function listTokenImpact(
+ vault: string,
+ filter: TokenImpactFilter = {},
+): ReadonlyArray<ContinuityRecord> {
+ let records = listContinuityRecords(vault, {
+ kind: "token_impact",
+ ...(filter.since !== undefined ? { since: filter.since } : {}),
+ ...(filter.until !== undefined ? { until: filter.until } : {}),
+ }).filter((record) => matchesFilter(record, filter));
+ records = records.toReversed();
+ if (filter.limit !== undefined) records = records.slice(0, Math.max(0, Math.floor(filter.limit)));
+ return Object.freeze(records);
+}
+
+/** List `token_impact_outcome` calibration posts newest-first. */
+export function listTokenImpactOutcomes(
+ vault: string,
+ filter: TokenImpactFilter = {},
+): ReadonlyArray<ContinuityRecord> {
+ let records = listContinuityRecords(vault, {
+ kind: "token_impact_outcome",
+ ...(filter.since !== undefined ? { since: filter.since } : {}),
+ ...(filter.until !== undefined ? { until: filter.until } : {}),
+ }).filter((record) => matchesOutcomeFilter(record, filter));
+ records = records.toReversed();
+ if (filter.limit !== undefined) records = records.slice(0, Math.max(0, Math.floor(filter.limit)));
+ return Object.freeze(records);
+}
+
+/**
+ * Roll the two ledgers up into a single summary that keeps them strictly
+ * separated: the EXACT prompt-token delta (with a per-method split) and the
+ * MODELED inference-avoidance figure (calibrated by posted outcomes). A
+ * `limit` bounds only the raw list; `maxSamples` bounds aggregation.
+ */
+export function summarizeTokenImpact(
+ vault: string,
+ filter: TokenImpactFilter = {},
+): TokenImpactSummary {
+ // The roll-up spans the full filtered window - `limit` never bounds it.
+ const { limit: _limit, maxSamples, ...summaryFilter } = filter;
+ let samples = listTokenImpact(vault, summaryFilter);
+ if (maxSamples !== undefined) samples = samples.slice(0, Math.max(0, Math.floor(maxSamples)));
+
+ let net = 0;
+ let saved = 0;
+ let added = 0;
+ const byMethod = {
+ exact: { samples: 0, net: 0 },
+ fallback: { samples: 0, net: 0 },
+ };
+ let modeledSamples = 0;
+ let rawModeled = 0;
+
+ for (const record of samples) {
+ const payload = record.payload;
+ const delta = numberOr(payload["delta_tokens"], null);
+ if (delta !== null) {
+ net += delta;
+ if (delta > 0) saved += delta;
+ else if (delta < 0) added += -delta;
+ }
+ const method = payload["method"];
+ if (isTokenCountMethod(method) && delta !== null) {
+ byMethod[method].samples += 1;
+ byMethod[method].net += delta;
+ }
+ const modeled = numberOr(payload["modeled_savings_tokens"], null);
+ if (modeled !== null) {
+ modeledSamples += 1;
+ rawModeled += modeled;
+ }
+ }
+
+ const calibration = summarizeCalibration(vault, summaryFilter);
+ const calibrated =
+ calibration.first_pass_rate === null ? null : round1(rawModeled * calibration.first_pass_rate);
+
+ return Object.freeze({
+ total_samples: samples.length,
+ prompt_token_delta: Object.freeze({
+ total_samples: samples.length,
+ net_savings_tokens: net,
+ saved_tokens: saved,
+ added_tokens: added,
+ mean_savings_tokens: samples.length > 0 ? round1(net / samples.length) : 0,
+ by_method: Object.freeze({
+ exact: Object.freeze({
+ samples: byMethod.exact.samples,
+ net_savings_tokens: byMethod.exact.net,
+ }),
+ fallback: Object.freeze({
+ samples: byMethod.fallback.samples,
+ net_savings_tokens: byMethod.fallback.net,
+ }),
+ }),
+ }),
+ modeled_inference_avoidance: Object.freeze({
+ samples: modeledSamples,
+ raw_savings_tokens: round1(rawModeled),
+ calibration,
+ calibrated_savings_tokens: calibrated,
+ }),
+ });
+}
+
+function summarizeCalibration(
+ vault: string,
+ filter: Omit<TokenImpactFilter, "limit" | "maxSamples">,
+): TokenImpactCalibration {
+ const outcomes = listTokenImpactOutcomes(vault, filter);
+ let firstPass = 0;
+ let repair = 0;
+ let retry = 0;
+ let tpiSum = 0;
+ let tpiCount = 0;
+ for (const record of outcomes) {
+ const outcome = record.payload["outcome"];
+ if (outcome === "first_pass") firstPass += 1;
+ else if (outcome === "repair") repair += 1;
+ else if (outcome === "retry") retry += 1;
+ const tpi = numberOr(record.payload["tokens_per_inference"], null);
+ if (tpi !== null) {
+ tpiSum += tpi;
+ tpiCount += 1;
+ }
+ }
+ const total = firstPass + repair + retry;
+ return Object.freeze({
+ total_outcomes: total,
+ first_pass: firstPass,
+ repair,
+ retry,
+ first_pass_rate: total > 0 ? round4(firstPass / total) : null,
+ mean_tokens_per_inference: tpiCount > 0 ? round1(tpiSum / tpiCount) : null,
+ });
+}
+
+function resolveModeled(
+ input: TokenImpactInput,
+): { avoided: number; perInference: number; savings: number } | null {
+ if (
+ input.modeledAvoidedInferences === undefined &&
+ input.modeledTokensPerInference === undefined
+ ) {
+ return null;
+ }
+ // Partial modeled input would otherwise default the missing field to 0 and
+ // look like an exact measurement. Require both together; the throw fail-opens
+ // to null (emitGatedTelemetry swallows it), matching the "omit, don't invent"
+ // honesty goal stated in this module's header.
+ if (
+ input.modeledAvoidedInferences === undefined ||
+ input.modeledTokensPerInference === undefined
+ ) {
+ throw new TypeError(
+ "token impact: modeledAvoidedInferences and modeledTokensPerInference must both be supplied together",
+ );
+ }
+ const avoided = nonNegativeCount("modeled_avoided_inferences", input.modeledAvoidedInferences);
+ const perInference = nonNegativeCount(
+ "modeled_tokens_per_inference",
+ input.modeledTokensPerInference,
+ );
+ return { avoided, perInference, savings: round1(avoided * perInference) };
+}
+
+function nonNegativeCount(field: string, value: number): number {
+ if (typeof value !== "number" || !Number.isFinite(value) || value < 0) {
+ throw new TypeError(`token impact: ${field} must be a finite number >= 0`);
+ }
+ return value;
+}
+
+function numberOr(value: unknown, fallback: number | null): number | null {
+ return typeof value === "number" && Number.isFinite(value) ? value : fallback;
+}
+
+function matchesFilter(record: ContinuityRecord, filter: TokenImpactFilter): boolean {
+ const payload = record.payload;
+ if (filter.host !== undefined && payload["host"] !== filter.host) return false;
+ if (filter.packId !== undefined && payload["pack_id"] !== filter.packId) return false;
+ if (filter.method !== undefined && payload["method"] !== filter.method) return false;
+ return true;
+}
+
+function matchesOutcomeFilter(record: ContinuityRecord, filter: TokenImpactFilter): boolean {
+ const payload = record.payload;
+ if (filter.host !== undefined && payload["host"] !== filter.host) return false;
+ if (filter.packId !== undefined && payload["pack_id"] !== filter.packId) return false;
+ return true;
+}
+
+function round1(value: number): number {
+ return Math.round(value * 10) / 10;
+}
+
+function round4(value: number): number {
+ return Math.round(value * 10000) / 10000;
+}
diff --git a/src/core/config.ts b/src/core/config.ts
index 996a4a9d..1b241db8 100644
--- a/src/core/config.ts
+++ b/src/core/config.ts
@@ -352,6 +352,22 @@ export function resolveSearchFocusContextPack(configPath?: string): boolean {
);
}
+/**
+ * Context-pack density-ranking gate (impact-per-token allocation,
+ * t_affa3bd9). Default OFF: brain_context_pack orders purely by tier →
+ * recency unless `density_ranking_context_pack: "true"` (or the env
+ * override), keeping the default pack byte-identical. When on, a
+ * deterministic value-per-token density score breaks within-tier ties
+ * (after session focus, before recency).
+ */
+export function resolveDensityRankingContextPack(configPath?: string): boolean {
+ return resolveConfigFlag(
+ "OPEN_SECOND_BRAIN_DENSITY_RANKING_CONTEXT_PACK",
+ "density_ranking_context_pack",
+ configPath,
+ );
+}
+
/**
* Post-compaction pinned-anchor survival audit gate
* (session-lifecycle-capture-durability, t_12c8b256). Default OFF: the
@@ -506,6 +522,62 @@ export function resolveGenerationTraceEnabled(configPath?: string): boolean {
);
}
+/**
+ * Route-level MCP latency metrics gate (context-pack-economics-
+ * observability suite). Default OFF: the `mcp_route_latency` continuity
+ * path stays dormant unless `mcp_route_metrics_enabled: "true"`, when the
+ * MCP server records one payload-safe latency record per tool call (tool
+ * name, scope, status, duration, and argument key names only - never
+ * argument values). Fail-open: a failed record never fails the call.
+ */
+export function resolveMcpRouteMetricsEnabled(configPath?: string): boolean {
+ return resolveConfigFlag(
+ "OPEN_SECOND_BRAIN_MCP_ROUTE_METRICS_ENABLED",
+ "mcp_route_metrics_enabled",
+ configPath,
+ );
+}
+
+/**
+ * Token-impact + context-pack-quality ledger gate (context-pack-economics-
+ * observability suite). Default OFF: the `token_impact` / `token_impact_outcome`
+ * continuity paths stay dormant unless `token_impact_ledger_enabled: "true"`,
+ * when opt-in `record`/`outcome` posts to `brain_token_impact` persist the
+ * tokenizer-exact prompt-token delta (baseline vs packed, method-labelled)
+ * and modeled inference-avoidance calibration. Payload-safe: counts and an
+ * opaque pack id only, never raw prompts or recalled text. Fail-open: a
+ * failed write never fails the caller. Read paths (list/summary) ignore the
+ * gate so historical aggregates stay inspectable after it is turned off.
+ */
+export function resolveTokenImpactLedgerEnabled(configPath?: string): boolean {
+ return resolveConfigFlag(
+ "OPEN_SECOND_BRAIN_TOKEN_IMPACT_LEDGER_ENABLED",
+ "token_impact_ledger_enabled",
+ configPath,
+ );
+}
+
+/**
+ * Agent-operable context-pack outcome-loop gate (context-pack-economics-
+ * observability suite, C5). Default OFF: the `context_pack_outcome`
+ * continuity path (and its composed `token_impact_outcome` calibration
+ * write) stays dormant unless `context_pack_outcome_enabled: "true"`, when
+ * an opt-in `post` to `brain_context_pack_outcome` records one compact
+ * outcome row - first-pass/repair/retry counters plus the three strictly
+ * separate token signals (exact / modeled / observed) - correlated to a
+ * carried context-pack quality-sample id. Payload-safe: counts and an
+ * opaque sample id only, never raw prompts, completions, or recalled text.
+ * Fail-open: a failed write never fails the caller. Read paths (list/
+ * summary) ignore the gate so historical aggregates stay inspectable.
+ */
+export function resolveContextPackOutcomeEnabled(configPath?: string): boolean {
+ return resolveConfigFlag(
+ "OPEN_SECOND_BRAIN_CONTEXT_PACK_OUTCOME_ENABLED",
+ "context_pack_outcome_enabled",
+ configPath,
+ );
+}
+
/**
* Optional external judge command for the memory benchmark (Memory
* Observability Suite, t_882c396a). Unset (the default) means the
diff --git a/src/mcp/brain/pack-tools.ts b/src/mcp/brain/pack-tools.ts
index f4106214..3b73e64c 100644
--- a/src/mcp/brain/pack-tools.ts
+++ b/src/mcp/brain/pack-tools.ts
@@ -9,6 +9,7 @@
*/
import {
+ resolveDensityRankingContextPack,
resolveRecallAdequacyThresholds,
resolveSearchFocusContextPack,
} from "../../core/config.ts";
@@ -110,8 +111,13 @@ async function toolBrainContextPack(
sessionFocus = null;
}
}
+ // Density-ranking wiring (impact-per-token allocation, t_affa3bd9):
+ // gated on the density_ranking_context_pack config key (default off)
+ // so the default pack stays byte-identical to the tier → recency order.
+ const densityRanking = resolveDensityRankingContextPack(ctx.configPath ?? undefined);
const report = packContext(ctx.vault, {
maxTokens,
+ ...(densityRanking ? { densityRanking: true } : {}),
...(sessionFocus !== null ? { sessionFocus } : {}),
...(query ? { query } : {}),
...(includeLanes ? { includeLanes: true } : {}),
@@ -146,6 +152,7 @@ async function toolBrainContextPack(
trimmed: i.trimmed,
epistemic: i.epistemic,
...(i.evidenceRefs.length > 0 ? { evidence_refs: i.evidenceRefs } : {}),
+ ...(i.density !== undefined ? { density: i.density } : {}),
...(i.originalRank !== undefined ? { original_rank: i.originalRank } : {}),
...(i.stableRank !== undefined ? { stable_rank: i.stableRank } : {}),
...(i.dedupedFrom !== undefined ? { deduped_from: i.dedupedFrom } : {}),
diff --git a/src/mcp/brain/recall-tools.ts b/src/mcp/brain/recall-tools.ts
index 6808ff1b..8d3d939f 100644
--- a/src/mcp/brain/recall-tools.ts
+++ b/src/mcp/brain/recall-tools.ts
@@ -21,6 +21,34 @@ import {
type RecallTelemetryMode,
type RecallTelemetryStatus,
} from "../../core/brain/recall-telemetry.ts";
+import {
+ isMcpRouteStatus,
+ listMcpRouteLatency,
+ summarizeMcpRouteLatency,
+ type McpRouteLatencyFilter,
+ type McpRouteStatus,
+} from "../../core/brain/mcp-route-metrics.ts";
+import {
+ emitTokenImpact,
+ isTokenCountMethod,
+ isTokenImpactOutcome,
+ listTokenImpact,
+ recordTokenImpactOutcome,
+ summarizeTokenImpact,
+ type TokenCountMethod,
+ type TokenImpactFilter,
+ type TokenImpactOutcome,
+} from "../../core/brain/token-impact.ts";
+import {
+ emitContextPackOutcome,
+ listContextPackOutcomes,
+ summarizeContextPackOutcomes,
+ type ContextPackOutcomeFilter,
+} from "../../core/brain/context-pack-outcome.ts";
+import {
+ resolveContextPackOutcomeEnabled,
+ resolveTokenImpactLedgerEnabled,
+} from "../../core/config.ts";
import {
describeSessionRecall,
expandSessionRecall,
@@ -273,6 +301,407 @@ function coerceRecallTelemetryStatus(raw: unknown): RecallTelemetryStatus | unde
return trimmed;
}
+// ----- brain_route_metrics (context-pack-economics-observability) -----------
+
+async function toolBrainRouteMetrics(
+ ctx: ServerContext,
+ args: Record<string, unknown>,
+): Promise<Record<string, unknown>> {
+ const operation = optionalStringArg("brain_route_metrics", args, "operation");
+ const filter = routeMetricsFilter(args);
+
+ if (operation === "list") {
+ const records = listMcpRouteLatency(ctx.vault, filter);
+ return { vault_path: ctx.vault, total: records.length, records };
+ }
+ if (operation === "summary") {
+ const summary = summarizeMcpRouteLatency(ctx.vault, filter);
+ return { vault_path: ctx.vault, ...summary };
+ }
+ throw new MCPError(INVALID_PARAMS, "brain_route_metrics: operation must be list or summary");
+}
+
+function routeMetricsFilter(args: Record<string, unknown>): McpRouteLatencyFilter {
+ const tool = optionalStringArg("brain_route_metrics", args, "tool");
+ const status = coerceRouteMetricsStatus(args["status"]);
+ const since = optionalStringArg("brain_route_metrics", args, "since");
+ const until = optionalStringArg("brain_route_metrics", args, "until");
+ const limit = coercePositiveInteger("brain_route_metrics", "limit", args["limit"]);
+ return {
+ ...(tool !== undefined ? { tool } : {}),
+ ...(status !== undefined ? { status } : {}),
+ ...(since !== undefined ? { since } : {}),
+ ...(until !== undefined ? { until } : {}),
+ ...(limit !== undefined ? { limit } : {}),
+ };
+}
+
+function coerceRouteMetricsStatus(raw: unknown): McpRouteStatus | undefined {
+ if (raw === undefined || raw === null) return undefined;
+ const trimmed = typeof raw === "string" ? raw.trim() : raw;
+ if (!isMcpRouteStatus(trimmed)) {
+ throw new MCPError(INVALID_PARAMS, "brain_route_metrics: status must be ok or error");
+ }
+ return trimmed;
+}
+
+// ----- brain_token_impact (context-pack-economics-observability) ------------
+
+/**
+ * Durable token-impact + context-pack-quality ledger. `record`/`outcome`
+ * write opt-in samples (gated on `token_impact_ledger_enabled`, payload-safe:
+ * counts + opaque pack id only); `list`/`summary` read the ledger regardless
+ * of the gate so historical aggregates stay inspectable.
+ */
+async function toolBrainTokenImpact(
+ ctx: ServerContext,
+ args: Record<string, unknown>,
+): Promise<Record<string, unknown>> {
+ const operation = optionalStringArg("brain_token_impact", args, "operation");
+
+ if (operation === "record") {
+ const baselineTokens = coerceNonNegativeInteger(
+ "brain_token_impact",
+ "baseline_tokens",
+ args["baseline_tokens"],
+ );
+ const packedTokens = coerceNonNegativeInteger(
+ "brain_token_impact",
+ "packed_tokens",
+ args["packed_tokens"],
+ );
+ if (baselineTokens === undefined || packedTokens === undefined) {
+ throw new MCPError(
+ INVALID_PARAMS,
+ "brain_token_impact: record requires baseline_tokens and packed_tokens (non-negative integers)",
+ );
+ }
+ const method = coerceTokenCountMethod(args["method"]) ?? "fallback";
+ const modeledAvoided = coerceNonNegativeTokenValue(
+ "brain_token_impact",
+ "modeled_avoided_inferences",
+ args["modeled_avoided_inferences"],
+ );
+ const modeledPerInference = coerceNonNegativeTokenValue(
+ "brain_token_impact",
+ "modeled_tokens_per_inference",
+ args["modeled_tokens_per_inference"],
+ );
+ const enabled = resolveTokenImpactLedgerEnabled(ctx.configPath ?? undefined);
+ const record = emitTokenImpact(
+ ctx.vault,
+ {
+ baselineTokens,
+ packedTokens,
+ method,
+ ...tokenImpactCorrelation(args),
+ ...(modeledAvoided !== undefined ? { modeledAvoidedInferences: modeledAvoided } : {}),
+ ...(modeledPerInference !== undefined
+ ? { modeledTokensPerInference: modeledPerInference }
+ : {}),
+ },
+ enabled || undefined,
+ );
+ if (record === null) {
+ return { vault_path: ctx.vault, recorded: false, enabled };
+ }
+ return {
+ vault_path: ctx.vault,
+ recorded: true,
+ enabled,
+ id: record.id,
+ method,
+ baseline_tokens: baselineTokens,
+ packed_tokens: packedTokens,
+ delta_tokens: baselineTokens - packedTokens,
+ };
+ }
+
+ if (operation === "outcome") {
+ const outcome = coerceTokenImpactOutcome(args["outcome"]);
+ if (outcome === undefined) {
+ throw new MCPError(
+ INVALID_PARAMS,
+ "brain_token_impact: outcome requires outcome (first_pass | repair | retry)",
+ );
+ }
+ const tokensPerInference = coerceNonNegativeTokenValue(
+ "brain_token_impact",
+ "tokens_per_inference",
+ args["tokens_per_inference"],
+ );
+ const enabled = resolveTokenImpactLedgerEnabled(ctx.configPath ?? undefined);
+ const record = recordTokenImpactOutcome(
+ ctx.vault,
+ {
+ outcome,
+ ...tokenImpactCorrelation(args),
+ ...(tokensPerInference !== undefined ? { tokensPerInference } : {}),
+ },
+ enabled || undefined,
+ );
+ if (record === null) {
+ return { vault_path: ctx.vault, recorded: false, enabled };
+ }
+ return { vault_path: ctx.vault, recorded: true, enabled, id: record.id, outcome };
+ }
+
+ const filter = tokenImpactFilter(args);
+ if (operation === "list") {
+ const records = listTokenImpact(ctx.vault, filter);
+ return { vault_path: ctx.vault, total: records.length, records };
+ }
+ if (operation === "summary") {
+ return { vault_path: ctx.vault, ...summarizeTokenImpact(ctx.vault, filter) };
+ }
+ throw new MCPError(
+ INVALID_PARAMS,
+ "brain_token_impact: operation must be record, outcome, list, or summary",
+ );
+}
+
+function tokenImpactCorrelation(args: Record<string, unknown>): {
+ host?: string;
+ sessionId?: string;
+ turnId?: string;
+ packId?: string;
+} {
+ const host = optionalStringArg("brain_token_impact", args, "host");
+ const sessionId = optionalStringArg("brain_token_impact", args, "session_id");
+ const turnId = optionalStringArg("brain_token_impact", args, "turn_id");
+ const packId = optionalStringArg("brain_token_impact", args, "pack_id");
+ return {
+ ...(host !== undefined ? { host } : {}),
+ ...(sessionId !== undefined ? { sessionId } : {}),
+ ...(turnId !== undefined ? { turnId } : {}),
+ ...(packId !== undefined ? { packId } : {}),
+ };
+}
+
+function tokenImpactFilter(args: Record<string, unknown>): TokenImpactFilter {
+ const host = optionalStringArg("brain_token_impact", args, "host");
+ const packId = optionalStringArg("brain_token_impact", args, "pack_id");
+ const method = coerceTokenCountMethod(args["method"]);
+ const since = optionalStringArg("brain_token_impact", args, "since");
+ const until = optionalStringArg("brain_token_impact", args, "until");
+ const limit = coercePositiveInteger("brain_token_impact", "limit", args["limit"]);
+ const maxSamples = coercePositiveInteger(
+ "brain_token_impact",
+ "max_samples",
+ args["max_samples"],
+ );
+ return {
+ ...(host !== undefined ? { host } : {}),
+ ...(packId !== undefined ? { packId } : {}),
+ ...(method !== undefined ? { method } : {}),
+ ...(since !== undefined ? { since } : {}),
+ ...(until !== undefined ? { until } : {}),
+ ...(limit !== undefined ? { limit } : {}),
+ ...(maxSamples !== undefined ? { maxSamples } : {}),
+ };
+}
+
+function coerceTokenCountMethod(raw: unknown): TokenCountMethod | undefined {
+ if (raw === undefined || raw === null) return undefined;
+ const trimmed = typeof raw === "string" ? raw.trim() : raw;
+ if (!isTokenCountMethod(trimmed)) {
+ throw new MCPError(INVALID_PARAMS, "brain_token_impact: method must be exact or fallback");
+ }
+ return trimmed;
+}
+
+function coerceTokenImpactOutcome(raw: unknown): TokenImpactOutcome | undefined {
+ if (raw === undefined || raw === null) return undefined;
+ const trimmed = typeof raw === "string" ? raw.trim() : raw;
+ if (!isTokenImpactOutcome(trimmed)) {
+ throw new MCPError(
+ INVALID_PARAMS,
+ "brain_token_impact: outcome must be first_pass, repair, or retry",
+ );
+ }
+ return trimmed;
+}
+
+function coerceNonNegativeInteger(tool: string, field: string, raw: unknown): number | undefined {
+ if (raw === undefined || raw === null) return undefined;
+ if (typeof raw === "number") {
+ if (!Number.isInteger(raw) || raw < 0) {
+ throw new MCPError(INVALID_PARAMS, `${tool}: ${field} must be a non-negative integer`);
+ }
+ return raw;
+ }
+ if (typeof raw === "string") {
+ const trimmed = raw.trim();
+ if (trimmed === "" || !/^[0-9]+$/.test(trimmed)) {
+ throw new MCPError(INVALID_PARAMS, `${tool}: ${field} must be a non-negative integer`);
+ }
+ return Number.parseInt(trimmed, 10);
+ }
+ throw new MCPError(INVALID_PARAMS, `${tool}: ${field} must be a non-negative integer`);
+}
+
+function coerceNonNegativeTokenValue(
+ tool: string,
+ field: string,
+ raw: unknown,
+): number | undefined {
+ if (raw === undefined || raw === null) return undefined;
+ // Reject empty/whitespace-only strings explicitly: Number("") and
+ // Number(" ".trim()) both coerce to 0 and would otherwise be written to the
+ // durable ledger as a fabricated zero. Mirrors coerceNonNegativeInteger above.
+ if (typeof raw === "string" && raw.trim() === "") {
+ throw new MCPError(INVALID_PARAMS, `${tool}: ${field} must be a non-negative number`);
+ }
+ const value = typeof raw === "string" ? Number(raw.trim()) : raw;
+ if (typeof value !== "number" || !Number.isFinite(value) || value < 0) {
+ throw new MCPError(INVALID_PARAMS, `${tool}: ${field} must be a non-negative number`);
+ }
+ return value;
+}
+
+// ----- brain_context_pack_outcome (context-pack-economics-observability) ----
+
+/**
+ * Agent-operable context-pack outcome loop. `post` writes one compact
+ * outcome row (gated on `context_pack_outcome_enabled`, payload-safe:
+ * counters + an opaque sample id only) AND composes the C3 ledger by posting
+ * a matching first-pass/repair/retry calibration record. `list`/`summary`
+ * read the rows regardless of the gate so historical aggregates stay
+ * inspectable. The three token signals (exact/modeled/observed) stay strictly
+ * separate; a field the caller omits is never invented.
+ */
+async function toolBrainContextPackOutcome(
+ ctx: ServerContext,
+ args: Record<string, unknown>,
+): Promise<Record<string, unknown>> {
+ const operation = optionalStringArg("brain_context_pack_outcome", args, "operation");
+
+ if (operation === "post") {
+ const sampleId = requiredStringArg("brain_context_pack_outcome", args, "sample_id");
+ const firstPassSuccess = coerceBoolean(args["first_pass_success"]);
+ if (firstPassSuccess === undefined) {
+ throw new MCPError(
+ INVALID_PARAMS,
+ "brain_context_pack_outcome: post requires first_pass_success (boolean)",
+ );
+ }
+ const repairRequired = coerceBoolean(args["repair_required"]);
+ const retryCount = coerceNonNegativeInteger(
+ "brain_context_pack_outcome",
+ "retry_count",
+ args["retry_count"],
+ );
+ const followUpTokens = coerceNonNegativeInteger(
+ "brain_context_pack_outcome",
+ "follow_up_tokens",
+ args["follow_up_tokens"],
+ );
+ const exact = coerceNonNegativeTokenValue(
+ "brain_context_pack_outcome",
+ "exact_prompt_token_savings",
+ args["exact_prompt_token_savings"],
+ );
+ const modeled = coerceNonNegativeTokenValue(
+ "brain_context_pack_outcome",
+ "modeled_inference_avoidance",
+ args["modeled_inference_avoidance"],
+ );
+ const observed = coerceNonNegativeTokenValue(
+ "brain_context_pack_outcome",
+ "observed_provider_tokens",
+ args["observed_provider_tokens"],
+ );
+ const enabled = resolveContextPackOutcomeEnabled(ctx.configPath ?? undefined);
+ const record = emitContextPackOutcome(
+ ctx.vault,
+ {
+ sampleId,
+ firstPassSuccess,
+ ...contextPackOutcomeCorrelation(args),
+ // Omit-don't-invent: only forward fields the caller actually supplied.
+ ...(repairRequired !== undefined ? { repairRequired } : {}),
+ ...(retryCount !== undefined ? { retryCount } : {}),
+ ...(followUpTokens !== undefined ? { followUpTokens } : {}),
+ ...(exact !== undefined ? { exactPromptTokenSavings: exact } : {}),
+ ...(modeled !== undefined ? { modeledInferenceAvoidance: modeled } : {}),
+ ...(observed !== undefined ? { observedProviderTokens: observed } : {}),
+ },
+ enabled || undefined,
+ );
+ if (record === null) {
+ return { vault_path: ctx.vault, recorded: false, enabled };
+ }
+ return {
+ vault_path: ctx.vault,
+ recorded: true,
+ enabled,
+ id: record.id,
+ sample_id: sampleId,
+ first_pass_success: firstPassSuccess,
+ };
+ }
+
+ const filter = contextPackOutcomeFilter(args);
+ if (operation === "list") {
+ const records = listContextPackOutcomes(ctx.vault, filter);
+ return { vault_path: ctx.vault, total: records.length, records };
+ }
+ if (operation === "summary") {
+ return { vault_path: ctx.vault, ...summarizeContextPackOutcomes(ctx.vault, filter) };
+ }
+ throw new MCPError(
+ INVALID_PARAMS,
+ "brain_context_pack_outcome: operation must be post, list, or summary",
+ );
+}
+
+function contextPackOutcomeCorrelation(args: Record<string, unknown>): {
+ host?: string;
+ sessionId?: string;
+ turnId?: string;
+} {
+ const host = optionalStringArg("brain_context_pack_outcome", args, "host");
+ const sessionId = optionalStringArg("brain_context_pack_outcome", args, "session_id");
+ const turnId = optionalStringArg("brain_context_pack_outcome", args, "turn_id");
+ return {
+ ...(host !== undefined ? { host } : {}),
+ ...(sessionId !== undefined ? { sessionId } : {}),
+ ...(turnId !== undefined ? { turnId } : {}),
+ };
+}
+
+function contextPackOutcomeFilter(args: Record<string, unknown>): ContextPackOutcomeFilter {
+ const host = optionalStringArg("brain_context_pack_outcome", args, "host");
+ const sampleId = optionalStringArg("brain_context_pack_outcome", args, "sample_id");
+ const since = optionalStringArg("brain_context_pack_outcome", args, "since");
+ const until = optionalStringArg("brain_context_pack_outcome", args, "until");
+ const limit = coercePositiveInteger("brain_context_pack_outcome", "limit", args["limit"]);
+ const maxSamples = coercePositiveInteger(
+ "brain_context_pack_outcome",
+ "max_samples",
+ args["max_samples"],
+ );
+ return {
+ ...(host !== undefined ? { host } : {}),
+ ...(sampleId !== undefined ? { sampleId } : {}),
+ ...(since !== undefined ? { since } : {}),
+ ...(until !== undefined ? { until } : {}),
+ ...(limit !== undefined ? { limit } : {}),
+ ...(maxSamples !== undefined ? { maxSamples } : {}),
+ };
+}
+
+function coerceBoolean(raw: unknown): boolean | undefined {
+ if (raw === undefined || raw === null) return undefined;
+ if (typeof raw === "boolean") return raw;
+ if (raw === "true") return true;
+ if (raw === "false") return false;
+ throw new MCPError(
+ INVALID_PARAMS,
+ "brain_context_pack_outcome: boolean fields must be true or false",
+ );
+}
+
// ----- brain_knowledge_gaps (t_97091fff) -----------------------------------
async function toolBrainKnowledgeGaps(
@@ -467,6 +896,198 @@ export const RECALL_TOOLS: ReadonlyArray<ToolDefinition> = Object.freeze([
},
handler: toolBrainRecallTelemetry,
},
+ {
+ name: "brain_route_metrics",
+ previewBudget: MCP_PREVIEW_BUDGET,
+ description:
+ "Route-level MCP latency: list mcp_route_latency records or summarize per-tool latency (count, errors, min/avg/max, p50/p95/p99) slowest-first to find slow surfaces by endpoint. Emitted only when mcp_route_metrics_enabled is on; payload-safe (tool, scope, status, duration, arg keys). Read-only.",
+ inputSchema: {
+ type: "object",
+ properties: {
+ operation: {
+ type: "string",
+ enum: ["list", "summary"],
+ description: "list for raw records; summary for per-tool latency roll-up.",
+ },
+ tool: {
+ type: "string",
+ description: "Optional filter by MCP tool name.",
+ },
+ status: {
+ type: "string",
+ enum: ["ok", "error"],
+ description: "Optional filter by call status.",
+ },
+ since: {
+ type: "string",
+ description: "Optional inclusive lower timestamp bound.",
+ },
+ until: {
+ type: "string",
+ description: "Optional inclusive upper timestamp bound.",
+ },
+ limit: {
+ type: "integer",
+ minimum: 1,
+ description: "Optional maximum record count for list.",
+ },
+ },
+ required: ["operation"],
+ additionalProperties: false,
+ },
+ handler: toolBrainRouteMetrics,
+ },
+ {
+ name: "brain_token_impact",
+ previewBudget: MCP_PREVIEW_BUDGET,
+ description:
+ "Durable value-of-memory ledger. `record`: a pack's tokenizer-exact prompt-token delta (baseline−packed; method exact|fallback) + optional modeled inference-avoidance. `outcome` calibrates the model. `summary` keeps EXACT separate from MODELED; `list` reads samples. Gated write; payload-safe.",
+ inputSchema: {
+ type: "object",
+ properties: {
+ operation: {
+ type: "string",
+ enum: ["record", "outcome", "list", "summary"],
+ description: "record/outcome write opt-in samples; list/summary read the durable ledger.",
+ },
+ baseline_tokens: {
+ type: "integer",
+ minimum: 0,
+ description: "record: prompt-token cost WITHOUT the memory layer's compaction/selection.",
+ },
+ packed_tokens: {
+ type: "integer",
+ minimum: 0,
+ description: "record: prompt-token cost the memory layer actually shipped.",
+ },
+ method: {
+ type: "string",
+ enum: ["exact", "fallback"],
+ description:
+ "How the counts were obtained: a real tokenizer (exact) or a heuristic estimate (fallback, the default). Also a list/summary filter.",
+ },
+ modeled_avoided_inferences: {
+ type: "number",
+ minimum: 0,
+ description:
+ "record (optional): modeled count of inferences (repairs/retries) the layer avoided.",
+ },
+ modeled_tokens_per_inference: {
+ type: "number",
+ minimum: 0,
+ description: "record (optional): modeled average prompt tokens per avoided inference.",
+ },
+ outcome: {
+ type: "string",
+ enum: ["first_pass", "repair", "retry"],
+ description: "outcome: the observed result used to calibrate the modeled ledger.",
+ },
+ tokens_per_inference: {
+ type: "number",
+ minimum: 0,
+ description: "outcome (optional): observed prompt tokens for this inference.",
+ },
+ pack_id: {
+ type: "string",
+ description:
+ "Opaque correlation id (a receipt id or request hash) — never a raw prompt. Also a list/summary filter.",
+ },
+ host: { type: "string", description: "Optional host/runtime label; also a filter." },
+ session_id: { type: "string", description: "Optional session id recorded on the sample." },
+ turn_id: { type: "string", description: "Optional turn id recorded on the sample." },
+ since: { type: "string", description: "Optional inclusive lower timestamp bound." },
+ until: { type: "string", description: "Optional inclusive upper timestamp bound." },
+ limit: {
+ type: "integer",
+ minimum: 1,
+ description: "Optional maximum record count for list.",
+ },
+ max_samples: {
+ type: "integer",
+ minimum: 1,
+ description: "Optional cap on the most-recent samples aggregated by summary.",
+ },
+ },
+ required: ["operation"],
+ additionalProperties: false,
+ },
+ handler: toolBrainTokenImpact,
+ },
+ {
+ name: "brain_context_pack_outcome",
+ previewBudget: MCP_PREVIEW_BUDGET,
+ description:
+ "Agent-operable context-pack outcome loop. `post` records a compact outcome row for a carried sample id — first-pass/repair/retry counters plus three SEPARATE token signals (exact, modeled, observed) — and calibrates the token-impact ledger. `list`/`summary` read rows. Gated, payload-safe.",
+ inputSchema: {
+ type: "object",
+ properties: {
+ operation: {
+ type: "string",
+ enum: ["post", "list", "summary"],
+ description: "post writes one opt-in outcome row; list/summary read the durable ledger.",
+ },
+ sample_id: {
+ type: "string",
+ description:
+ "post: the carried recall/context-pack quality-sample id (a context-receipt id or opaque request hash) — never a raw prompt. Also a list/summary filter.",
+ },
+ first_pass_success: {
+ type: "boolean",
+ description: "post: whether the packed context led to a first-pass success.",
+ },
+ repair_required: {
+ type: "boolean",
+ description: "post (optional): whether the agent had to repair the first completion.",
+ },
+ retry_count: {
+ type: "integer",
+ minimum: 0,
+ description: "post (optional): how many retries the completion needed.",
+ },
+ follow_up_tokens: {
+ type: "integer",
+ minimum: 0,
+ description: "post (optional): tokens spent on follow-up turns after the first pass.",
+ },
+ exact_prompt_token_savings: {
+ type: "number",
+ minimum: 0,
+ description:
+ "post (optional): EXACT tokenizer-aware prompt-token savings (a measurement). Kept separate from the modeled and observed signals.",
+ },
+ modeled_inference_avoidance: {
+ type: "number",
+ minimum: 0,
+ description:
+ "post (optional): MODELED confidence-banded inference-avoidance estimate (a model). Kept separate from the exact and observed signals.",
+ },
+ observed_provider_tokens: {
+ type: "number",
+ minimum: 0,
+ description:
+ "post (optional): OBSERVED provider-reported token usage. Kept separate from the exact and modeled signals; also calibrates the token-impact ledger.",
+ },
+ host: { type: "string", description: "Optional host/runtime label; also a filter." },
+ session_id: { type: "string", description: "Optional session id recorded on the row." },
+ turn_id: { type: "string", description: "Optional turn id recorded on the row." },
+ since: { type: "string", description: "Optional inclusive lower timestamp bound." },
+ until: { type: "string", description: "Optional inclusive upper timestamp bound." },
+ limit: {
+ type: "integer",
+ minimum: 1,
+ description: "Optional maximum record count for list.",
+ },
+ max_samples: {
+ type: "integer",
+ minimum: 1,
+ description: "Optional cap on the most-recent rows aggregated by summary.",
+ },
+ },
+ required: ["operation"],
+ additionalProperties: false,
+ },
+ handler: toolBrainContextPackOutcome,
+ },
{
name: "brain_knowledge_gaps",
previewBudget: MCP_PREVIEW_BUDGET,
diff --git a/src/mcp/server.ts b/src/mcp/server.ts
index d1327f07..e0298eb8 100644
--- a/src/mcp/server.ts
+++ b/src/mcp/server.ts
@@ -4,7 +4,8 @@
* class, including handshake instructions and error semantics.
*/
-import { resolveAgentName } from "../core/config.ts";
+import { resolveAgentName, resolveMcpRouteMetricsEnabled } from "../core/config.ts";
+import { emitMcpRouteLatency, type McpRouteStatus } from "../core/brain/mcp-route-metrics.ts";
import { buildInstructions } from "./instructions.ts";
import {
INTERNAL_ERROR,
@@ -78,6 +79,13 @@ export class MCPServer {
private readonly scope: ToolScope;
private readonly artifactStore: ArtifactStore;
private readonly capabilityReport: ToolCapabilityReport;
+ /**
+ * Route-level latency metrics gate (config `mcp_route_metrics_enabled`),
+ * resolved once at construction. Off by default; when on, every tool
+ * call is timed and a payload-safe `mcp_route_latency` continuity
+ * record is emitted (fail-open).
+ */
+ private readonly routeMetricsEnabled: boolean;
constructor(opts: MCPServerOptions, runtimeOpts: MCPServerRuntimeOptions = {}) {
this.vault = opts.vault;
@@ -92,6 +100,7 @@ export class MCPServer {
});
this.tools = evaluated.tools;
this.capabilityReport = evaluated.report;
+ this.routeMetricsEnabled = resolveMcpRouteMetricsEnabled(this.configPath ?? undefined);
const runId = runtimeOpts.artifactRunId ?? `run-${process.pid}-${Date.now().toString(36)}`;
this.artifactStore = new ArtifactStore({ vault: this.vault, runId });
// Best-effort housekeeping: clear prior processes' stale artifacts.
@@ -116,7 +125,43 @@ export class MCPServer {
/** Public method for CLI tool-call bridge — the legacy code reached into `_tools`. */
async callTool(name: string, args: Record<string, unknown>): Promise<Record<string, unknown>> {
const tool = findTool(this.tools, name);
- return toolResult(tool, await tool.handler(this.context, args));
+ return toolResult(tool, await this.invokeToolHandler(tool, args));
+ }
+
+ /**
+ * Single seam through which every tool handler runs, for both the CLI
+ * bridge (`callTool`) and the JSON-RPC `tools/call` path. With route
+ * metrics off it is a transparent pass-through; with them on it times
+ * the handler and emits one payload-safe `mcp_route_latency` record
+ * (status `error` on throw), then re-raises so error handling upstream
+ * is unchanged. The emit is gated and fail-open, so it can never fail
+ * or slow-fail the call beyond one synchronous continuity append.
+ */
+ private async invokeToolHandler(
+ tool: ToolDefinition,
+ args: Record<string, unknown>,
+ ): Promise<unknown> {
+ if (!this.routeMetricsEnabled) return tool.handler(this.context, args);
+ const start = performance.now();
+ let status: McpRouteStatus = "ok";
+ try {
+ return await tool.handler(this.context, args);
+ } catch (exc) {
+ status = "error";
+ throw exc;
+ } finally {
+ emitMcpRouteLatency(
+ this.vault,
+ {
+ tool: tool.name,
+ scope: this.scope,
+ status,
+ durationMs: performance.now() - start,
+ argKeys: Object.keys(args),
+ },
+ this.routeMetricsEnabled,
+ );
+ }
}
/** Process one JSON-RPC request or notification. Returns null for notifications. */
@@ -248,7 +293,7 @@ export class MCPServer {
}
const args = argsRaw as Record<string, unknown>;
try {
- const structured = await tool.handler(this.context, args);
+ const structured = await this.invokeToolHandler(tool, args);
return buildMcpToolResult(tool, structured, this.artifactStore);
} catch (exc) {
if (exc instanceof MCPError) throw exc;
diff --git a/tests/core/brain/active-budget-pressure.test.ts b/tests/core/brain/active-budget-pressure.test.ts
new file mode 100644
index 00000000..44ef6931
--- /dev/null
+++ b/tests/core/brain/active-budget-pressure.test.ts
@@ -0,0 +1,253 @@
+/**
+ * Proactive active-memory budget-pressure watermark
+ * (context-pack-economics-observability, C4 / t_dfda8adb).
+ *
+ * `computeActiveBudgetPressure` measures active.md fill-rate against its
+ * injection byte budget, classifies health, and - only above the warn
+ * threshold - lists ranked eviction CANDIDATES (retired before
+ * confirmed) reusing the reactive drop order. "Empty output = healthy":
+ * the doctor surface stays quiet on healthy vaults. Suggestions only;
+ * nothing is mutated.
+ */
+
+import { describe, expect, test } from "bun:test";
+import { mkdirSync, mkdtempSync, readFileSync, rmSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+
+import {
+ CRITICAL_THRESHOLD,
+ ELEVATED_THRESHOLD,
+ computeActiveBudgetPressure,
+} from "../../../src/core/brain/active-budget-pressure.ts";
+import { runDoctor } from "../../../src/core/brain/doctor.ts";
+import { brainActivePath, brainDirs } from "../../../src/core/brain/paths.ts";
+
+/** A full rendered active.md body across every known section. */
+function body(): string {
+ return [
+ "# Active Brain Preferences",
+ "",
+ "Auto-generated by `dream`. Do not edit — changes will be overwritten.",
+ "",
+ "## Confirmed (2)",
+ "",
+ "- `pref-a` (confidence: high (0.95)) — Rule A",
+ "- `pref-b` (confidence: medium (0.50)) — Rule B",
+ "",
+ "## Most-applied (30d) (1)",
+ "",
+ "- `pref-a` (applied_in_window: 4)",
+ "",
+ "## Quarantine (1)",
+ "",
+ "_Probationary rules — still active._",
+ "",
+ "- `pref-q` (applied: 0 / violated: 2) — Quarantined rule",
+ "",
+ "## Recently retired (last 1)",
+ "",
+ "- `pref-r` — low_confidence on 2026-05-01",
+ ].join("\n");
+}
+
+describe("computeActiveBudgetPressure", () => {
+ test("healthy: fillRate <= threshold yields status healthy and NO candidates", () => {
+ const input = body();
+ // Budget far larger than the body -> low fill-rate.
+ const p = computeActiveBudgetPressure(input, input.length * 10);
+ expect(p.status).toBe("healthy");
+ expect(p.candidates).toHaveLength(0);
+ expect(p.fillRate).toBeLessThanOrEqual(ELEVATED_THRESHOLD);
+ });
+
+ test("fillRate is bytes / budget", () => {
+ const input = body();
+ const p = computeActiveBudgetPressure(input, input.length * 2);
+ expect(p.fillRate).toBeCloseTo(0.5, 10);
+ expect(p.bytes).toBe(input.length);
+ });
+
+ test("elevated band sits between the two thresholds", () => {
+ const input = body();
+ // Choose a budget so fillRate lands strictly between the thresholds.
+ const mid = (ELEVATED_THRESHOLD + CRITICAL_THRESHOLD) / 2;
+ const budget = Math.round(input.length / mid);
+ const p = computeActiveBudgetPressure(input, budget);
+ expect(p.status).toBe("elevated");
+ expect(p.candidates.length).toBeGreaterThan(0);
+ });
+
+ test("over budget: status critical, candidates ranked retired before quarantine before most-applied", () => {
+ const input = body();
+ const p = computeActiveBudgetPressure(input, input.length - 40);
+ expect(p.status).toBe("critical");
+ // Confirmed / preamble (keep-guard) never appear as candidates.
+ for (const c of p.candidates) {
+ expect(c.priority).toBeGreaterThan(0);
+ expect(c.sectionKey).not.toContain("Confirmed");
+ expect(c.sectionKey).not.toBe("preamble");
+ }
+ // Ranked highest-priority-to-drop first: retired (4) > quarantine (3) > most-applied (1).
+ const keys = p.candidates.map((c) => c.sectionKey);
+ const retiredAt = keys.findIndex((k) => k.startsWith("## Recently retired"));
+ const quarantineAt = keys.findIndex((k) => k.startsWith("## Quarantine"));
+ const mostAppliedAt = keys.findIndex((k) => k.startsWith("## Most-applied"));
+ expect(retiredAt).toBeGreaterThanOrEqual(0);
+ expect(retiredAt).toBeLessThan(quarantineAt);
+ expect(quarantineAt).toBeLessThan(mostAppliedAt);
+ // Priority is non-increasing down the ranked list.
+ for (let i = 1; i < p.candidates.length; i++) {
+ expect(p.candidates[i - 1]!.priority).toBeGreaterThanOrEqual(p.candidates[i]!.priority);
+ }
+ });
+
+ test("non-positive / non-finite budget is fully saturated -> critical", () => {
+ expect(computeActiveBudgetPressure(body(), 0).status).toBe("critical");
+ expect(computeActiveBudgetPressure(body(), 0).fillRate).toBe(Infinity);
+ expect(computeActiveBudgetPressure(body(), Number.NaN).status).toBe("critical");
+ // An empty body against a zero budget is still healthy (nothing overflows).
+ expect(computeActiveBudgetPressure("", 0).status).toBe("healthy");
+ expect(computeActiveBudgetPressure("", 0).fillRate).toBe(0);
+ });
+
+ test("deterministic", () => {
+ const a = computeActiveBudgetPressure(body(), 400);
+ const b = computeActiveBudgetPressure(body(), 400);
+ expect(a).toEqual(b);
+ });
+
+ test("distinct term: does NOT collide with the WatermarkState cursor", () => {
+ const src = readFileSync(
+ join(import.meta.dir, "../../../src/core/brain/active-budget-pressure.ts"),
+ "utf8",
+ );
+ // The unrelated last-processed cursor lives in skill-proposals.ts;
+ // this module must not reuse that identifier.
+ expect(src).not.toMatch(/\bWatermarkState\b/);
+ expect(src).toContain("active budget pressure");
+ });
+});
+
+// ----- doctor integration ---------------------------------------------------
+
+function makeVault(): string {
+ const vault = mkdtempSync(join(tmpdir(), "o2b-budget-pressure-"));
+ const dirs = brainDirs(vault);
+ mkdirSync(dirs.brain, { recursive: true });
+ mkdirSync(dirs.preferences, { recursive: true });
+ mkdirSync(dirs.log, { recursive: true });
+ writeFileSync(join(dirs.brain, "_BRAIN.md"), "---\ntitle: Brain\n---\n", "utf8");
+ return vault;
+}
+
+function writeBrainConfig(vault: string, injectBudgetChars: number): void {
+ const dirs = brainDirs(vault);
+ writeFileSync(
+ join(dirs.brain, "_brain.yaml"),
+ `schema_version: 1
+primary_agent: null
+dream:
+ candidate_threshold: 2
+ unconfirmed_window_days: 7
+ contradiction_window_days: 14
+retire:
+ stale_evidence_days: 90
+confidence:
+ low_max_applied: 2
+ medium_min: 0.4
+ high_min: 0.7
+snapshots:
+ retention_count: 10
+active:
+ inject_budget_chars: ${injectBudgetChars}
+`,
+ "utf8",
+ );
+}
+
+/**
+ * A rendered body comfortably larger than the minimum injection budget
+ * (500 chars) so the doctor check can exercise real over-budget
+ * pressure. Extra retired lines pad the tail - the section an operator
+ * archives first.
+ */
+function largeBody(): string {
+ const lines = [
+ "# Active Brain Preferences",
+ "",
+ "Auto-generated by `dream`. Do not edit — changes will be overwritten.",
+ "",
+ "## Confirmed (2)",
+ "",
+ "- `pref-a` (confidence: high (0.95)) — Keep this live rule around always",
+ "- `pref-b` (confidence: medium (0.50)) — Another live confirmed rule kept",
+ "",
+ "## Quarantine (1)",
+ "",
+ "- `pref-q` (applied: 0 / violated: 2) — A probationary quarantined rule here",
+ "",
+ "## Recently retired (last 6)",
+ "",
+ ];
+ for (let i = 0; i < 6; i++) {
+ lines.push(`- \`pref-r${i}\` — retired for low_confidence stale history on 2026-05-0${i + 1}`);
+ }
+ return lines.join("\n");
+}
+
+function writeActive(vault: string, bodyText: string): void {
+ writeFileSync(
+ brainActivePath(vault),
+ `---\nkind: brain-active\ngenerated_at: "2026-06-01T00:00:00Z"\n---\n\n${bodyText}\n`,
+ "utf8",
+ );
+}
+
+describe("runDoctor active-budget-pressure check", () => {
+ test("quiet on healthy vaults: no warning when under budget", () => {
+ const vault = makeVault();
+ try {
+ writeBrainConfig(vault, 100_000);
+ writeActive(vault, body());
+ const result = runDoctor(vault);
+ expect(result.warnings.some((w) => w.code === "active-budget-pressure")).toBe(false);
+ } finally {
+ rmSync(vault, { recursive: true, force: true });
+ }
+ });
+
+ test("over budget: one warning naming ranked candidates, vault unmutated", () => {
+ const vault = makeVault();
+ try {
+ const bodyText = largeBody();
+ // Minimum permitted injection budget (500); the body overflows it.
+ writeBrainConfig(vault, 500);
+ writeActive(vault, bodyText);
+ const before = readFileSync(brainActivePath(vault), "utf8");
+
+ const result = runDoctor(vault);
+ const hits = result.warnings.filter((w) => w.code === "active-budget-pressure");
+ expect(hits).toHaveLength(1);
+ expect(hits[0]!.message).toContain("active.md is at");
+ // Retired is the first archive candidate named.
+ expect(hits[0]!.message).toMatch(/Recently retired/);
+
+ // Suggestions only — the probe never rewrites active.md.
+ expect(readFileSync(brainActivePath(vault), "utf8")).toBe(before);
+ } finally {
+ rmSync(vault, { recursive: true, force: true });
+ }
+ });
+
+ test("missing active.md: silent", () => {
+ const vault = makeVault();
+ try {
+ writeBrainConfig(vault, 500);
+ const result = runDoctor(vault);
+ expect(result.warnings.some((w) => w.code === "active-budget-pressure")).toBe(false);
+ } finally {
+ rmSync(vault, { recursive: true, force: true });
+ }
+ });
+});
diff --git a/tests/core/brain/context-density.test.ts b/tests/core/brain/context-density.test.ts
new file mode 100644
index 00000000..4f50c0c6
--- /dev/null
+++ b/tests/core/brain/context-density.test.ts
@@ -0,0 +1,87 @@
+import { describe, expect, test } from "bun:test";
+
+import {
+ countWikilinks,
+ densityScore,
+ signalWeight,
+} from "../../../src/core/brain/context-density.ts";
+import { EPISTEMIC_STATUS } from "../../../src/core/brain/provenance/epistemic.ts";
+
+describe("countWikilinks", () => {
+ test("counts internal [[...]] markers, ignoring plain text", () => {
+ expect(countWikilinks("see [[a]] and [[b/c]] here")).toBe(2);
+ expect(countWikilinks("no links at all")).toBe(0);
+ });
+
+ test("is language-agnostic (no wordlist) - counts markers in any script", () => {
+ expect(countWikilinks("[[テスト]] и [[тема]]")).toBe(2);
+ });
+});
+
+describe("signalWeight", () => {
+ test("sums evidence grounding, connectivity, and epistemic weight", () => {
+ // 2 evidence refs (x2) + 1 body link (x1) + observed (3) = 4 + 1 + 3 = 8
+ expect(
+ signalWeight({
+ body: "grounded rule referencing [[premise]]",
+ evidenceRefs: ["[[sig-1]]", "[[sig-2]]"],
+ epistemic: EPISTEMIC_STATUS.observed,
+ }),
+ ).toBe(8);
+ });
+
+ test("a bare, contested page carries no signal", () => {
+ expect(
+ signalWeight({
+ body: "plain contested body",
+ evidenceRefs: [],
+ epistemic: EPISTEMIC_STATUS.unknown,
+ }),
+ ).toBe(0);
+ });
+
+ test("a grounded observed fact outweighs an equally-linked hypothesis", () => {
+ const observed = signalWeight({
+ body: "x",
+ evidenceRefs: [],
+ epistemic: EPISTEMIC_STATUS.observed,
+ });
+ const hypothesis = signalWeight({
+ body: "x",
+ evidenceRefs: [],
+ epistemic: EPISTEMIC_STATUS.hypothesis,
+ });
+ expect(observed).toBeGreaterThan(hypothesis);
+ });
+});
+
+describe("densityScore", () => {
+ test("is signal per estimated token - denser wins for equal signal, fewer tokens", () => {
+ const source = {
+ body: "[[a]]",
+ evidenceRefs: ["[[sig]]"],
+ epistemic: EPISTEMIC_STATUS.observed,
+ };
+ expect(densityScore(source, 4)).toBeGreaterThan(densityScore(source, 40));
+ });
+
+ test("non-positive or non-finite tokens yield 0 (cannot displace a real page)", () => {
+ const source = {
+ body: "[[a]]",
+ evidenceRefs: ["[[sig]]"],
+ epistemic: EPISTEMIC_STATUS.observed,
+ };
+ expect(densityScore(source, 0)).toBe(0);
+ expect(densityScore(source, -5)).toBe(0);
+ expect(densityScore(source, Number.NaN)).toBe(0);
+ });
+
+ test("deterministic - identical inputs yield the identical score", () => {
+ const source = {
+ body: "[[a]] [[b]]",
+ evidenceRefs: ["[[sig]]"],
+ epistemic: EPISTEMIC_STATUS.derived,
+ };
+ expect(densityScore(source, 10)).toBe(densityScore(source, 10));
+ });
+});
diff --git a/tests/core/brain/context-pack-outcome.test.ts b/tests/core/brain/context-pack-outcome.test.ts
new file mode 100644
index 00000000..2dd77199
--- /dev/null
+++ b/tests/core/brain/context-pack-outcome.test.ts
@@ -0,0 +1,247 @@
+import { afterEach, beforeEach, describe, expect, test } from "bun:test";
+import { mkdirSync, mkdtempSync, rmSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+
+import {
+ contextPackSampleId,
+ emitContextPackOutcome,
+ listContextPackOutcomes,
+ SampleCarrier,
+ summarizeContextPackOutcomes,
+} from "../../../src/core/brain/context-pack-outcome.ts";
+import { listTokenImpactOutcomes } from "../../../src/core/brain/token-impact.ts";
+
+let tmp: string;
+let vault: string;
+
+beforeEach(() => {
+ tmp = mkdtempSync(join(tmpdir(), "o2b-ctx-outcome-"));
+ vault = join(tmp, "vault");
+ mkdirSync(join(vault, "Brain"), { recursive: true });
+});
+
+afterEach(() => {
+ rmSync(tmp, { recursive: true, force: true });
+});
+
+describe("emitContextPackOutcome gating", () => {
+ test("gate off writes nothing and returns null", () => {
+ expect(
+ emitContextPackOutcome(vault, { sampleId: "s1", firstPassSuccess: true }, false),
+ ).toBeNull();
+ expect(
+ emitContextPackOutcome(vault, { sampleId: "s1", firstPassSuccess: true }, undefined),
+ ).toBeNull();
+ expect(listContextPackOutcomes(vault)).toHaveLength(0);
+ });
+
+ test("fail-open: a missing sample id never throws and writes nothing", () => {
+ expect(
+ emitContextPackOutcome(vault, { sampleId: " ", firstPassSuccess: true }, true),
+ ).toBeNull();
+ expect(listContextPackOutcomes(vault)).toHaveLength(0);
+ });
+});
+
+describe("emitContextPackOutcome token-signal separation", () => {
+ test("stores the three token signals as SEPARATE fields, never merged", () => {
+ const record = emitContextPackOutcome(
+ vault,
+ {
+ createdAt: "2026-07-01T00:00:00.000Z",
+ host: "mcp",
+ sampleId: "receipt_abc",
+ firstPassSuccess: true,
+ exactPromptTokenSavings: 680,
+ modeledInferenceAvoidance: 420,
+ observedProviderTokens: 1200,
+ },
+ true,
+ );
+ expect(record).not.toBeNull();
+ expect(record!.kind).toBe("context_pack_outcome");
+ const payload = record!.payload;
+ // three distinct keys — one per signal basis
+ expect(payload["exact_prompt_token_savings"]).toBe(680);
+ expect(payload["modeled_inference_avoidance"]).toBe(420);
+ expect(payload["observed_provider_tokens"]).toBe(1200);
+ // never conflated into a single merged headline figure
+ expect(payload["token_savings"]).toBeUndefined();
+ expect(payload["total_tokens"]).toBeUndefined();
+ expect(payload["tokens"]).toBeUndefined();
+ });
+});
+
+describe("emitContextPackOutcome privacy", () => {
+ test("stores only compact counters — no raw prompt/completion/source text", () => {
+ const record = emitContextPackOutcome(
+ vault,
+ {
+ sampleId: "receipt_abc",
+ firstPassSuccess: false,
+ repairRequired: true,
+ retryCount: 2,
+ followUpTokens: 90,
+ observedProviderTokens: 1500,
+ },
+ true,
+ );
+ const payload = record!.payload;
+ for (const value of Object.values(payload)) {
+ // no free-text field longer than an opaque id / label
+ if (typeof value === "string") expect(value.length).toBeLessThanOrEqual(64);
+ }
+ // the only strings are the opaque sample id (and optional labels)
+ expect(payload["sample_id"]).toBe("receipt_abc");
+ expect(payload["prompt"]).toBeUndefined();
+ expect(payload["completion"]).toBeUndefined();
+ expect(payload["text"]).toBeUndefined();
+ expect(record!.redacted).toBe(false);
+ });
+});
+
+describe("emitContextPackOutcome omit-don't-invent", () => {
+ test("a field the caller did not supply is OMITTED, not defaulted to 0", () => {
+ const record = emitContextPackOutcome(
+ vault,
+ { sampleId: "receipt_abc", firstPassSuccess: true },
+ true,
+ );
+ const payload = record!.payload;
+ expect(payload["sample_id"]).toBe("receipt_abc");
+ expect(payload["first_pass_success"]).toBe(true);
+ // none of the optional counters were invented
+ expect("repair_required" in payload).toBe(false);
+ expect("retry_count" in payload).toBe(false);
+ expect("follow_up_tokens" in payload).toBe(false);
+ expect("exact_prompt_token_savings" in payload).toBe(false);
+ expect("modeled_inference_avoidance" in payload).toBe(false);
+ expect("observed_provider_tokens" in payload).toBe(false);
+ });
+});
+
+describe("emitContextPackOutcome composes the C3 ledger", () => {
+ test("a first-pass outcome also lands in the token-impact calibration ledger", () => {
+ emitContextPackOutcome(
+ vault,
+ { sampleId: "receipt_abc", firstPassSuccess: true, observedProviderTokens: 1200 },
+ true,
+ );
+ const outcomes = listTokenImpactOutcomes(vault);
+ expect(outcomes).toHaveLength(1);
+ expect(outcomes[0]!.payload).toMatchObject({
+ outcome: "first_pass",
+ pack_id: "receipt_abc",
+ tokens_per_inference: 1200,
+ });
+ });
+
+ test("repair/retry map to the calibration outcome enum", () => {
+ emitContextPackOutcome(
+ vault,
+ { sampleId: "r1", firstPassSuccess: false, repairRequired: true },
+ true,
+ );
+ emitContextPackOutcome(vault, { sampleId: "r2", firstPassSuccess: false, retryCount: 3 }, true);
+ const outcomes = listTokenImpactOutcomes(vault);
+ const byPack = new Map(outcomes.map((r) => [r.payload["pack_id"], r.payload["outcome"]]));
+ expect(byPack.get("r1")).toBe("repair");
+ expect(byPack.get("r2")).toBe("retry");
+ });
+});
+
+describe("summarizeContextPackOutcomes", () => {
+ test("keeps the three token signals separate and reports a first-pass rate", () => {
+ emitContextPackOutcome(
+ vault,
+ { sampleId: "a", firstPassSuccess: true, exactPromptTokenSavings: 100 },
+ true,
+ );
+ emitContextPackOutcome(
+ vault,
+ {
+ sampleId: "b",
+ firstPassSuccess: false,
+ repairRequired: true,
+ modeledInferenceAvoidance: 50,
+ },
+ true,
+ );
+ emitContextPackOutcome(
+ vault,
+ { sampleId: "c", firstPassSuccess: true, observedProviderTokens: 900, followUpTokens: 30 },
+ true,
+ );
+ const summary = summarizeContextPackOutcomes(vault);
+ expect(summary.total).toBe(3);
+ expect(summary.first_pass_success).toBe(2);
+ expect(summary.repair_required).toBe(1);
+ expect(summary.first_pass_rate).toBe(0.6667);
+ expect(summary.token_signals.exact).toEqual({ samples: 1, prompt_token_savings: 100 });
+ expect(summary.token_signals.modeled).toEqual({ samples: 1, inference_avoidance: 50 });
+ expect(summary.token_signals.observed).toEqual({ samples: 1, provider_tokens: 900 });
+ expect(summary.follow_up).toEqual({ samples: 1, tokens: 30 });
+ });
+
+ test("empty ledger summarizes to zeros and a null rate", () => {
+ const summary = summarizeContextPackOutcomes(vault);
+ expect(summary.total).toBe(0);
+ expect(summary.first_pass_rate).toBeNull();
+ expect(summary.token_signals.exact.samples).toBe(0);
+ });
+});
+
+describe("contextPackSampleId carries the report's sample id", () => {
+ test("prefers the receipt id, falls back to telemetry, else null", () => {
+ expect(contextPackSampleId({ receiptId: "r1", telemetryId: "t1" })).toBe("r1");
+ expect(contextPackSampleId({ telemetryId: "t1" })).toBe("t1");
+ expect(contextPackSampleId({})).toBeNull();
+ });
+
+ test("feeds a carried sample id straight into an outcome post", () => {
+ const carrier = new SampleCarrier();
+ const sampleId = contextPackSampleId({ receiptId: "receipt_live" });
+ expect(sampleId).not.toBeNull();
+ carrier.remember(sampleId as string);
+ const record = emitContextPackOutcome(
+ vault,
+ { sampleId: carrier.latest() as string, firstPassSuccess: true },
+ true,
+ );
+ expect(record!.payload["sample_id"]).toBe("receipt_live");
+ });
+});
+
+describe("SampleCarrier bounded local state", () => {
+ test("carries the latest sample id and stays bounded", () => {
+ const carrier = new SampleCarrier(3);
+ expect(carrier.latest()).toBeNull();
+ carrier.remember("s1");
+ carrier.remember("s2");
+ carrier.remember("s3");
+ carrier.remember("s4"); // evicts s1
+ expect(carrier.size).toBe(3);
+ expect(carrier.latest()).toBe("s4");
+ expect(carrier.has("s1")).toBe(false);
+ expect(carrier.has("s2")).toBe(true);
+ expect([...carrier.all()]).toEqual(["s2", "s3", "s4"]);
+ });
+
+ test("re-remembering an id moves it to most-recent without growing", () => {
+ const carrier = new SampleCarrier(2);
+ carrier.remember("s1");
+ carrier.remember("s2");
+ carrier.remember("s1"); // move-to-front, no growth
+ expect(carrier.size).toBe(2);
+ expect(carrier.latest()).toBe("s1");
+ expect([...carrier.all()]).toEqual(["s2", "s1"]);
+ });
+
+ test("ignores blank ids", () => {
+ const carrier = new SampleCarrier();
+ carrier.remember(" ");
+ expect(carrier.latest()).toBeNull();
+ expect(carrier.size).toBe(0);
+ });
+});
diff --git a/tests/core/brain/context-pack.test.ts b/tests/core/brain/context-pack.test.ts
index ffeec845..6a1a2752 100644
--- a/tests/core/brain/context-pack.test.ts
+++ b/tests/core/brain/context-pack.test.ts
@@ -192,6 +192,97 @@ describe("packContext", () => {
expect(dedupedPack.items[1]!.referenceHint).toBe("see pref-first");
});
+ test("densityRanking OFF is byte-identical to the option being absent", () => {
+ writePref("older-dense", {
+ topic: "x",
+ principle: "dense body",
+ body: "[[a]] [[b]] grounded",
+ tier: "core",
+ created_at: "2026-01-01T00:00:00Z",
+ });
+ writePref("newer-sparse", {
+ topic: "x",
+ principle: "sparse body",
+ body: "plain",
+ tier: "core",
+ created_at: "2026-06-01T00:00:00Z",
+ });
+
+ const absent = packContext(vault, { maxTokens: 10_000 });
+ const off = packContext(vault, { maxTokens: 10_000, densityRanking: false });
+ expect(JSON.stringify(off)).toBe(JSON.stringify(absent));
+ // Recency wins with density off: the newer sparse page leads.
+ expect(off.items.map((i) => i.id)).toEqual(["pref-newer-sparse", "pref-older-dense"]);
+ expect(off.items.every((i) => i.density === undefined)).toBe(true);
+ });
+
+ // A long, low-signal body: many tokens, no links, no evidence - so its
+ // value-per-token density is unambiguously low.
+ const SPARSE_BODY =
+ "just some ordinary filler prose without any structural signal at all ".repeat(3);
+
+ test("densityRanking ON: a denser older page outranks a sparser newer one within a tier", () => {
+ writeFileSync(
+ join(vault, "Brain", "preferences", "pref-older-dense.md"),
+ [
+ "---",
+ "id: pref-older-dense",
+ "topic: x",
+ "principle: dense body",
+ "tier: core",
+ "created_at: 2026-01-01T00:00:00Z",
+ '_evidenced_by: ["[[sig-1]]", "[[sig-2]]"]',
+ "---",
+ "",
+ "[[a]] [[b]] [[c]] grounded",
+ ].join("\n"),
+ );
+ writePref("newer-sparse", {
+ topic: "x",
+ principle: "sparse body",
+ body: SPARSE_BODY,
+ tier: "core",
+ created_at: "2026-06-01T00:00:00Z",
+ });
+
+ const r = packContext(vault, { maxTokens: 10_000, densityRanking: true });
+ expect(r.items.map((i) => i.id)).toEqual(["pref-older-dense", "pref-newer-sparse"]);
+ // The score that broke the tie is surfaced on the leading item.
+ expect(r.items[0]!.density).toBeGreaterThan(r.items[1]!.density!);
+ });
+
+ test("densityRanking ON: a peripheral page never outranks a core one regardless of density", () => {
+ // A maximally dense peripheral page: evidence refs + many links.
+ writeFileSync(
+ join(vault, "Brain", "preferences", "pref-dense-peripheral.md"),
+ [
+ "---",
+ "id: pref-dense-peripheral",
+ "topic: x",
+ "principle: dense peripheral",
+ "tier: peripheral",
+ "created_at: 2026-06-01T00:00:00Z",
+ '_evidenced_by: ["[[e1]]", "[[e2]]", "[[e3]]"]',
+ "---",
+ "",
+ "[[a]] [[b]] [[c]] [[d]]",
+ ].join("\n"),
+ );
+ // A minimally dense core page: long low-signal body, no links/evidence.
+ writePref("sparse-core", {
+ topic: "x",
+ principle: "sparse core",
+ body: SPARSE_BODY,
+ tier: "core",
+ created_at: "2026-01-01T00:00:00Z",
+ });
+
+ const r = packContext(vault, { maxTokens: 10_000, densityRanking: true });
+ expect(r.items.map((i) => i.id)).toEqual(["pref-sparse-core", "pref-dense-peripheral"]);
+ // Tier is the coarse gate even though the peripheral page is denser.
+ expect(r.items[1]!.density).toBeGreaterThan(r.items[0]!.density!);
+ });
+
test("stops when next page would exceed budget", () => {
writePref("a", {
topic: "x",
diff --git a/tests/core/brain/mcp-route-metrics.test.ts b/tests/core/brain/mcp-route-metrics.test.ts
new file mode 100644
index 00000000..83fe5310
--- /dev/null
+++ b/tests/core/brain/mcp-route-metrics.test.ts
@@ -0,0 +1,173 @@
+import { afterEach, beforeEach, describe, expect, test } from "bun:test";
+import { mkdirSync, mkdtempSync, readFileSync, rmSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+
+import {
+ emitMcpRouteLatency,
+ listMcpRouteLatency,
+ summarizeMcpRouteLatency,
+} from "../../../src/core/brain/mcp-route-metrics.ts";
+
+let tmp: string;
+let vault: string;
+
+beforeEach(() => {
+ tmp = mkdtempSync(join(tmpdir(), "o2b-route-metrics-"));
+ vault = join(tmp, "vault");
+ mkdirSync(join(vault, "Brain"), { recursive: true });
+});
+
+afterEach(() => {
+ rmSync(tmp, { recursive: true, force: true });
+});
+
+describe("emitMcpRouteLatency gating", () => {
+ test("gate off writes nothing and returns null", () => {
+ expect(
+ emitMcpRouteLatency(vault, { tool: "brain_search", status: "ok", durationMs: 5 }, false),
+ ).toBeNull();
+ expect(
+ emitMcpRouteLatency(vault, { tool: "brain_search", status: "ok", durationMs: 5 }, undefined),
+ ).toBeNull();
+ expect(listMcpRouteLatency(vault)).toHaveLength(0);
+ });
+
+ test("gate on writes one record", () => {
+ const record = emitMcpRouteLatency(
+ vault,
+ {
+ createdAt: "2026-06-01T00:00:00.000Z",
+ tool: "brain_search",
+ scope: "full",
+ status: "ok",
+ durationMs: 12.6,
+ argKeys: ["query"],
+ },
+ true,
+ );
+ expect(record).not.toBeNull();
+ expect(record!.kind).toBe("mcp_route_latency");
+ expect(record!.payload).toMatchObject({
+ tool: "brain_search",
+ scope: "full",
+ status: "ok",
+ duration_ms: 13, // rounded
+ arg_keys: ["query"],
+ });
+ });
+
+ test("fail-open: a bad tool value never throws", () => {
+ expect(
+ emitMcpRouteLatency(vault, { tool: "" as string, status: "ok", durationMs: 1 }, true),
+ ).toBeNull();
+ expect(listMcpRouteLatency(vault)).toHaveLength(0);
+ });
+});
+
+describe("mcp route latency payload safety", () => {
+ test("only key names are stored, never argument values", () => {
+ emitMcpRouteLatency(
+ vault,
+ {
+ createdAt: "2026-06-01T00:00:00.000Z",
+ tool: "brain_feedback",
+ status: "ok",
+ durationMs: 3,
+ // Arg keys are schema property names; values are deliberately absent.
+ argKeys: ["principle", "topic", "signal"],
+ },
+ true,
+ );
+ const dir = join(vault, "Brain", "log", "continuity");
+ const raw = readFileSync(join(dir, "2026-06.jsonl"), "utf8");
+ expect(raw).toContain("principle");
+ expect(raw).toContain("brain_feedback");
+ // The record carries key names only — no free-text value smuggled in.
+ const record = JSON.parse(raw.trim());
+ expect(record.payload.arg_keys).toEqual(["principle", "signal", "topic"]); // sorted+unique
+ expect(record.sourceRefs).toEqual([]);
+ });
+
+ test("arg keys are de-duplicated and sorted", () => {
+ const record = emitMcpRouteLatency(
+ vault,
+ {
+ tool: "x",
+ status: "ok",
+ durationMs: 1,
+ argKeys: ["b", "a", "b", "a"],
+ },
+ true,
+ );
+ expect(record!.payload["arg_keys"]).toEqual(["a", "b"]);
+ });
+});
+
+describe("listMcpRouteLatency", () => {
+ test("newest-first, filterable by tool and status, limited", () => {
+ emitMcpRouteLatency(
+ vault,
+ { createdAt: "2026-06-01T00:00:00.000Z", tool: "a", status: "ok", durationMs: 1 },
+ true,
+ );
+ emitMcpRouteLatency(
+ vault,
+ { createdAt: "2026-06-01T00:00:01.000Z", tool: "b", status: "error", durationMs: 2 },
+ true,
+ );
+ emitMcpRouteLatency(
+ vault,
+ { createdAt: "2026-06-01T00:00:02.000Z", tool: "a", status: "ok", durationMs: 3 },
+ true,
+ );
+
+ const all = listMcpRouteLatency(vault);
+ expect(all).toHaveLength(3);
+ // Newest first.
+ expect(all[0]!.payload["duration_ms"]).toBe(3);
+
+ expect(listMcpRouteLatency(vault, { tool: "a" })).toHaveLength(2);
+ expect(listMcpRouteLatency(vault, { status: "error" })).toHaveLength(1);
+ expect(listMcpRouteLatency(vault, { limit: 1 })).toHaveLength(1);
+ });
+});
+
+describe("summarizeMcpRouteLatency", () => {
+ test("per-tool percentiles, slowest-first, error rollup", () => {
+ // Tool "slow": durations 10..100 -> high p95. Tool "fast": all 1.
+ for (const d of [10, 20, 30, 40, 50, 60, 70, 80, 90, 100]) {
+ emitMcpRouteLatency(vault, { tool: "slow", status: "ok", durationMs: d }, true);
+ }
+ emitMcpRouteLatency(vault, { tool: "fast", status: "ok", durationMs: 1 }, true);
+ emitMcpRouteLatency(vault, { tool: "fast", status: "error", durationMs: 1 }, true);
+
+ const summary = summarizeMcpRouteLatency(vault);
+ expect(summary.total).toBe(12);
+ expect(summary.error_count).toBe(1);
+ expect(summary.by_status).toEqual({ ok: 11, error: 1 });
+
+ // Slowest surface first.
+ expect(summary.routes[0]!.tool).toBe("slow");
+ const slow = summary.routes.find((r) => r.tool === "slow")!;
+ expect(slow.count).toBe(10);
+ expect(slow.min_ms).toBe(10);
+ expect(slow.max_ms).toBe(100);
+ expect(slow.avg_ms).toBe(55);
+ expect(slow.p50_ms).toBe(50); // ceil(0.5*10)=5 -> idx 4 -> 50
+ expect(slow.p95_ms).toBe(100); // ceil(0.95*10)=10 -> idx 9 -> 100
+
+ const fast = summary.routes.find((r) => r.tool === "fast")!;
+ expect(fast.count).toBe(2);
+ expect(fast.error_count).toBe(1);
+ });
+
+ test("limit does not shrink the summary window", () => {
+ for (const d of [1, 2, 3]) {
+ emitMcpRouteLatency(vault, { tool: "t", status: "ok", durationMs: d }, true);
+ }
+ const summary = summarizeMcpRouteLatency(vault, { limit: 1 });
+ expect(summary.total).toBe(3);
+ expect(summary.routes[0]!.count).toBe(3);
+ });
+});
diff --git a/tests/core/brain/token-impact.test.ts b/tests/core/brain/token-impact.test.ts
new file mode 100644
index 00000000..9a0f88fe
--- /dev/null
+++ b/tests/core/brain/token-impact.test.ts
@@ -0,0 +1,268 @@
+import { afterEach, beforeEach, describe, expect, test } from "bun:test";
+import { mkdirSync, mkdtempSync, readFileSync, rmSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+
+import {
+ emitTokenImpact,
+ listTokenImpact,
+ listTokenImpactOutcomes,
+ recordTokenImpactOutcome,
+ summarizeTokenImpact,
+} from "../../../src/core/brain/token-impact.ts";
+
+let tmp: string;
+let vault: string;
+
+beforeEach(() => {
+ tmp = mkdtempSync(join(tmpdir(), "o2b-token-impact-"));
+ vault = join(tmp, "vault");
+ mkdirSync(join(vault, "Brain"), { recursive: true });
+});
+
+afterEach(() => {
+ rmSync(tmp, { recursive: true, force: true });
+});
+
+describe("emitTokenImpact gating", () => {
+ test("gate off writes nothing and returns null", () => {
+ expect(
+ emitTokenImpact(vault, { baselineTokens: 100, packedTokens: 40, method: "exact" }, false),
+ ).toBeNull();
+ expect(
+ emitTokenImpact(vault, { baselineTokens: 100, packedTokens: 40, method: "exact" }, undefined),
+ ).toBeNull();
+ expect(listTokenImpact(vault)).toHaveLength(0);
+ });
+
+ test("gate on writes one record with a signed delta", () => {
+ const record = emitTokenImpact(
+ vault,
+ {
+ createdAt: "2026-06-01T00:00:00.000Z",
+ host: "mcp",
+ packId: "receipt_123",
+ baselineTokens: 1000,
+ packedTokens: 320,
+ method: "exact",
+ },
+ true,
+ );
+ expect(record).not.toBeNull();
+ expect(record!.kind).toBe("token_impact");
+ expect(record!.payload).toMatchObject({
+ host: "mcp",
+ pack_id: "receipt_123",
+ method: "exact",
+ baseline_tokens: 1000,
+ packed_tokens: 320,
+ delta_tokens: 680,
+ });
+ });
+
+ test("delta is negative when the memory layer adds tokens", () => {
+ const record = emitTokenImpact(
+ vault,
+ { baselineTokens: 200, packedTokens: 260, method: "fallback" },
+ true,
+ );
+ expect(record!.payload["delta_tokens"]).toBe(-60);
+ });
+
+ test("fail-open: an invalid method never throws and writes nothing", () => {
+ expect(
+ emitTokenImpact(
+ vault,
+ { baselineTokens: 1, packedTokens: 0, method: "bogus" as "exact" },
+ true,
+ ),
+ ).toBeNull();
+ // A negative count is also swallowed.
+ expect(
+ emitTokenImpact(vault, { baselineTokens: -5, packedTokens: 0, method: "exact" }, true),
+ ).toBeNull();
+ expect(listTokenImpact(vault)).toHaveLength(0);
+ });
+
+ test("modeled fields produce a separate modeled_savings figure", () => {
+ const record = emitTokenImpact(
+ vault,
+ {
+ baselineTokens: 500,
+ packedTokens: 500,
+ method: "exact",
+ modeledAvoidedInferences: 3,
+ modeledTokensPerInference: 1200,
+ },
+ true,
+ );
+ expect(record!.payload).toMatchObject({
+ delta_tokens: 0, // exact ledger unaffected by the model
+ modeled_avoided_inferences: 3,
+ modeled_tokens_per_inference: 1200,
+ modeled_savings_tokens: 3600,
+ });
+ });
+});
+
+describe("token-impact privacy", () => {
+ test("only counts and an opaque pack id land on disk", () => {
+ emitTokenImpact(
+ vault,
+ {
+ createdAt: "2026-06-01T00:00:00.000Z",
+ packId: "hash_abc",
+ baselineTokens: 10,
+ packedTokens: 4,
+ method: "fallback",
+ },
+ true,
+ );
+ const raw = readFileSync(join(vault, "Brain", "log", "continuity", "2026-06.jsonl"), "utf8");
+ const record = JSON.parse(raw.trim());
+ expect(record.payload.pack_id).toBe("hash_abc");
+ expect(record.sourceRefs).toEqual([]);
+ // No free-text prompt/recall keys smuggled in.
+ expect(Object.keys(record.payload).sort()).toEqual(
+ ["baseline_tokens", "delta_tokens", "method", "pack_id", "packed_tokens"].sort(),
+ );
+ });
+});
+
+describe("listTokenImpact", () => {
+ test("newest-first, filterable, limited", () => {
+ emitTokenImpact(
+ vault,
+ {
+ createdAt: "2026-06-01T00:00:00.000Z",
+ baselineTokens: 10,
+ packedTokens: 1,
+ method: "exact",
+ },
+ true,
+ );
+ emitTokenImpact(
+ vault,
+ {
+ createdAt: "2026-06-01T00:00:01.000Z",
+ baselineTokens: 20,
+ packedTokens: 2,
+ method: "fallback",
+ packId: "p2",
+ },
+ true,
+ );
+ const all = listTokenImpact(vault);
+ expect(all).toHaveLength(2);
+ expect(all[0]!.payload["baseline_tokens"]).toBe(20); // newest first
+ expect(listTokenImpact(vault, { method: "exact" })).toHaveLength(1);
+ expect(listTokenImpact(vault, { packId: "p2" })).toHaveLength(1);
+ expect(listTokenImpact(vault, { limit: 1 })).toHaveLength(1);
+ });
+});
+
+describe("summarizeTokenImpact — exact vs modeled separation", () => {
+ test("splits the prompt-token delta by method and never folds in the model", () => {
+ emitTokenImpact(vault, { baselineTokens: 100, packedTokens: 30, method: "exact" }, true); // +70
+ emitTokenImpact(vault, { baselineTokens: 50, packedTokens: 80, method: "exact" }, true); // -30
+ emitTokenImpact(
+ vault,
+ {
+ baselineTokens: 200,
+ packedTokens: 100,
+ method: "fallback",
+ modeledAvoidedInferences: 2,
+ modeledTokensPerInference: 500,
+ },
+ true,
+ ); // +100 exact, 1000 modeled
+
+ const s = summarizeTokenImpact(vault);
+ expect(s.total_samples).toBe(3);
+ // EXACT-type delta ledger.
+ expect(s.prompt_token_delta.net_savings_tokens).toBe(140); // 70 - 30 + 100
+ expect(s.prompt_token_delta.saved_tokens).toBe(170); // 70 + 100
+ expect(s.prompt_token_delta.added_tokens).toBe(30);
+ expect(s.prompt_token_delta.by_method.exact).toEqual({ samples: 2, net_savings_tokens: 40 });
+ expect(s.prompt_token_delta.by_method.fallback).toEqual({
+ samples: 1,
+ net_savings_tokens: 100,
+ });
+ // MODELED ledger is strictly separate.
+ expect(s.modeled_inference_avoidance.samples).toBe(1);
+ expect(s.modeled_inference_avoidance.raw_savings_tokens).toBe(1000);
+ // No outcomes posted yet -> uncalibrated, not zero.
+ expect(s.modeled_inference_avoidance.calibration.total_outcomes).toBe(0);
+ expect(s.modeled_inference_avoidance.calibration.first_pass_rate).toBeNull();
+ expect(s.modeled_inference_avoidance.calibrated_savings_tokens).toBeNull();
+ });
+
+ test("maxSamples bounds aggregation to the most-recent samples", () => {
+ for (let i = 0; i < 5; i += 1) {
+ emitTokenImpact(
+ vault,
+ {
+ createdAt: `2026-06-01T00:00:0${i}.000Z`,
+ baselineTokens: 10,
+ packedTokens: 0,
+ method: "exact",
+ },
+ true,
+ );
+ }
+ const s = summarizeTokenImpact(vault, { maxSamples: 2 });
+ expect(s.total_samples).toBe(2);
+ expect(s.prompt_token_delta.net_savings_tokens).toBe(20);
+ });
+});
+
+describe("outcome calibration", () => {
+ test("gate off records no outcome", () => {
+ expect(recordTokenImpactOutcome(vault, { outcome: "first_pass" }, false)).toBeNull();
+ expect(listTokenImpactOutcomes(vault)).toHaveLength(0);
+ });
+
+ test("posted outcomes calibrate the modeled figure by first-pass rate", () => {
+ emitTokenImpact(
+ vault,
+ {
+ baselineTokens: 0,
+ packedTokens: 0,
+ method: "exact",
+ modeledAvoidedInferences: 4,
+ modeledTokensPerInference: 1000,
+ },
+ true,
+ ); // raw modeled = 4000
+
+ // 3 first-pass, 1 repair -> first_pass_rate = 0.75.
+ recordTokenImpactOutcome(vault, { outcome: "first_pass", tokensPerInference: 800 }, true);
+ recordTokenImpactOutcome(vault, { outcome: "first_pass" }, true);
+ recordTokenImpactOutcome(vault, { outcome: "first_pass" }, true);
+ recordTokenImpactOutcome(vault, { outcome: "repair", tokensPerInference: 1200 }, true);
+
+ const s = summarizeTokenImpact(vault);
+ const cal = s.modeled_inference_avoidance.calibration;
+ expect(cal.total_outcomes).toBe(4);
+ expect(cal.first_pass).toBe(3);
+ expect(cal.repair).toBe(1);
+ expect(cal.first_pass_rate).toBe(0.75);
+ expect(cal.mean_tokens_per_inference).toBe(1000); // (800 + 1200) / 2
+ expect(s.modeled_inference_avoidance.raw_savings_tokens).toBe(4000);
+ expect(s.modeled_inference_avoidance.calibrated_savings_tokens).toBe(3000); // 4000 * 0.75
+ });
+
+ test("fail-open: an invalid outcome never throws", () => {
+ expect(recordTokenImpactOutcome(vault, { outcome: "nope" as "repair" }, true)).toBeNull();
+ expect(listTokenImpactOutcomes(vault)).toHaveLength(0);
+ });
+});
+
+describe("durability across restarts", () => {
+ test("aggregates are recomputed from disk (a fresh read sees prior samples)", () => {
+ emitTokenImpact(vault, { baselineTokens: 90, packedTokens: 10, method: "exact" }, true);
+ // A brand-new summarize call reads only the on-disk continuity log.
+ const s = summarizeTokenImpact(vault);
+ expect(s.prompt_token_delta.net_savings_tokens).toBe(80);
+ });
+});
diff --git a/tests/mcp/brain-tools-parity.test.ts b/tests/mcp/brain-tools-parity.test.ts
index 2294da0b..6872220d 100644
--- a/tests/mcp/brain-tools-parity.test.ts
+++ b/tests/mcp/brain-tools-parity.test.ts
@@ -22,7 +22,15 @@
* bridge — persists native built-in-memory writes as durable
* host_memory_write continuity records); the dashboard-context-trace
* release added `brain_event_trace` (joins logged Brain events to the
- * continuity records attached to them by shared correlation ids).
+ * continuity records attached to them by shared correlation ids); the
+ * context-pack-economics-observability release added
+ * `brain_route_metrics` (route-level MCP tool latency read over opt-in
+ * `mcp_route_latency` continuity records) and `brain_token_impact` (durable
+ * token-impact ledger: tokenizer-exact prompt-token deltas kept strictly
+ * separate from a modeled, outcome-calibrated inference-avoidance estimate)
+ * and `brain_context_pack_outcome` (agent-operable outcome loop: a compact
+ * per-sample outcome row keeping the exact/modeled/observed token signals
+ * strictly separate, composing the token-impact ledger's calibration).
*/
import { describe, expect, test } from "bun:test";
@@ -45,6 +53,7 @@ const FROZEN_BRAIN_TOOL_NAMES = [
"brain_codegraph_report",
"brain_context",
"brain_context_pack",
+ "brain_context_pack_outcome",
"brain_context_presets",
"brain_context_receipts",
"brain_create_note",
@@ -86,6 +95,7 @@ const FROZEN_BRAIN_TOOL_NAMES = [
"brain_research_report",
"brain_retention",
"brain_review_candidates",
+ "brain_route_metrics",
"brain_secrets",
"brain_session_describe",
"brain_session_expand",
@@ -96,6 +106,7 @@ const FROZEN_BRAIN_TOOL_NAMES = [
"brain_stale_scan",
"brain_switch_vault",
"brain_tiers",
+ "brain_token_impact",
"brain_trigger",
"brain_truth",
"brain_tune",
diff --git a/tests/mcp/context-pack-outcome-tool.test.ts b/tests/mcp/context-pack-outcome-tool.test.ts
new file mode 100644
index 00000000..87cf184c
--- /dev/null
+++ b/tests/mcp/context-pack-outcome-tool.test.ts
@@ -0,0 +1,214 @@
+import { afterEach, beforeEach, describe, expect, test } from "bun:test";
+import { mkdirSync, mkdtempSync, rmSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+
+import { atomicWriteFileSync } from "../../src/core/fs-atomic.ts";
+import { listContextPackOutcomes } from "../../src/core/brain/context-pack-outcome.ts";
+import { listTokenImpactOutcomes } from "../../src/core/brain/token-impact.ts";
+import { JSONRPC_VERSION, MCPServer, PROTOCOL_VERSION } from "../../src/mcp/index.ts";
+import { buildToolTable } from "../../src/mcp/tools.ts";
+
+let tmp: string;
+let vault: string;
+let configHome: string;
+let configPath: string;
+const savedEnv: Record<string, string | undefined> = {};
+
+function writeConfig(enabled: boolean): void {
+ atomicWriteFileSync(
+ configPath,
+ `vault: ${vault}\nagent_name: claude\ncontext_pack_outcome_enabled: "${enabled}"\n`,
+ );
+}
+
+beforeEach(() => {
+ tmp = mkdtempSync(join(tmpdir(), "o2b-ctx-outcome-tool-"));
+ vault = join(tmp, "vault");
+ mkdirSync(join(vault, "Brain"), { recursive: true });
+ configHome = mkdtempSync(join(tmpdir(), "o2b-ctx-outcome-tool-cfg-"));
+ configPath = join(configHome, "config.yaml");
+ for (const key of [
+ "VAULT_AGENT_NAME",
+ "VAULT_TIMEZONE",
+ "VAULT_DIR",
+ "OPEN_SECOND_BRAIN_CONFIG",
+ "OPEN_SECOND_BRAIN_CONTEXT_PACK_OUTCOME_ENABLED",
+ ]) {
+ savedEnv[key] = process.env[key];
+ delete process.env[key];
+ }
+ process.env["OPEN_SECOND_BRAIN_CONFIG"] = configPath;
+});
+
+afterEach(() => {
+ rmSync(tmp, { recursive: true, force: true });
+ rmSync(configHome, { recursive: true, force: true });
+ for (const [key, value] of Object.entries(savedEnv)) {
+ if (value === undefined) delete process.env[key];
+ else process.env[key] = value;
+ }
+});
+
+async function initialize(server: MCPServer): Promise<void> {
+ await server.handleRequest({
+ jsonrpc: JSONRPC_VERSION,
+ id: 1,
+ method: "initialize",
+ params: {
+ protocolVersion: PROTOCOL_VERSION,
+ capabilities: {},
+ clientInfo: { name: "ctx-outcome-test", version: "0" },
+ },
+ });
+}
+
+async function callTool(
+ server: MCPServer,
+ name: string,
+ args: Record<string, unknown>,
+): Promise<Record<string, unknown>> {
+ const response = (await server.handleRequest({
+ jsonrpc: JSONRPC_VERSION,
+ id: 9,
+ method: "tools/call",
+ params: { name, arguments: args },
+ })) as { result: { content: ReadonlyArray<{ type: string; text: string }> } };
+ return JSON.parse(response.result.content[0]!.text);
+}
+
+describe("brain_context_pack_outcome registration", () => {
+ test("registered in the full tool table only", () => {
+ expect(
+ buildToolTable("full").find((t) => t.name === "brain_context_pack_outcome"),
+ ).toBeDefined();
+ expect(
+ buildToolTable("writer").find((t) => t.name === "brain_context_pack_outcome"),
+ ).toBeUndefined();
+ });
+});
+
+describe("brain_context_pack_outcome post gating", () => {
+ test("gate off records nothing but reports enabled:false", async () => {
+ writeConfig(false);
+ const server = new MCPServer({ vault, configPath });
+ await initialize(server);
+ const out = await callTool(server, "brain_context_pack_outcome", {
+ operation: "post",
+ sample_id: "receipt_1",
+ first_pass_success: true,
+ });
+ expect(out["recorded"]).toBe(false);
+ expect(out["enabled"]).toBe(false);
+ expect(listContextPackOutcomes(vault)).toHaveLength(0);
+ expect(listTokenImpactOutcomes(vault)).toHaveLength(0);
+ });
+
+ test("gate on records an outcome row and composes the token-impact ledger", async () => {
+ writeConfig(true);
+ const server = new MCPServer({ vault, configPath });
+ await initialize(server);
+ const out = await callTool(server, "brain_context_pack_outcome", {
+ operation: "post",
+ sample_id: "receipt_1",
+ first_pass_success: true,
+ exact_prompt_token_savings: 680,
+ modeled_inference_avoidance: 420,
+ observed_provider_tokens: 1200,
+ });
+ expect(out["recorded"]).toBe(true);
+ expect(out["sample_id"]).toBe("receipt_1");
+
+ const rows = listContextPackOutcomes(vault);
+ expect(rows).toHaveLength(1);
+ // three signals as separate keys, never merged
+ expect(rows[0]!.payload["exact_prompt_token_savings"]).toBe(680);
+ expect(rows[0]!.payload["modeled_inference_avoidance"]).toBe(420);
+ expect(rows[0]!.payload["observed_provider_tokens"]).toBe(1200);
+
+ // composes C3
+ const outcomes = listTokenImpactOutcomes(vault);
+ expect(outcomes).toHaveLength(1);
+ expect(outcomes[0]!.payload).toMatchObject({
+ outcome: "first_pass",
+ pack_id: "receipt_1",
+ tokens_per_inference: 1200,
+ });
+ });
+
+ test("omit-don't-invent: unsupplied optional counters are absent", async () => {
+ writeConfig(true);
+ const server = new MCPServer({ vault, configPath });
+ await initialize(server);
+ await callTool(server, "brain_context_pack_outcome", {
+ operation: "post",
+ sample_id: "receipt_1",
+ first_pass_success: true,
+ });
+ const payload = listContextPackOutcomes(vault)[0]!.payload;
+ expect("retry_count" in payload).toBe(false);
+ expect("exact_prompt_token_savings" in payload).toBe(false);
+ expect("observed_provider_tokens" in payload).toBe(false);
+ });
+
+ test("rejects a missing first_pass_success", async () => {
+ writeConfig(true);
+ const server = new MCPServer({ vault, configPath });
+ await initialize(server);
+ const response = (await server.handleRequest({
+ jsonrpc: JSONRPC_VERSION,
+ id: 9,
+ method: "tools/call",
+ params: {
+ name: "brain_context_pack_outcome",
+ arguments: { operation: "post", sample_id: "receipt_1" },
+ },
+ })) as { result?: { isError?: boolean }; error?: unknown };
+ expect(response.error ?? response.result?.isError).toBeTruthy();
+ });
+});
+
+describe("brain_context_pack_outcome summary reads even with the gate off", () => {
+ test("summary keeps the three token signals separate", async () => {
+ writeConfig(true);
+ let server = new MCPServer({ vault, configPath });
+ await initialize(server);
+ await callTool(server, "brain_context_pack_outcome", {
+ operation: "post",
+ sample_id: "a",
+ first_pass_success: true,
+ exact_prompt_token_savings: 100,
+ });
+ await callTool(server, "brain_context_pack_outcome", {
+ operation: "post",
+ sample_id: "b",
+ first_pass_success: false,
+ repair_required: true,
+ modeled_inference_avoidance: 50,
+ });
+ // flip the gate off — reads still work
+ writeConfig(false);
+ server = new MCPServer({ vault, configPath });
+ await initialize(server);
+ const summary = await callTool(server, "brain_context_pack_outcome", { operation: "summary" });
+ expect(summary["total"]).toBe(2);
+ expect(summary["first_pass_rate"]).toBe(0.5);
+ const signals = summary["token_signals"] as Record<string, Record<string, unknown>>;
+ expect(signals["exact"]!["prompt_token_savings"]).toBe(100);
+ expect(signals["modeled"]!["inference_avoidance"]).toBe(50);
+ expect(signals["observed"]!["samples"]).toBe(0);
+ });
+
+ test("rejects an unknown operation", async () => {
+ writeConfig(true);
+ const server = new MCPServer({ vault, configPath });
+ await initialize(server);
+ const response = (await server.handleRequest({
+ jsonrpc: JSONRPC_VERSION,
+ id: 9,
+ method: "tools/call",
+ params: { name: "brain_context_pack_outcome", arguments: { operation: "bogus" } },
+ })) as { result?: { isError?: boolean }; error?: unknown };
+ expect(response.error ?? response.result?.isError).toBeTruthy();
+ });
+});
diff --git a/tests/mcp/context-pack-tool.test.ts b/tests/mcp/context-pack-tool.test.ts
index 2514e2b5..348778a3 100644
--- a/tests/mcp/context-pack-tool.test.ts
+++ b/tests/mcp/context-pack-tool.test.ts
@@ -188,6 +188,44 @@ describe("brain_context_pack tool — round trip", () => {
});
});
+ test("density ranking is gated off by default (no density field emitted)", async () => {
+ writeFileSync(
+ join(vault, "Brain", "preferences", "pref-core.md"),
+ "---\nid: pref-core\ntopic: x\nprinciple: p\ntier: core\ncreated_at: 2026-05-01T00:00:00Z\n---\n\n[[a]] [[b]]\n",
+ );
+ const server = new MCPServer({ vault, configPath });
+ await initialize(server);
+ const out = await callPack(server, { max_tokens: 10_000 });
+ const items = out["items"] as Array<Record<string, unknown>>;
+ expect(items[0]!["density"]).toBeUndefined();
+ });
+
+ test("density_ranking_context_pack config gate ranks the denser page first within a tier", async () => {
+ atomicWriteFileSync(
+ configPath,
+ `vault: ${vault}\nagent_name: claude\ndensity_ranking_context_pack: "true"\n`,
+ );
+ // Older but dense: evidence refs + links → high value per token.
+ writeFileSync(
+ join(vault, "Brain", "preferences", "pref-dense.md"),
+ '---\nid: pref-dense\ntopic: x\nprinciple: p\ntier: core\ncreated_at: 2026-01-01T00:00:00Z\n_evidenced_by: ["[[s1]]", "[[s2]]"]\n---\n\n[[a]] [[b]] [[c]]\n',
+ );
+ // Newer but sparse: long low-signal body → low value per token.
+ writeFileSync(
+ join(vault, "Brain", "preferences", "pref-sparse.md"),
+ "---\nid: pref-sparse\ntopic: x\nprinciple: p\ntier: core\ncreated_at: 2026-06-01T00:00:00Z\n---\n\n" +
+ "ordinary filler prose with no structural signal at all ".repeat(3) +
+ "\n",
+ );
+ const server = new MCPServer({ vault, configPath });
+ await initialize(server);
+ const out = await callPack(server, { max_tokens: 10_000 });
+ const items = out["items"] as Array<{ id: string; density?: number }>;
+ expect(items.map((i) => i.id)).toEqual(["pref-dense", "pref-sparse"]);
+ expect(typeof items[0]!.density).toBe("number");
+ expect(items[0]!.density!).toBeGreaterThan(items[1]!.density!);
+ });
+
test("rejects non-positive max_tokens via INVALID_PARAMS", async () => {
const server = new MCPServer({ vault, configPath });
await initialize(server);
diff --git a/tests/mcp/mcp.test.ts b/tests/mcp/mcp.test.ts
index 21cc0780..f8f1c4b6 100644
--- a/tests/mcp/mcp.test.ts
+++ b/tests/mcp/mcp.test.ts
@@ -212,6 +212,7 @@ describe("tool listing", () => {
"brain_sources",
"brain_switch_vault",
"brain_context_pack",
+ "brain_context_pack_outcome",
"brain_unlinked_mentions",
"brain_moc_audit",
"brain_stale_scan",
@@ -293,6 +294,10 @@ describe("tool listing", () => {
"brain_agenda",
// Hermes on_memory_write host bridge (memory-subsystem-alignment).
"brain_memory_bridge",
+ // Route-level MCP latency (context-pack-economics-observability).
+ "brain_route_metrics",
+ // Durable token-impact ledger (context-pack-economics-observability).
+ "brain_token_impact",
].toSorted(),
);
// Explicit grep: legacy writable tools are no longer advertised.
@@ -567,7 +572,10 @@ describe("stdio loop", () => {
// + brain_event_trace (dashboard-context-trace: event→trace join) = 87.
// + brain_search_expand (progressive disclosure: search→expand→transcript) = 88.
// + brain_knowledge_gaps (cross-query demand log, t_97091fff) = 89.
- expect(list.result.tools.length).toBe(89);
+ // + brain_route_metrics (route-level MCP latency, context-pack-economics-observability) = 90.
+ // + brain_token_impact (durable token-impact ledger, context-pack-economics-observability) = 91.
+ // + brain_context_pack_outcome (agent-operable outcome loop, context-pack-economics-observability) = 92.
+ expect(list.result.tools.length).toBe(92);
});
test("returns parse error for invalid JSON", async () => {
diff --git a/tests/mcp/removed-tools.test.ts b/tests/mcp/removed-tools.test.ts
index 914ed406..7579c521 100644
--- a/tests/mcp/removed-tools.test.ts
+++ b/tests/mcp/removed-tools.test.ts
@@ -149,5 +149,8 @@ test("the shadow surface is gone: no hidden tools, removed names unlisted", asyn
// + brain_event_trace (dashboard-context-trace: event→trace join) = 87.
// + brain_search_expand (progressive disclosure: search→expand→transcript) = 88.
// + brain_knowledge_gaps (cross-query demand log, t_97091fff) = 89.
- expect(list.result.tools.length).toBe(89);
+ // + brain_route_metrics (route-level MCP latency, context-pack-economics-observability) = 90.
+ // + brain_token_impact (durable token-impact ledger, context-pack-economics-observability) = 91.
+ // + brain_context_pack_outcome (agent-operable outcome loop, context-pack-economics-observability) = 92.
+ expect(list.result.tools.length).toBe(92);
});
diff --git a/tests/mcp/route-metrics-tool.test.ts b/tests/mcp/route-metrics-tool.test.ts
new file mode 100644
index 00000000..a76844d1
--- /dev/null
+++ b/tests/mcp/route-metrics-tool.test.ts
@@ -0,0 +1,180 @@
+import { afterEach, beforeEach, describe, expect, test } from "bun:test";
+import { mkdirSync, mkdtempSync, rmSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+
+import { atomicWriteFileSync } from "../../src/core/fs-atomic.ts";
+import { listMcpRouteLatency } from "../../src/core/brain/mcp-route-metrics.ts";
+import { JSONRPC_VERSION, MCPServer, PROTOCOL_VERSION } from "../../src/mcp/index.ts";
+import { buildToolTable } from "../../src/mcp/tools.ts";
+
+let tmp: string;
+let vault: string;
+let configHome: string;
+let configPath: string;
+const savedEnv: Record<string, string | undefined> = {};
+
+function writeConfig(routeMetrics: boolean): void {
+ atomicWriteFileSync(
+ configPath,
+ `vault: ${vault}\nagent_name: claude\nmcp_route_metrics_enabled: "${routeMetrics}"\n`,
+ );
+}
+
+beforeEach(() => {
+ tmp = mkdtempSync(join(tmpdir(), "o2b-route-metrics-tool-"));
+ vault = join(tmp, "vault");
+ mkdirSync(join(vault, "Brain"), { recursive: true });
+ configHome = mkdtempSync(join(tmpdir(), "o2b-route-metrics-tool-cfg-"));
+ configPath = join(configHome, "config.yaml");
+ for (const key of [
+ "VAULT_AGENT_NAME",
+ "VAULT_TIMEZONE",
+ "VAULT_DIR",
+ "OPEN_SECOND_BRAIN_CONFIG",
+ "OPEN_SECOND_BRAIN_MCP_ROUTE_METRICS_ENABLED",
+ ]) {
+ savedEnv[key] = process.env[key];
+ delete process.env[key];
+ }
+ process.env["OPEN_SECOND_BRAIN_CONFIG"] = configPath;
+});
+
+afterEach(() => {
+ rmSync(tmp, { recursive: true, force: true });
+ rmSync(configHome, { recursive: true, force: true });
+ for (const [key, value] of Object.entries(savedEnv)) {
+ if (value === undefined) delete process.env[key];
+ else process.env[key] = value;
+ }
+});
+
+async function initialize(server: MCPServer): Promise<void> {
+ await server.handleRequest({
+ jsonrpc: JSONRPC_VERSION,
+ id: 1,
+ method: "initialize",
+ params: {
+ protocolVersion: PROTOCOL_VERSION,
+ capabilities: {},
+ clientInfo: { name: "route-metrics-test", version: "0" },
+ },
+ });
+}
+
+async function callTool(
+ server: MCPServer,
+ name: string,
+ args: Record<string, unknown>,
+): Promise<Record<string, unknown>> {
+ const response = (await server.handleRequest({
+ jsonrpc: JSONRPC_VERSION,
+ id: 9,
+ method: "tools/call",
+ params: { name, arguments: args },
+ })) as { result: { content: ReadonlyArray<{ type: string; text: string }> } };
+ return JSON.parse(response.result.content[0]!.text);
+}
+
+describe("brain_route_metrics registration", () => {
+ test("registered in the full tool table only", () => {
+ expect(
+ buildToolTable("full").find((tool) => tool.name === "brain_route_metrics"),
+ ).toBeDefined();
+ expect(
+ buildToolTable("writer").find((tool) => tool.name === "brain_route_metrics"),
+ ).toBeUndefined();
+ });
+});
+
+describe("route latency capture through tools/call", () => {
+ test("gate off records nothing", async () => {
+ writeConfig(false);
+ const server = new MCPServer({ vault, configPath });
+ await initialize(server);
+ await callTool(server, "second_brain_status", {});
+ expect(listMcpRouteLatency(vault)).toHaveLength(0);
+ });
+
+ test("gate on records one payload-safe record per call", async () => {
+ writeConfig(true);
+ const server = new MCPServer({ vault, configPath });
+ await initialize(server);
+
+ await callTool(server, "second_brain_status", {});
+ await callTool(server, "second_brain_query", { pattern: "x", limit: 5 });
+
+ const records = listMcpRouteLatency(vault);
+ expect(records).toHaveLength(2);
+ const tools = records.map((r) => r.payload["tool"]).toSorted();
+ expect(tools).toEqual(["second_brain_query", "second_brain_status"]);
+ for (const r of records) {
+ expect(r.payload["status"]).toBe("ok");
+ expect(r.payload["scope"]).toBe("full");
+ expect(typeof r.payload["duration_ms"]).toBe("number");
+ }
+ // Query call recorded its schema arg key NAMES, never the values.
+ const query = records.find((r) => r.payload["tool"] === "second_brain_query")!;
+ expect(query.payload["arg_keys"]).toEqual(["limit", "pattern"]);
+ });
+
+ test("a failing tool call is recorded with status error and still errors upstream", async () => {
+ writeConfig(true);
+ const server = new MCPServer({ vault, configPath });
+ await initialize(server);
+
+ // artifact_get with an unknown id → handler throws → tool error envelope.
+ const response = (await server.handleRequest({
+ jsonrpc: JSONRPC_VERSION,
+ id: 9,
+ method: "tools/call",
+ params: { name: "brain_artifact_get", arguments: { artifact_id: "nope" } },
+ })) as { result?: { isError?: boolean }; error?: unknown };
+ expect(response.error ?? response.result?.isError).toBeTruthy();
+
+ const records = listMcpRouteLatency(vault, { tool: "brain_artifact_get" });
+ expect(records).toHaveLength(1);
+ expect(records[0]!.payload["status"]).toBe("error");
+ });
+
+ test("brain_route_metrics summary ranks the slowest surface first", async () => {
+ writeConfig(true);
+ const server = new MCPServer({ vault, configPath });
+ await initialize(server);
+
+ // Generate a few calls across two tools.
+ await callTool(server, "second_brain_status", {});
+ await callTool(server, "second_brain_query", {});
+ await callTool(server, "second_brain_query", {});
+
+ const summary = await callTool(server, "brain_route_metrics", { operation: "summary" });
+ // The summary call itself is emitted AFTER the handler returns, so it is
+ // not counted here; only the three prior calls plus none-yet for this one.
+ expect(summary["total"]).toBeGreaterThanOrEqual(3);
+ const routes = summary["routes"] as Array<Record<string, unknown>>;
+ expect(routes.length).toBeGreaterThanOrEqual(2);
+ for (const route of routes) {
+ expect(route).toHaveProperty("p95_ms");
+ expect(route).toHaveProperty("count");
+ }
+
+ const list = await callTool(server, "brain_route_metrics", {
+ operation: "list",
+ tool: "second_brain_query",
+ });
+ expect(list["total"]).toBe(2);
+ });
+
+ test("brain_route_metrics rejects an unknown operation", async () => {
+ writeConfig(true);
+ const server = new MCPServer({ vault, configPath });
+ await initialize(server);
+ const response = (await server.handleRequest({
+ jsonrpc: JSONRPC_VERSION,
+ id: 9,
+ method: "tools/call",
+ params: { name: "brain_route_metrics", arguments: { operation: "bogus" } },
+ })) as { result?: { isError?: boolean }; error?: unknown };
+ expect(response.error ?? response.result?.isError).toBeTruthy();
+ });
+});
diff --git a/tests/mcp/token-impact-tool.test.ts b/tests/mcp/token-impact-tool.test.ts
new file mode 100644
index 00000000..9bb2c8be
--- /dev/null
+++ b/tests/mcp/token-impact-tool.test.ts
@@ -0,0 +1,214 @@
+import { afterEach, beforeEach, describe, expect, test } from "bun:test";
+import { mkdirSync, mkdtempSync, rmSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+
+import { atomicWriteFileSync } from "../../src/core/fs-atomic.ts";
+import { listTokenImpact } from "../../src/core/brain/token-impact.ts";
+import { JSONRPC_VERSION, MCPServer, PROTOCOL_VERSION } from "../../src/mcp/index.ts";
+import { buildToolTable } from "../../src/mcp/tools.ts";
+
+let tmp: string;
+let vault: string;
+let configHome: string;
+let configPath: string;
+const savedEnv: Record<string, string | undefined> = {};
+
+function writeConfig(ledger: boolean): void {
+ atomicWriteFileSync(
+ configPath,
+ `vault: ${vault}\nagent_name: claude\ntoken_impact_ledger_enabled: "${ledger}"\n`,
+ );
+}
+
+beforeEach(() => {
+ tmp = mkdtempSync(join(tmpdir(), "o2b-token-impact-tool-"));
+ vault = join(tmp, "vault");
+ mkdirSync(join(vault, "Brain"), { recursive: true });
+ configHome = mkdtempSync(join(tmpdir(), "o2b-token-impact-tool-cfg-"));
+ configPath = join(configHome, "config.yaml");
+ for (const key of [
+ "VAULT_AGENT_NAME",
+ "VAULT_TIMEZONE",
+ "VAULT_DIR",
+ "OPEN_SECOND_BRAIN_CONFIG",
+ "OPEN_SECOND_BRAIN_TOKEN_IMPACT_LEDGER_ENABLED",
+ ]) {
+ savedEnv[key] = process.env[key];
+ delete process.env[key];
+ }
+ process.env["OPEN_SECOND_BRAIN_CONFIG"] = configPath;
+});
+
+afterEach(() => {
+ rmSync(tmp, { recursive: true, force: true });
+ rmSync(configHome, { recursive: true, force: true });
+ for (const [key, value] of Object.entries(savedEnv)) {
+ if (value === undefined) delete process.env[key];
+ else process.env[key] = value;
+ }
+});
+
+async function initialize(server: MCPServer): Promise<void> {
+ await server.handleRequest({
+ jsonrpc: JSONRPC_VERSION,
+ id: 1,
+ method: "initialize",
+ params: {
+ protocolVersion: PROTOCOL_VERSION,
+ capabilities: {},
+ clientInfo: { name: "token-impact-test", version: "0" },
+ },
+ });
+}
+
+async function callTool(
+ server: MCPServer,
+ name: string,
+ args: Record<string, unknown>,
+): Promise<Record<string, unknown>> {
+ const response = (await server.handleRequest({
+ jsonrpc: JSONRPC_VERSION,
+ id: 9,
+ method: "tools/call",
+ params: { name, arguments: args },
+ })) as { result: { content: ReadonlyArray<{ type: string; text: string }> } };
+ return JSON.parse(response.result.content[0]!.text);
+}
+
+describe("brain_token_impact registration", () => {
+ test("registered in the full tool table only", () => {
+ expect(buildToolTable("full").find((t) => t.name === "brain_token_impact")).toBeDefined();
+ expect(buildToolTable("writer").find((t) => t.name === "brain_token_impact")).toBeUndefined();
+ });
+});
+
+describe("brain_token_impact record gating", () => {
+ test("gate off records nothing but reports enabled:false", async () => {
+ writeConfig(false);
+ const server = new MCPServer({ vault, configPath });
+ await initialize(server);
+ const out = await callTool(server, "brain_token_impact", {
+ operation: "record",
+ baseline_tokens: 100,
+ packed_tokens: 40,
+ method: "exact",
+ });
+ expect(out["recorded"]).toBe(false);
+ expect(out["enabled"]).toBe(false);
+ expect(listTokenImpact(vault)).toHaveLength(0);
+ });
+
+ test("gate on records a tokenizer-exact delta", async () => {
+ writeConfig(true);
+ const server = new MCPServer({ vault, configPath });
+ await initialize(server);
+ const out = await callTool(server, "brain_token_impact", {
+ operation: "record",
+ baseline_tokens: 1000,
+ packed_tokens: 300,
+ method: "exact",
+ pack_id: "receipt_1",
+ });
+ expect(out["recorded"]).toBe(true);
+ expect(out["delta_tokens"]).toBe(700);
+ const records = listTokenImpact(vault);
+ expect(records).toHaveLength(1);
+ expect(records[0]!.payload["pack_id"]).toBe("receipt_1");
+ });
+
+ test("method defaults to fallback when omitted", async () => {
+ writeConfig(true);
+ const server = new MCPServer({ vault, configPath });
+ await initialize(server);
+ const out = await callTool(server, "brain_token_impact", {
+ operation: "record",
+ baseline_tokens: 10,
+ packed_tokens: 4,
+ });
+ expect(out["method"]).toBe("fallback");
+ });
+
+ test("rejects a missing count", async () => {
+ writeConfig(true);
+ const server = new MCPServer({ vault, configPath });
+ await initialize(server);
+ const response = (await server.handleRequest({
+ jsonrpc: JSONRPC_VERSION,
+ id: 9,
+ method: "tools/call",
+ params: {
+ name: "brain_token_impact",
+ arguments: { operation: "record", baseline_tokens: 1 },
+ },
+ })) as { result?: { isError?: boolean }; error?: unknown };
+ expect(response.error ?? response.result?.isError).toBeTruthy();
+ });
+});
+
+describe("brain_token_impact exact-vs-modeled summary + calibration", () => {
+ test("summary keeps exact and modeled separate; outcomes calibrate the model", async () => {
+ writeConfig(true);
+ const server = new MCPServer({ vault, configPath });
+ await initialize(server);
+
+ await callTool(server, "brain_token_impact", {
+ operation: "record",
+ baseline_tokens: 800,
+ packed_tokens: 200,
+ method: "exact",
+ modeled_avoided_inferences: 2,
+ modeled_tokens_per_inference: 1000,
+ });
+ // 3 first-pass, 1 retry -> first_pass_rate 0.75.
+ await callTool(server, "brain_token_impact", { operation: "outcome", outcome: "first_pass" });
+ await callTool(server, "brain_token_impact", { operation: "outcome", outcome: "first_pass" });
+ await callTool(server, "brain_token_impact", { operation: "outcome", outcome: "first_pass" });
+ await callTool(server, "brain_token_impact", { operation: "outcome", outcome: "retry" });
+
+ const summary = await callTool(server, "brain_token_impact", { operation: "summary" });
+ const delta = summary["prompt_token_delta"] as Record<string, unknown>;
+ expect(delta["net_savings_tokens"]).toBe(600);
+ const modeled = summary["modeled_inference_avoidance"] as Record<string, unknown>;
+ expect(modeled["raw_savings_tokens"]).toBe(2000);
+ expect(modeled["calibrated_savings_tokens"]).toBe(1500); // 2000 * 0.75
+ const cal = modeled["calibration"] as Record<string, unknown>;
+ expect(cal["first_pass_rate"]).toBe(0.75);
+ });
+
+ test("list and summary read even with the gate off", async () => {
+ // Write with the gate on...
+ writeConfig(true);
+ let server = new MCPServer({ vault, configPath });
+ await initialize(server);
+ await callTool(server, "brain_token_impact", {
+ operation: "record",
+ baseline_tokens: 50,
+ packed_tokens: 10,
+ method: "fallback",
+ });
+ // ...then flip the gate off and confirm reads still work.
+ writeConfig(false);
+ server = new MCPServer({ vault, configPath });
+ await initialize(server);
+ const list = await callTool(server, "brain_token_impact", { operation: "list" });
+ expect(list["total"]).toBe(1);
+ const summary = await callTool(server, "brain_token_impact", { operation: "summary" });
+ expect((summary["prompt_token_delta"] as Record<string, unknown>)["net_savings_tokens"]).toBe(
+ 40,
+ );
+ });
+
+ test("rejects an unknown operation", async () => {
+ writeConfig(true);
+ const server = new MCPServer({ vault, configPath });
+ await initialize(server);
+ const response = (await server.handleRequest({
+ jsonrpc: JSONRPC_VERSION,
+ id: 9,
+ method: "tools/call",
+ params: { name: "brain_token_impact", arguments: { operation: "bogus" } },
+ })) as { result?: { isError?: boolean }; error?: unknown };
+ expect(response.error ?? response.result?.isError).toBeTruthy();
+ });
+});