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.jsonindex 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.jsonindex 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.mdindex 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-06A hardening and correctness pass over the PR #121 refactor. Thirteen fixesdiff --git a/README.md b/README.mdindex 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.## Whydiff --git a/docs/brainstorm/context-pack-economics-observability/cli-output/claude.md b/docs/brainstorm/context-pack-economics-observability/cli-output/claude.mdnew file mode 100644index 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.mdnew file mode 100644index 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.mdnew file mode 100644index 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.mdnew file mode 100644index 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.mdnew file mode 100644index 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.mdindex 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 thecontinuity schema version - lives in `docs/observability.md`.diff --git a/docs/observability.md b/docs/observability.mdindex 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.jsonindex 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.jsonindex 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.yamlindex 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: truediff --git a/plugins/codex/.codex-plugin/plugin.json b/plugins/codex/.codex-plugin/plugin.jsonindex 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.yamlindex 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: truediff --git a/pyproject.toml b/pyproject.tomlindex 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.tsnew file mode 100644index 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.tsindex 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.tsnew file mode 100644index 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.tsnew file mode 100644index 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.tsindex 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): ContextPacconst 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): ContextPactrimmed,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.tsindex 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.tsindex 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}, anddiff --git a/src/core/brain/mcp-route-metrics.ts b/src/core/brain/mcp-route-metrics.tsnew file mode 100644index 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.tsnew file mode 100644index 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.tsindex 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 thediff --git a/src/mcp/brain/pack-tools.ts b/src/mcp/brain/pack-tools.tsindex 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.tsindex 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 | undereturn 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.tsindex 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.tsnew file mode 100644index 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.tsnew file mode 100644index 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.tsnew file mode 100644index 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.tsindex 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.tsnew file mode 100644index 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.tsnew file mode 100644index 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.tsindex 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.tsnew file mode 100644index 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.tsindex 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.tsindex 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.tsindex 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.tsnew file mode 100644index 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.tsnew file mode 100644index 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();+ });+});