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: recall quality - an iterative recall loop, coverage-first session recall and a measured surfacing key (v1.82.0) (#250)
Serg Eroshe44a8ccaf3b71
diff --git a/.claude-plugin/plugin.json b/.claude-plugin/plugin.jsonindex 954cc0e4..3d1cca1d 100644--- a/.claude-plugin/plugin.json+++ b/.claude-plugin/plugin.json@@ -1,6 +1,6 @@{"name": "open-second-brain",- "version": "1.81.1",+ "version": "1.82.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 21db4ecc..22003f3f 100644--- a/.codex-plugin/plugin.json+++ b/.codex-plugin/plugin.json@@ -1,6 +1,6 @@{"name": "open-second-brain",- "version": "1.81.1",+ "version": "1.82.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/CHANGELOG.md b/CHANGELOG.mdindex 5d69359a..cc640bb5 100644--- a/CHANGELOG.md+++ b/CHANGELOG.md@@ -5,6 +5,28 @@ 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.82.0] - 2026-10-12++Open Second Brain 1.82.0 is the recall-quality release: it widens what recall can reach on a hard question and makes every surfacing decision measurable. A bounded iterative recall loop keeps querying after the single self-correcting second pass and, when coverage gaps survive, pauses mid-answer with a plan the caller executes and commits back; session recall gains a coverage-first selection that answers for a whole thread instead of a keyword's hits; recall admission moves onto one shared graded surfacing key that the recall-inject hook and the recall gate grade identically; and the bench grows the harness to score all of it - a suite registry, a LongMemEval lane with a strict recall_all@5 receipt, and a surfacing-replay suite that measures the graded gate itself. The default posture of every surface is byte-identity: with the knobs off, every response and every query-cache key is exactly what it was.++### Added++- **A bounded iterative recall loop behind `brain_search`'s plan/commit round-trip.** With the operator knob `search_iterative_recall_enabled` on (`OPEN_SECOND_BRAIN_SEARCH_ITERATIVE`; the round cap `search_iterative_recall_max_rounds` / `OPEN_SECOND_BRAIN_SEARCH_ITERATIVE_MAX_ROUNDS` defaults to 2 and clamps to 8), a query marked `iterative: true` runs gap-driven rounds past the single second pass: each round re-measures pool coverage, emits follow-up sub-queries from the uncovered rare-term groups, and merges what they recover into the same ranked pool, stopping on coverage completeness, a round that recovers nothing, the marginal-value stop extracted from the retrieval advisor, the round cap or the composite deadline. The deterministic k-group coverage planner is the always-available floor - the mode is useful with no model in the loop - and the decider rounds are additive: when measurable gaps survive the deterministic budget, the call pauses with an `iterative` marker at `phase: "needs-llm-step"` carrying the decider envelope, the candidate pool ids, the uncovered gaps and an opaque single-use round token, and the caller re-invokes with `iterative_token` plus `iterative_payload` (`{evidence, subQueries}`), validated in full before any pull runs - unknown chunk ids, oversized or over-limit sub-queries, sub-queries carrying no significant terms, a replayed token (`token_used`), a mismatched one (`token_mismatch`) and a fully-formed commit arriving while the loop is disabled are typed refusals surfaced as caller errors. The round-trip runs on the single-vault path only: any `iterative` field combined with `global: true` is refused by name at the argument layer, so no iterative field ever reaches the federated legs. Every loop that ran at least one round - a committed call, or a plain final - answers with the same marker at `phase: "final"`, carrying the per-round records (terms, groups, added, elapsed, and whether the deterministic floor or the decider authored the sub-queries) and the `stop_reason` (`coverage_complete`, `no_sub_query`, `no_progress`, `round_cap`, `marginal_value`, `deadline`, `decider_round`); with the knob off, and on any call the mode did nothing for, the response and the query-cache keys are byte-identical, because the cache suffix that separates iterative rows exists only in the opt-in mode.+- **Coverage-first session recall on `brain_session_grep`, with CLI parity.** `operation: "coverage"` replaces the grep's term matching with thread coverage over the same lineage-scoped record set: facets are the thread's own - distinct mined entity keys and depth-1 summary clusters, never a word list - and fan out under the adaptive topic budget `clamp(distinct facets, floor 12, cap 16)`, the selection returns in chronological order under the required `char_budget` beside recomputable diagnostics that report the realized topic count honestly, and `entity_key` optionally seeds the fan-out from the `session_entity_mention` rows an import already mined - no new mining, no new record kind - with an entity no record mentions refused by name instead of answered with an empty result. The operations keep their arguments to themselves: `char_budget` under `match`, and `query`, `since`, `before`, `limit`, `snippet_chars`, `include_raw` and `raw_budget_chars` under `coverage`, are each refused as not applicable. A budget that cannot hold the floor-weighted selection is a typed infeasibility mapped to `INVALID_PARAMS`, naming the requested topics, the kept ones and the required characters - a retry bound, never a silent truncation, with the floor enforced again after the real budget pass so a crowded-out floor topic cannot slip through the pre-check. `brain_session_describe` accepts `topics: true`, adding the `topic_report` the coverage operation fans out under (detected facets, the budget, the realized topics); without it the response is byte-identical. The CLI mirrors both surfaces: `o2b brain session-grep --operation coverage --char-budget <n> [--entity-key <key>]` and `o2b brain session-describe --topics`, with the same refusals.+- **A bench suite registry, with LongMemEval and surfacing-replay suites.** `o2b brain bench memory --suite <name>` resolves through a registry mapping each suite name to its loader plus a declared capability set (`{embeddings: boolean}`), so what a suite may do is explicit in code rather than flag-implied; omitting `--suite` stays the byte-identical default path. `--suite longmemeval` adds the benchmark the memory field reports recall_all@5 on: a fail-fast parser over the official dataset shape with named parse errors, a converter into the unchanged bench fixture that drops abstention questions at conversion with the count recorded and joins gold sessions by direct id membership (an unknown id is a named parse error, and `expected_text` is never set, so nothing silently scores nothing), a committed sample fixture certifying CI with the full dataset an operator-supplied path that is never downloaded at run time, and the strict named report family `longmemeval: {recall_all_at_5, abstention_excluded}` beside the untouched quality, latency and context_cost families. The judge glue reuses `bench_judge_cmd`: when the suite provides them, the stdin payload's questions carry `question`, `answer`, `gold` and the evidence the run actually injected (path plus a bounded excerpt per retrieved note, in rank order) beside the usual result fields, and the judge prompts are house-written in the spirit of upstream's `evaluate_qa.py` rather than transcribed from it, so the external command stays a dumb model call; suites without judge input keep the payload byte for byte. Embeddings are a per-suite capability: the semantic lane is reachable only for a suite that declared it, the index builds through the apply-gated embedding path with the spend plan surfaced and never silently bypassed, a shared vector cache under the runs dir keyed by provider, model, dimension, prefixes and text hash lets both arms compare byte-identical vectors, and `--pin <json>` plus `--recall-floor <n>` expose pinning and the admission floor from the CLI. `--suite surfacing-replay` replays a recorded prompt corpus - a committed session fixture in the replay shape, carrying each prompt's recorded predecessor for the structural gate - through the shipped decision core and scores the graded surfacing gate's know_to_ask and false_fire rates under the same denominations the proactive-recall metric uses, with per-turn `injected_tokens`, checkpoint and resume, and the abstain-costs-zero invariant asserted: the calibration becomes a measured number a re-run re-measures.+- **Bench runs carry their configuration in the run identity.** A `SearchConfigOverrides`-shaped knob pin applies last through `resolveSearchConfig` and folds into the checkpoint hash beside the fixture hash and the proactive-recall admission floor, so a resumed run that would mix configurations fails the identity guard by name instead of silently comparing two pipelines, and two runs with different pins get different run ids. The default pin is the semantic-off override the harness always applied, so locomo report numbers stay identical; the one-time consequence is that in-flight runs started before this change fail the resume guard loudly and restart.++### Changed++- **Recall admission is one graded, channel-aware key.** The recall gate's binary prompt-structural predicate stays the structural pre-tier with its named short-circuits (empty prompt, verbatim repeat, slash command, shell command) and keeps projecting the binary `{retrieve, reason}` contract unchanged; admission now rides one shared calculator that grades absolute match quality - the IDF-weighted coverage a search outcome already reports, the quantity recall-adequacy grades - calibrated per transport channel, and orders by the existing fused composite, which is never a threshold basis. `brain_recall_gate` and the recall-inject hook's floor branches consume the same `{key, tier, admit, reason}` decision, so a tier boundary surfaces the same reason on every channel, and a measured `brain_recall_gate` call returns `key` and `tier` beside the binary decision, absent - byte-identical - without a measurement. Per-channel admission floors ship as exported module constants at the hook's 0.35, the hook's `RECALL_INJECT_CONFIDENCE_FLOOR` now derived from that single source, with no new config knobs. Gate telemetry under the existing `recall_gate_telemetry` opt-in records optional `key`, `tier` and `channel` on measured decisions and summarizes counts by tier; the opt-in-off path records nothing, and no new record kind exists.+- **Docs:** `docs/mcp.md` documents the iterative round-trip, the coverage operation with its argument partition, the graded surfacing key on `brain_recall_gate` and the widened gate telemetry; `docs/cli-reference.md` documents the coverage flags with their CLI parity, the iterative-recall and graded-key sections, and the bench suites with the run identity; `docs/observability.md` covers the gate-telemetry key, tier and channel fields and the suite registry; the README names the release and extends the search and session-recall capabilities.++### Fixed++- **The iterative loop answers to the reach rule everywhere.** The round records counted raw pull hits, so at non-local reach a probing caller could read recovery counts for terms only withheld pages match - the same boundary the pause pool already honors; the reach filter now governs the loop's working set, so withheld candidates never enter the pool, the round accounting or the coverage gaps. An expired composite deadline at block entry also skipped the commit refusal, handing the caller a plain answer and an unspent token with no error; the commit is refused by name like every other half-executable commit, and the round token is claimed atomically so two racing commits cannot both spend it.+- **Coverage selection refuses honestly instead of silently degrading.** The private-row rule the entity-seed resolver applies now covers the coverage facets too, so a private mention can no longer seed a facet whose key surfaces in the diagnostics or the topic report; the entity seed and its typed unknown-entity refusal reach both shipped surfaces (they were core-API only); and the echoed entity key is capped at the sibling argument bound.+- **The bench refuses the identities it cannot honor.** A run id of dots passed the charset check and resolved into the runs-dir root, writing the checkpoint and vault beside the shared vector cache, and is refused by name; distinct LongMemEval session ids that sanitize to one evidence note are a named parse error instead of silently merging both sessions' evidence; and the embedding cost gate prices the misses census, so a second arm the shared cache serves whole is no longer refused under a positive gate against the zero-provider-contact purpose the cache exists for.+## [1.81.1] - 2026-10-12### Fixed@@ -3252,7 +3274,7 @@ storage model stays vault-first Markdown and JSONL.### Added- **Native Grok Build (xAI `grok`) integration.** `o2b install --target grok---apply` registers the two Open Second Brain MCP servers in+ --apply` registers the two Open Second Brain MCP servers in`${GROK_HOME:-~/.grok}/config.toml` under `[mcp_servers.*]` (grok'shighest-priority MCP source) and writes lifecycle hooks to`${GROK_HOME:-~/.grok}/hooks/open-second-brain.json` (grok's native hooks@@ -3322,7 +3344,7 @@ logging reminder.- **Bundled opencode plugin** (`plugins/opencode/open-second-brain.ts`):a single zero-dependency file installed into`~/.config/opencode/plugins/` by `o2b install --target opencode---apply`. On each chat request it appends the rendered+ --apply`. On each chat request it appends the rendered`Brain/active.md` digest to the system prompt (via the same`o2b-hook active-inject` shim the Claude Code and Codex hook layersuse, cached with a 5 minute TTL); on `session.idle` /@@ -3383,7 +3405,7 @@ logging reminder.finding ids through existing primitives (preference merge, claimappend, targeted recompile, archive-never-delete) with an auditrecord per run. New `brain_hygiene` MCP tool and `o2b brain hygiene-scan|apply` verbs.+ scan|apply` verbs.- **Advisory conflict resolution** through the shared external-commandbridge: when the operator configures `hygiene.resolver_cmd`, contestedtruth slots get supersede / merge / flag verdicts with recorded@@ -3416,7 +3438,7 @@ scan|apply` verbs.The adapter now merges the two Open Second Brain servers into`~/.config/opencode/opencode.json` under the `mcp` key usingopencode's entry schema (`{type: "local", command: [bin, ...args],-environment, enabled: true}`), honouring `XDG_CONFIG_HOME`. Apply+ environment, enabled: true}`), honouring `XDG_CONFIG_HOME`. Applyalso migrates the stale `~/.config/opencode/mcp.json` written byearlier releases: the two Open Second Brain keys are removed, and thefile is deleted when nothing else remains.@@ -3596,7 +3618,7 @@ break with a migration table in `docs/updating.md`.advertised list and the callable surface are the same set. Callinga removed name answers an INVALID_PARAMS tombstone naming thereplacement (`brain_digest was removed in 1.0.0; call brain_brief-with view="digest"`). Full table in `docs/updating.md`.+ with view="digest"`). Full table in `docs/updating.md`.### Added@@ -3616,7 +3638,7 @@ with view="digest"`). Full table in `docs/updating.md`.task results classify `timed_out`; persisted error strings cap at4096 bytes with an explicit marker.- **Staged dream pipeline.** `o2b brain dream stage | validate-<run-id> | apply <run-id> | discard <run-id> | list` (MCP+ <run-id> | apply <run-id> | discard <run-id> | list` (MCP`brain_dream` gains an `action` parameter - no new tools). Stagepersists a reviewable bundle under `Brain/dream/staged/<run-id>/`(manifest with schema `o2b.dream-stage.v1`, human REPORT.md,@@ -3894,10 +3916,10 @@ MCP tool count grows 66 -> 69.independent sources materialize a `value_conflict` with`resolution: ask_user` - never auto-resolved - while a later valueoutside the window supersedes silently. `o2b brain truth-ingest|slots|conflicts|aggregate|collisions|sweep` and the+ ingest|slots|conflicts|aggregate|collisions|sweep` and the`brain_truth` MCP tool are the operator surface.- **Atomic-fact decomposition and the quantity family**. `o2b brain-facts decompose` deterministically splits session text into discrete+ facts decompose` deterministically splits session text into discreteassertions via markdown structure (heading paths, list items,sentence boundaries with an abbreviation guard) anchored tocanonical entities - no model calls; `--ingest` bridges@@ -3978,7 +4000,7 @@ ranks bit-identically. MCP tool count is unchanged (66).and antipatterns never decay, projects ~120d, handoffs/sessions~30d, notes 60d. Reinforcement is miss-driven: a query-cache hitreturns early and records nothing. `o2b brain activation-status|sweep` inspects and compacts the event store+ status|sweep` inspects and compacts the event store(`search_activation_enabled` is the kill switch).- **Co-access reinforcement edges**. Documents habitually surfacedtogether gain pairwise counts in the same fold; when one appears in@@ -4005,7 +4027,7 @@ status|sweep` inspects and compacts the event storezero-candidate first pass (implicit-AND too strict) triggers exactlyone broadened OR retry; recovered results carry a `second_pass`reason and the envelope reports `secondPass: {triggered, reason,-added}` (`search_two_pass_enabled` is the kill switch).+ added}` (`search_two_pass_enabled` is the kill switch).### Changed@@ -4096,8 +4118,8 @@ stays at 65 tools.caller-supplied sha against the full-40-hex grammar before it canreach git.- **Git history query** (`o2b brain git find [text] [--file F]-[--author A] [--since/--until] [--repo K]`, `o2b brain git-status`). Answers "why and when did this file change" and "which+ [--author A] [--since/--until] [--repo K]`, `o2b brain git+ status`). Answers "why and when did this file change" and "whichrelease carried it" purely from the store - no live git on thequery path, so the answers survive checkout deletion. Adeterministic per-repo digest note (releases, recent commits, hot@@ -4116,7 +4138,7 @@ status`). Answers "why and when did this file change" and "whichnew regions, and fails closed (no partial rewrite) on unbalanced,duplicate, nested, or mismatched sentinels.- **Architecture docs generator** (`o2b brain architect-<project-path>`). A deterministic stdlib-only scanner (module+ <project-path>`). A deterministic stdlib-only scanner (modulelayout, language mix, entry points, manifest, test layout - no LLM,no network) renders an overview plus per-module notes under`Brain/projects/arch/<repo-key>/` through the region engine:@@ -4157,7 +4179,7 @@ stays default-off.test). Evolution rule documented: additive fields never bump theversion, renames/removals/semantic changes do.- **Lazy gated telemetry emit kernel.** One `emitGatedTelemetry(gate,-build)` helper now carries every gated telemetry surface+ build)` helper now carries every gated telemetry surface(context-pack receipts and telemetry, pre-compress, `brain_search`telemetry, recall-gate telemetry): with the gate off the payloadthunk is never invoked and nothing reaches the continuity store; a@@ -4172,14 +4194,14 @@ build)` helper now carries every gated telemetry surfaceun-masks redacted text - the single normalization layer everyread-side consumer shares.- **ATOF/ATIF trajectory export.** `o2b brain continuity export---format atof|atif [--session <id>] [--month YYYY-MM]` renders the+ --format atof|atif [--session <id>] [--month YYYY-MM]` renders thestore as standard trajectory formats: ATOF JSONL events (recalltelemetry as `retriever` scope pairs with a marked synthetic start,other kinds as marks) and ATIF v1.7 documents (one per session,memory-layer events as `llm_call_count: 0` system steps). Read-onlyover the read-model; private records never reach an export file.- **Memory quality benchmark.** `o2b brain bench memory --fixture-<name|path>` ingests a fixture into a disposable vault inside the+ <name|path>` ingests a fixture into a disposable vault inside theruns directory (never the configured vault), indexes, retrieves,evaluates, and reports - quality (pass rate per category), latency,and context cost as separate families, never one collapsed score.@@ -4221,7 +4243,7 @@ behaviour-changing pieces are off by default or per-call explicit.beside the config; malformed pointers and dangling targets fail softand are reported, never thrown.- **Read-only recall sources.** `o2b brain source add <vault> --alias-<name>` attaches an external vault as a read-only recall origin of+ <name>` attaches an external vault as a read-only recall origin ofthe active Brain. The registry is keyed by owning vault (switchingprofiles never leaks sources), validation concentrates in one place(alias and path uniqueness, self-links, direct circular links), and@@ -4239,25 +4261,25 @@ behaviour-changing pieces are off by default or per-call explicit.key selects `preserve` (default, byte-identical), `full`(vault-relative key path), or `short` (shortest unambiguous suffix)for generated and normalized links. `o2b brain links normalize-[path] [--mode M] [--write]` rewrites wikilinks across Brain notes -+ [path] [--mode M] [--write]` rewrites wikilinks across Brain notes -dry-run by default, decorations and code blocks preserved verbatim,ambiguous and unknown targets left as typed and reported.- **Shell-native Brain surface.** `o2b brain profile` materializes acompact `Brain/profile.md` digest (facts, top preferences, recentactivity; age-gated regeneration) plus a `.o2bfs` root marker soshell wrappers can detect a Brain root safely. `o2b brain sgrep-<query> [path]` is a grep-shaped semantic search - `path:line:`+ <query> [path]` is a grep-shaped semantic search - `path:line:`output lines, path scoping, `--json`, exit 1 on no matches - with noMCP and no OSB-specific knowledge required.- **Grounded trigger queue with anti-nag lifecycle.** `o2b brain-trigger scan` turns existing semantic-health and retention findings+ trigger scan` turns existing semantic-health and retention findingsinto Markdown trigger records under `Brain/triggers/` (urgency,reason, suggested action, source artifacts, context snippets).Stable cooldown keys make repeated scans idempotent: an open twinblocks recreation, a dismissed/acted twin blocks for`trigger_cooldown_days` (default 7), an expired twin allows.Lifecycle is a strict machine (`pending → delivered → acknowledged →-acted`, dismiss from any open state) over `list`, `ack`, `dismiss`,+ acted`, dismiss from any open state) over `list`, `ack`, `dismiss`,`act`, and `history` verbs plus one consolidated `brain_trigger` MCPtool. The morning brief surfaces capped pending triggers and marksthem delivered, so the same prompt shows at most once per cooldown@@ -4332,7 +4354,7 @@ behaviour-changing pieces are off by default.Absent captures every role; an explicit flag wins; an unknown rolefails fast.- **Session-scoped search focus.** `o2b search focus set|status|clear---session <id>` binds a focus to one session's file under+ --session <id>` binds a focus to one session's file under`search-focus/` beside the global file; a bound session focus winsover the global one, `brain_search` gains an optional`focus_session` input, and SessionEnd lifecycle capture auto-clears@@ -4340,13 +4362,13 @@ behaviour-changing pieces are off by default.(default off), `brain_context_pack` promotes focus-matching memorieswithin their tier.- **Operator-readable handoff notes.** `o2b brain handoff-<session-file>` (and, when `session_handoff` is true, SessionEnd+ <session-file>` (and, when `session_handoff` is true, SessionEndlifecycle capture) writes `Brain/handoffs/<date>-<scope>.md` withrequest, completed work, changed files, learned context, and nextsteps - extracted by deterministic regex from the recorded turns, noLLM.- **Scoped current-intention chains.** `o2b brain intention-set|show|list|move` (and the consolidated `brain_intention` MCP+ set|show|list|move` (and the consolidated `brain_intention` MCPtool) maintain per-workstream now-documents at`Brain/intentions/<scope>.md`: every update bumps `version` andappends the superseded text to an in-file history trail; `move`@@ -4375,7 +4397,7 @@ off-by-default where they could change behaviour.semantic depth.- **CLI provider registry.** Register OpenAI-compatible embeddingendpoints at runtime with `o2b search provider add | list | show |-remove`, persisted to `Brain/search/embedding-providers.json` (base+ remove`, persisted to `Brain/search/embedding-providers.json` (baseURL, default model, and the NAME of the environment variable holdingthe key - never the key itself, so the file is safe to sync). Aregistered name resolves to `openai-compat` config during config@@ -4417,7 +4439,7 @@ anchors.`category`, `name`, `aliases`, `status`, lifecycle stamps). The identityindex rebuilds from the Markdown files on every read - nothing to persist,nothing to sync-conflict. `o2b brain entity set | get | list | relate |-archive` drives the registry from the CLI (upsert resolves names AND+ archive` drives the registry from the CLI (upsert resolves names ANDaliases before creating anything and refuses duplicate claims; archiveremoves from active lookup, `--restore` returns); the read-only`brain_entity` MCP tool (`view: get | list`) serves lookups to agents.@@ -4578,7 +4600,7 @@ path.`OPEN_SECOND_BRAIN_SEARCH_RELATION_POLARITY` (default on; vaults withouttyped relations rank identically either way).- **Retrieval feedback loop with learned recall weights.** `o2b search-feedback --query <q> --result <path> --verdict up|down` and the new MCP+ feedback --query <q> --result <path> --verdict up|down` and the new MCPtool `brain_recall_feedback` record one JSON event per feedback under`Brain/search/feedback/` (the conflict-free one-file-per-signal pattern).A deterministic, order-insensitive fold derives per-layer multipliers@@ -5056,13 +5078,13 @@ install stays byte-identical.routed through the resolver. Inspect with `o2b vault map`.- Named multi-vault profiles (`portability/profiles.ts`). A registry in`profiles.json` beside the config with `o2b vault profile list / create-/ switch` and a `brain_switch_vault` MCP tool; activation is a pointer+ / switch` and a `brain_switch_vault` MCP tool; activation is a pointer(no symlinks). `resolveVault` consults the active profile before thebare config `vault` key; with no registry, resolution is unchanged.- Vault graph export/import (`portability/graph.ts`). `o2b brain-graph-export` serialises the user's pages (wikilinks + typed relations)+ graph-export` serialises the user's pages (wikilinks + typed relations)to a stable, byte-identical `graph.json`; `o2b brain graph-import---mode skip|overwrite|merge` reconstructs page stubs, every write+ --mode skip|overwrite|merge` reconstructs page stubs, every writeguarded by `ensureInsideVault`.### Notes@@ -5381,7 +5403,7 @@ under the stricter workflow. No runtime behaviour changes.- `oxlint.json` and `.oxfmtrc.json` configs, plus `lint`, `lint:fix`,`fmt`, `fmt:check`, `validate`, and `validate:fix` package scripts.`bun run validate` is the main verification command; `bun run-validate:fix` is the single autofix path for lint and formatting.+ validate:fix` is the single autofix path for lint and formatting.- `scripts/test` wrapper so `bun test` runs through the shared bun andsqlite prechecks.- `tests/cli/coerce.test.ts`, `tests/core/validate.test.ts`, and@@ -5566,7 +5588,7 @@ weak signal when the operator opts in via config.`would_promote`, `would_retire`, `would_supersede`,`clusters_below_threshold`, `gated_retires`. No state mutates.- Path helpers `dreamRunsDir(vault)` and `dreamWorkrunPath(vault,-runId)` in `src/core/brain/paths.ts`.+ runId)` in `src/core/brain/paths.ts`.### Changed@@ -5719,7 +5741,7 @@ agent assembles into prose externally.- `src/core/brain/temporal/belief-evolution.ts` -`buildBeliefEvolution(index, vault, target)` for `prefId` or`topic`. Returns frozen `{target, transitions, evidence,-retirements, generatedAt}`. Transitions derived from dream+ retirements, generatedAt}`. Transitions derived from dreamsummary arrays (`new_unconfirmed` / `confirmed` / `retired`);evidence rollup carries per-row running counts; retirement chainwalked via `supersedes` / `superseded_by` with a visited-set@@ -5741,7 +5763,7 @@ retirements, generatedAt}`. Transitions derived from dreamwindow ending at `weekEnd`. Same counters as daily plus`retired-in-window` list and `contradictions` (`signal-suppressed`events combined with `apply-evidence` rows where `result ===-"violated"`).+ "violated"`).- `src/core/brain/temporal/period-common.ts` - shared helpersconsumed by both briefs: `countByKind`, `collectTransitions`,`computeVaultDelta`, `collectSourcePointers`, `extractId`. One@@ -5951,7 +5973,7 @@ dream, and vault metadata into a single operator dashboard.Surfaces as a quality gate at `brain_feedback` time.- `src/core/brain/trust/self-approval-guardrail.ts` -`applySelfApprovalGuardrail({signal_count, distinct_agents,-age_days}, config)`. Promotes only when all three thresholds+ age_days}, config)`. Promotes only when all three thresholdspass; quarantines otherwise. Defaults(`promotion_min_signals: 2`, `promotion_min_distinct_agents: 1`,`promotion_min_age_days: 0`) keep pre-v0.10.16 dream behaviour@@ -5967,7 +5989,7 @@ age_days}, config)`. Promotes only when all three thresholds`AGENTS.md`, `GEMINI.md`) exceeds the configured ceiling.- `src/core/brain/trust/compute-trust-verdict.ts` -`computeTrustVerdict({ doctorWarnings, doctorErrors,-dreamWarnings, verification, driftWatchThreshold? })`. Returns+ dreamWarnings, verification, driftWatchThreshold? })`. Returnsone of `clean`, `watch`, `investigate`.- `src/core/brain/trust/operator-summary.ts` -`buildOperatorSummary(vault, opts)` and@@ -5980,18 +6002,18 @@ dreamWarnings, verification, driftWatchThreshold? })`. Returns`guardrails:` block in `_brain.yaml` overrides any subset.- `DreamRunSummary.uncertain: ReadonlyArray<DreamUncertainEntry>`and `DreamRunSummary.quarantined:-ReadonlyArray<DreamQuarantinedEntry>` (empty on every clean run).+ ReadonlyArray<DreamQuarantinedEntry>` (empty on every clean run).- `RunDoctorResult.trust_verdict` (always populated),`RunDoctorResult.verification_delta_summary` (present when adream summary is threaded through), `RunDoctorResult.-instruction_file_warnings`, and `RunDoctorResult.uncertain`.+ instruction_file_warnings`, and `RunDoctorResult.uncertain`.- `DigestJson.trust_verdict?`, `DigestJson.uncertain_count`,`DigestJson.quarantined_count`. Markdown digest gains a `##-Trust` section when doctor or dream input is supplied.+ Trust` section when doctor or dream input is supplied.- `brain_operator_summary` MCP tool in the full scope. Returnsthe structured envelope from `buildOperatorSummary`.- `o2b brain summary [--skip-dream] [--top-actions <n>]-[--vault <path>] [--json]` CLI verb. Markdown by default, JSON+ [--vault <path>] [--json]` CLI verb. Markdown by default, JSONon demand.- `BrainRolePermissionError` thrown by`appendApplyEvidence(vault, input, { role })` when the role is@@ -6290,7 +6312,7 @@ Companion design and impl plan at- `o2b mcp --probe` flag — in-process MCP handshake used by`o2b install --check` to confirm the server starts cleanly.- `_brain.yaml` block `active.{most_applied_window_days,-most_applied_limit}` (defaults 30 / 10; bounds 1..365 / 1..50).+ most_applied_limit}` (defaults 30 / 10; bounds 1..365 / 1..50).Both `Brain/active.md` and `brain_digest` honour the values;defaults unchanged from prior behaviour.- `Most-applied (Nd)` section in `brain_digest` Markdown plus a@@ -6607,8 +6629,8 @@ tracks ship together under one release.do not collide). No LLM in the report path.- §30 §E - Claude Code MEMORY to Brain bridge. New verb`o2b brain import-claude-memory [--memory <path>]-[--dry-run | --apply] [--yes] [--json]-[--allow-arbitrary-memory-path]` reads `metadata.type: feedback`+ [--dry-run | --apply] [--yes] [--json]+ [--allow-arbitrary-memory-path]` reads `metadata.type: feedback`entries from a Claude Code memory directory and writes them asconfirmed Brain preferences with a sidecar manifest`Brain/.imports/claude-memory.json` for idempotency.@@ -6679,7 +6701,7 @@ sidecar that powers drift detection.### Added- §22 — `o2b brain upgrade [--dry-run] [--apply] [--yes] [--check]-[--json]` migrates the three release-owned files+ [--json]` migrates the three release-owned files(`Brain/_brain.yaml`, `Brain/_BRAIN.md`,`AI Wiki/_OPEN_SECOND_BRAIN.md`) forward when the installedopen-second-brain version changes them. `_brain.yaml` merge is@@ -6699,7 +6721,7 @@ sidecar that powers drift detection.warning. `pruneSnapshots` removes the sidecar alongside thearchive; `listSnapshots` surfaces `manifest_path`.- §28 — `o2b brain export --format json|llms-txt [--out <path>]-[--force]` produces a read-only dump of active preferences+ [--force]` produces a read-only dump of active preferences(`confirmed | unconfirmed | quarantine`) from`Brain/preferences/`. Retired and signal artifacts are notincluded. Default sink is stdout; `--out` writes a file@@ -6740,7 +6762,7 @@ sidecar that powers drift detection.- §30 §C — `skills/brain-memory/SKILL.md` description and "When NOTto call" section reformulate the trigger: when a preferenceplausibly applies but you are unsure, record with `note:-"speculative; <reason>"` instead of skipping. The dream pass+ "speculative; <reason>"` instead of skipping. The dream passfilters single-event speculative entries that do not recur, socoverage costs less than missing the signal.`hooks/lib/messages.ts:postWriteReminder` mirrors the new wording.@@ -6814,7 +6836,7 @@ runs `o2b brain merge`.- §14 — `o2b brain explorer` launches a loopback HTTP server (defaultport `7777`, `--port <n>` to override) that renders preferences andretired entries as a force-directed graph. `o2b brain explorer---export <path>` writes the same view as a single offline HTML file+ --export <path>` writes the same view as a single offline HTML filewith inlined data; `--force` overwrites an existing file. Live andexport modes share one template at `templates/brain-explorer.html`.Zero backend, no LLM, no network. Markdown is parsed in the browser@@ -6824,7 +6846,7 @@ runs `o2b brain merge`.whose `principle` tokens reach jaccard ≥ `0.6`. Pairs ≥ doctor'sown duplicate threshold continue to trip the`duplicate-preferences` doctor lint. `o2b brain merge <keep>-<drop>` is the explicit resolver: `keep` retains its frontmatter,+ <drop>` is the explicit resolver: `keep` retains its frontmatter,picks up the deduped union of `evidenced_by`, the summed`applied_count` and `violated_count`, and `max(last_evidence_at)`;`drop` retires under reason `merged-into` with a `superseded_by`@@ -6841,7 +6863,7 @@ runs `o2b brain merge`.`session_id`/`cwd`/`tool_use_id` triple). `stopGuardrailReason`follows the same pattern.- §15 (completes deferred D4 from v0.10.4) — `skills/brain-memory/-SKILL.md` gains an `## Examples — good vs bad` section: four+ SKILL.md` gains an `## Examples — good vs bad` section: fourcontrastive pairs covering weak vs strong `principle`,too-general vs precise `topic`, and `note` with versus withoutthe "why" line.@@ -6990,7 +7012,7 @@ without an explicit declaration keep their current behaviour.- **`_brain.yaml.confidence.medium_min` (default 0.40) and`high_min` (default 0.75)** — derived-band thresholds on thenumeric value. Validated to lie in `[0, 1]` with `medium_min <-high_min`.+ high_min`.- **`Brain/_brain.yaml.primary_agent`** declarative field. When set,dream runs invoked from a different agent emit a stderr warning,a `warnings` array entry on the MCP `brain_dream` response, and a@@ -7002,7 +7024,7 @@ high_min`.during the fresh bootstrap; on re-runs the flag is a no-op (use`set-primary` instead).- **`src/core/brain/set-primary.ts`** — `setPrimaryAgent(vault,-name | null): SetPrimaryAgentResult`. Validates the rewritten+ name | null): SetPrimaryAgentResult`. Validates the rewrittenYAML before persisting; surfaces a typed `BrainConfigError` whenthe on-disk file is malformed.- **`renderPrefLink({ id, principle })`** in `src/core/brain/wikilink.ts`@@ -7037,7 +7059,7 @@ name | null): SetPrimaryAgentResult`. Validates the rewritten- **`brain_query` MCP response** carries `confidence_value` next to`confidence` on every preference and retired result row.- **`brain_dream` MCP response** carries a `warnings: [{code,-message}]` array. CLI `o2b brain dream` writes the same warnings+ message}]` array. CLI `o2b brain dream` writes the same warningsto `stderr`.- **`brain_dream` MCP schema** accepts an optional `agent` argumentfor the primary-agent check.@@ -7242,7 +7264,7 @@ in place.every preference and retired file. Dream collects the last 5applied + last 3 violated rows from `Brain/log/` on every pass andwrites them as bulleted `[[artifact:lines]] — timestamp (agent)-[result] — note` entries. The data was already on disk in the+ [result] — note` entries. The data was already on disk in thedaily log; v0.10.1 joins it back to the rule.- **`src/core/brain/evidence.ts`** — read-only log scanner used bydream and `moveToRetired`. Returns newest-first slices for a given@@ -7433,7 +7455,7 @@ negative without yet crossing the rebuttal threshold.- **`quarantine` preference status** (closes design summary §20).Entry: a `confirmed` preference whose recomputed counters satisfy`violated_count ≥ applied_count AND applied_count >-confidence.low_max_applied` transitions to `quarantine`. The rule+ confidence.low_max_applied` transitions to `quarantine`. The ruleis still listed in `Brain/active.md` (under its own section), butthe digest surfaces it separately. Exit: a new `violated`evidence event since the last `dream` snapshot retires the rule@@ -7453,7 +7475,7 @@ confidence.low_max_applied` transitions to `quarantine`. The rulesurfaces.- **`brain_backlinks` MCP tool** + `o2b brain backlinks <id>` CLI verb.Returns the count plus a list of `{source, source_kind, field,-timestamp?}` records for any Brain artifact id (preference,+ timestamp?}` records for any Brain artifact id (preference,retired, or signal).- **`osb://backlinks/{id}` MCP resource template** — markdown renderof inbound references grouped by source kind. Same data as the@@ -7478,7 +7500,7 @@ timestamp?}` records for any Brain artifact id (preference,— the source artifact's pointer just went stale.- **`brain` section in `second_brain_status`**. The existing MCPtool now includes a `brain: { present, counts, last_dream_at,-last_apply_evidence_at, sanity }` field. Counts cover+ last_apply_evidence_at, sanity }` field. Counts coverinbox/preferences (split by status)/retired/log_days/snapshots.`sanity.signals_awaiting_dream` is non-zero when inbox signalspredate the `unconfirmed_window_days` cutoff — a one-glance "you@@ -7527,7 +7549,7 @@ last_apply_evidence_at, sanity }` field. Counts cover`[[src/cli/main.ts:42]]` (single line). New`parseArtifactRef(value)` helper in`src/core/brain/wikilink.ts` extracts `{target, range?,-malformedRange?}`. The writer accepts the syntax verbatim; the+ malformedRange?}`. The writer accepts the syntax verbatim; theparser is used by downstream readers (lint, future fragmentdisplay).- **`brain_doctor` hygiene lints** (closes the remaining §11 items@@ -7581,7 +7603,7 @@ an orthogonal audit layer for paid actions.`contradiction_window_days`, `stale_evidence_days`,`high_freshness_factor`, `snapshots.retention_count`) and`_BRAIN.md` (agent-facing operating manual, rendered by `o2b-brain init`, kept under 200 lines).+ brain init`, kept under 200 lines).- **CLI namespace `o2b brain *`** with 11 verbs: `init`,`feedback`, `dream`, `apply-evidence`, `digest`, `query`,`reject`, `pin`, `unpin`, `rollback`, `doctor`.@@ -7784,7 +7806,7 @@ records what happened.`renderPaymentDigestTelegram`) for cron-friendly 4-line summaries;- **approval workflow** (`pending-payment-request` artifact under`AI Wiki/payments/_pending/`) with `pending → approved/rejected →-consumed` state machine.+ consumed` state machine.- **Path-safety helpers** (`src/core/path-safety.ts`): `ensureInsideVault`and `vaultRelative` use `path.sep` so the prefix check works on Windowstoo; replaces the duplicated POSIX-only versions previously inlined in@@ -7850,7 +7872,7 @@ parallel Python implementation under `src/open_second_brain/*.py` are gone.- `bun:test` suite (176 cases) + Python shim tests (13 cases). Includes a12-worker multi-process append-event lock test.- Per-runtime install flows for local marketplaces (Claude `claude plugin-marketplace add <path>`, Codex `codex plugin marketplace add <path>`,+ marketplace add <path>`, Codex `codex plugin marketplace add <path>`,Hermes via plugin-dir symlink, OpenClaw `openclaw plugins install <path>`).- `agent-event-log` skill: stronger trigger description and a languagepolicy that follows the user's session language.@@ -8002,7 +8024,7 @@ Hermes / Claude Code / Codex / OpenClaw configurations do not change.path is `codex plugin marketplace add <source>`, which validates amarketplace catalog at this exact location. Without this file theinstall fails with `marketplace root does not contain a supported-manifest`. The manifest declares the repository as a one-plugin+ manifest`. The manifest declares the repository as a one-pluginmarketplace pointing at itself (`path: "."`), so the same Git URLthat worked for `hermes plugins install` works for the new Codexflow without restructuring the repo.@@ -8089,7 +8111,7 @@ manifest`. The manifest declares the repository as a one-pluginthe success line `appended: Daily/...` gave no signal that theentry had landed in the wrong place. Now every one of these entrypoints resolves the vault via `--vault → VAULT_DIR → persisted-plugin config (vault field)`, and exits with a clear+ plugin config (vault field)`, and exits with a clear`error: no vault configured. Pass --vault ... or run o2b init ...`if none of those is set. The shared resolver lives in`cli._require_vault`; the `vault-log` and standalone-`o2b mcp`@@ -8369,7 +8391,7 @@ plugin config (vault field)`, and exits with a clear- Reworded the `--args` guidance in `after-install.md` and `docs/mcp.md` sothe docs no longer contain a literal copyable quoted-args anti-example.The corrected `hermes mcp add open-second-brain --command o2b --args mcp---vault /path/to/vault` example stays; the negative case is now described+ --vault /path/to/vault` example stays; the negative case is now describedin prose ("do not wrap all of those arguments into one quoted shellstring and do not repeat `--args` per token") so a careless copy/pastecannot pick up the wrong form.@@ -8460,6 +8482,7 @@ plugin config (vault field)`, and exits with a clear- Sandbox vault and plugin manifest fixtures for tests.- GitHub release workflow for tag-based and manually dispatched releases.+[1.82.0]: https://github.com/itechmeat/open-second-brain/compare/v1.81.1...v1.82.0[1.81.1]: https://github.com/itechmeat/open-second-brain/compare/v1.81.0...v1.81.1[1.81.0]: https://github.com/itechmeat/open-second-brain/compare/v1.80.0...v1.81.0[1.80.0]: https://github.com/itechmeat/open-second-brain/compare/v1.79.0...v1.80.0diff --git a/README.md b/README.mdindex 7b4834d1..9f228d2c 100644--- a/README.md+++ b/README.md@@ -98,8 +98,8 @@ The full router with readiness criteria is [`install.md`](install.md); native Wi- **Preferences that learn and expire.** Signals, a deterministic dream pass, confidence and retirement: [how it works](docs/how-it-works.md#a-preferences-lifecycle).- **Reversible changes.** Brain mutations take a snapshot first; `o2b brain rollback` restores it: [snapshots](docs/how-it-works.md#snapshots-and-rollback).- **Attributed writes.** `o2b brain writes` lists every note write by agent and device, `writes revert` plans a restore, `o2b brain freeze` stops all writers, and `o2b brain log verify` checks the hash-chained log: [Brain CLI](docs/cli-reference.md#brain-observing-memory).-- **Search.** Keyword search with an optional semantic lane, result explanations, recall profiles and compact cards: [search CLI](docs/cli-reference.md#search), [ranking](docs/how-it-works.md#full-text-search).-- **Session recall.** Import agent transcripts already on disk and search them: [session logs](docs/cli-reference.md#session-logs-this-machine-already-has-since-v1500).+- **Search.** Keyword search with an optional semantic lane, result explanations, recall profiles and compact cards; an opt-in iterative loop (`search_iterative_recall_enabled`, default off) keeps querying when coverage gaps survive, pausing with a plan the caller answers through `brain_search`'s round trip: [search CLI](docs/cli-reference.md#search), [iterative recall](docs/cli-reference.md#iterative-recall-since-v1820), [ranking](docs/how-it-works.md#full-text-search).+- **Session recall.** Import agent transcripts already on disk, search them, or select whole-thread coverage under a character budget (`o2b brain session-grep --operation coverage --char-budget <n>`, with `--entity-key` seeding the fan-out from mined entity mentions): [session logs](docs/cli-reference.md#session-logs-this-machine-already-has-since-v1500), [coverage](docs/cli-reference.md#coverage-first-session-recall-since-v1820).- **Hygiene.** `o2b brain hygiene scan` finds contested, duplicate, stale and unused memories; `apply` runs only the findings you pick: [maintenance](docs/cli-reference.md#maintenance-and-operator-surfaces).- **Claim ledger.** `o2b brain truth ingest` records an entity claim with an optional validity window (`--valid-from`/`--valid-until`; with the flags absent, a window on the source record's frontmatter is adopted and frozen at ingest), `truth events` recalls a windowed slice of the ledger, and `truth state` grounds an agent-stated claim with an anchoring verdict - committed, or reported back with reason codes. `truth state` accepts an optional opaque `--sample-id` naming the context-pack sample the claim drew on, and claim reads report the receipt and outcome provenance behind it at the caller's reach - "receipt known, outcome unknown", never an invented verdict: [entity truth CLI](docs/cli-reference.md#entity-truth-and-self-improving-dream-since-v0430).- **Corrections.** `o2b brain lifecycle correct <target>` reports a correction's blast radius and retires the affected records - validity-closed by default, tombstoned with `--flatly-wrong`, dry run by default and `--apply` to write. A retired record that recall can still serve is served only beside its correction, never alone: [belief lifecycle CLI](docs/cli-reference.md#belief-lifecycle-and-decision-memory-since-v1330).@@ -123,7 +123,7 @@ The full router with readiness criteria is [`install.md`](install.md); native Wi## What is new-1.81.0 is the answer-trust release: it narrows the gap between what an agent was given and what its answer can be believed on. A Stop-hook step verifies the quotations in the assistant's answer against the note cited for them or the evidence recall actually injected (`quote_check.recall|active|subagent` in `Brain/_brain.yaml`, each `off|shadow|enforce`, default `shadow` - annotate-only, one `additionalContext` note per turn; `enforce` adds one Brain-log record per turn). `o2b brain truth state` accepts an optional opaque `--sample-id` naming the context-pack sample a claim drew on, and claim reads report the receipt and outcome provenance behind it at the caller's reach. Trusted local-file ingest now archives a source's bytes content-addressed under `Brain/.archives/` (redacted before persist, refused past 1 MiB, never pruned) with the hash stamped on the summary page; the capture-scope hygiene detector and a count-only doctor section name missing or mismatched evidence, and `brain_hygiene` `archive_get` reads an entry back at local reach. A record with no session id is read as no-session everywhere - scoped recall excludes it, grouping skips it, the session digest omits the key - dissolving the phantom blank-session bucket, with a count-only `blank-session-identity` doctor check for what older writers left behind. A repair lane closes the outstanding review findings: attribute narrowing in search falls a document whose indexed snapshot went stale through to the live filter instead of silently excluding it. Every release is described in the [CHANGELOG](CHANGELOG.md).+1.82.0 is the recall-quality release: it widens what recall reaches and makes every surfacing decision measurable. `brain_search` gains a bounded iterative recall loop (`search_iterative_recall_enabled`, default off, byte-identical off): when coverage gaps survive the deterministic rounds, the call pauses with a plan - the decider envelope, the candidate pool and an opaque single-use round token - and the caller commits `{evidence, subQueries}` back through `iterative_token`/`iterative_payload` to run one validated round more, with per-round records and the stop reason on the final marker. `o2b brain session-grep --operation coverage --char-budget <n>` selects whole-thread coverage instead of grep matches - facets from the thread's own mined entity keys and summary clusters, fanned out under an adaptive topic budget (floor 12, cap 16), returned chronologically with diagnostics - and `o2b brain session-describe --topics` renders the topic report. Recall admission moves to one shared graded surfacing key: the recall-inject hook and `brain_recall_gate` grade the same channel-calibrated match quality against the same floor, gate telemetry records key, tier and channel under the existing opt-in, and the bench scores it all - a suite registry gains a LongMemEval lane with a strict `recall_all@5` report family and judge glue over `bench_judge_cmd`, plus a surfacing-replay suite that replays recorded prompts through the shipped decision core. Every release is described in the [CHANGELOG](CHANGELOG.md).## Documentationdiff --git a/docs/brainstorm/recall-quality-wave/cli-output/consultant.md b/docs/brainstorm/recall-quality-wave/cli-output/consultant.mdnew file mode 100644index 00000000..c99d797d--- /dev/null+++ b/docs/brainstorm/recall-quality-wave/cli-output/consultant.md@@ -0,0 +1,32 @@+### Variant 1: Bench-first contract substrate with four parallel disjoint lanes+- **Approach**: Land the bench framework contracts first as two behavior-preserving commits owned by one bench lane: the per-suite capability declaration (a suite registry in the bench verb mapping suite to loader and capabilities) and run-identity knob pinning folded into the checkpoint hash. Then run four lanes in parallel over disjoint file sets - iterative recall loop, coverage-first session recall, graded surfacing key plus replay harness, and the rest of the LongMemEval suite - with the replay lane pinned as the one declared dependent on the two bench contract commits. A single integrator pass closes census reconciliation, docs, version bump and the full gate run.+- **Trade-offs**:+ - Maximal wall-clock parallelism: the two recall behavior lanes share no files with anything and start immediately.+ - Exactly one declared cross-lane dependency (replay harness waits on the bench contracts), so coordination cost is one paragraph of contract, not a meeting schedule.+ - The wave gains its measuring stick early: the replay suite and the LongMemEval lane can later produce before/after receipts for the behavior lanes inside the same pull request.+ - Cost: the contract must be written down precisely (who owns which file, append-only rights on the bench registration points), and the bench lane must commit its two contract commits before the replay lane starts.+- **Complexity**: medium+- **Risk**: low++### Variant 2: Serial quality stack in measurement-first order+- **Approach**: Build the four residues one at a time, each fully complete and green on the branch before the next starts, ordered so measurement always precedes behavior: LongMemEval bench suite, graded surfacing key and replay harness, coverage-first session recall, iterative recall loop. No lane structure, no cross-lane contracts; every change lands against a fully settled tree.+- **Trade-offs**:+ - Zero coordination cost and the simplest possible audit trail: each residue is a clean sequential commit series.+ - Every change is built against the previous change's final state, so no waiting rules or append-only ownership splits are needed.+ - Four sequential build-and-stabilize cycles stretch the release badly; the two recall behavior lanes are completely file-disjoint yet serialize unnecessarily.+ - Late lanes inherit churn from earlier lanes' unrelated refactors, widening the review surface per step.+- **Complexity**: small+- **Risk**: medium++### Variant 3: Two stacked half-waves - measurement, then behavior+- **Approach**: Split the wave into two stacked halves inside one pull request: half-wave one lands the two measurement residues (LongMemEval suite and the graded gate with its replay harness), half-wave two lands the two recall behavior residues (iterative loop and coverage-first session recall) and records their before/after numbers with the new harness. The halves share the branch sequentially; within each half the lanes run in parallel.+- **Trade-offs**:+ - Each half is independently verifiable, and the final pull request carries measured evidence for the behavior changes, which is the strongest possible receipt.+ - The behavior lanes are forced to wait for the full measurement half even though the iterative loop and coverage recall share nothing with the bench files.+ - Stacked half-wave history entangles reverts: rolling back one behavior lane drags the measurement lane it is stacked on.+ - The integrator faces two merge windows instead of one, doubling the census-reconciliation work.+- **Complexity**: medium+- **Risk**: medium++### Recommended: Variant 1+**Rationale**: The four residues are file-disjoint except one genuine seam - the replay harness needs the suite registry and knob pinning the bench lane owns - so parallel lanes with a single pinned dependency capture almost all of the serial variant's safety at a fraction of its wall clock. Landing the two behavior-preserving bench contracts first costs nothing and hands the wave its measuring stick before any behavior changes land, which is exactly the discipline the repo's byte-identical-off invariant wants. This is also the shape the previous recall-quality wave on this branch already executed successfully, so the tooling and audit conventions exist.diff --git a/docs/brainstorm/recall-quality-wave/cli-output/prompt.md b/docs/brainstorm/recall-quality-wave/cli-output/prompt.mdnew file mode 100644index 00000000..7b44d483--- /dev/null+++ b/docs/brainstorm/recall-quality-wave/cli-output/prompt.md@@ -0,0 +1,111 @@+You are brainstorming architectural variants for the following task. Do not write code. Do not write a final design. Only produce variants and a recommendation.++# Task++This is a release wave of four related kanban cards that must compose into ONE pull request on branch feat/recall-quality-wave of Open Second Brain. Brainstorm how the four verified residues below compose into a single coherent delivery (lane structure, cross-lane contracts, integration order). The recon node already verified every anchor below against the live tree and corrected or refuted the card premises; the "residue" line in each card is the corrected, agreed scope.++## Card t_6b943fc7 (priority 2): Iterative multi-round retrieval with a caller-executed decider step++Source: EverMind-AI/EverOS v1.3.1.++What upstream ships: an optional multi-round retrieval mode where each round fuses keyword + semantic candidates with RRF, then a decider step selects core evidence, identifies remaining gaps, and issues follow-up sub-queries until a bounded final context is returned. To respect the deterministic-first rule, the decider is not an LLM call inside the search algorithm: Open Second Brain should emit a needs-llm-step envelope the caller executes (mirroring planExtractSignals in src/core/brain/extract-signals.ts), with the commit phase validating the decider's selected-evidence/follow-up-query output before the next round.++Validator verdict (premise_partly_false, refuted as stated): "One fused pass" is not what ships. A self-correcting second pass already runs: exactly one of two mutually exclusive retries fires per query - a zero-candidate pool gets a broadened OR retry, a partially-covered pool gets a targeted retry on the specifically uncovered rare terms - both deterministic and LLM-free (src/core/search/pipeline/second-pass.ts:1-7, dispatch :68-71, broadened :81-110, targeted :122-174; gate src/core/search/search.ts:435-438). That is the card's round two, with a coverage-derived gap signal instead of a model decider. The shadow-only advisor already computes the stop condition the loop needs: a marginal-value stop derived from the density curve plus observed p95 latency (src/core/brain/retrieval-plan.ts:195-224). The genuine delta: more than two rounds, follow-up SUB-QUERIES rather than term-level retries, and a decider that selects core evidence. The decider must be a needs-llm-step envelope the caller executes with a validating commit phase, exactly as planExtractSignals does (src/core/brain/extract-signals.ts:443-490, commitExtractedSignals :578-597), because the kernel never calls a model. Build it as an iterative mode over the existing second-pass lane and the advisor's stop, not as a new subsystem; keep the invariant that with the mode off, ranking and pool stay byte-identical.++Residue: a bounded N-round loop generalizing the single-fire second pass (round driver at the search.ts:435-456 seam), deterministic k-group sub-query generation generalizing planTargetedRetry (src/core/search/coverage.ts:208), a caller-executed decider envelope with validating commit, a composed stop condition (round cap + composite deadline + coverage completeness + adapted marginal-value stop), a default-off config knob, per-round outcome observability, and a caller-facing plan/commit round-trip that does not disturb the cached single-read brain_search response in its default shape.++## Card t_2c2a883c (priority 3): Coverage-first thread/entity recall with adaptive topic budget and typed evidence selection++Source: yantrikos/yantrikdb v0.17.0.++What upstream ships: recall_thread (coverage-first retrieval over conversation/entity threads: retrieve wide, then compress, every record carrying a canonical source turn), resolve_thread_topics (adaptive topic budget, floor 12 / cap 16), select_thread_evidence (relevance-ranked selection under a budget, presented chronologically, recomputable diagnostics, typed infeasibility error instead of silent truncation).++Validator verdict (premise_partly_false, two premises refuted): a conversation-thread recall lane already exists - import, search, describe and expand over session turns, stitching across compaction boundaries via a lineage ledger (src/core/brain/session-recall.ts:19-30, summary nodes over turn groups :531-580), surfaced as brain_session_grep / brain_session_describe / brain_session_expand (src/mcp/brain/recall-tools.ts:1507/:1557/:1570). And source-turn provenance already persists as source_turn_ids on continuity records (src/core/brain/session-checkpoint.ts:163), so no canonical-turn stamp needs inventing. Today's scoring is one line - kind weight plus occurrence count (hitFor, session-recall.ts:706-737) - top-k, no coverage or diversity notion.++Residue: coverage-first retrieve-wide-then-compress over the lineage-scoped record set (sessionRecallRecords :582-605), an adaptive topic budget, relevance-ranked evidence selection re-emitted chronologically (collectRawRecords :739-751, compareRecords :851-855, applyCharBudget in src/core/brain/recall-budget.ts:127), a typed infeasibility error when the budget cannot hold the floor-weighted selection, and entity-thread wiring: resolving a mined entity key to its session_entity_mention rows (src/core/brain/continuity/types.ts:99) to seed coverage. Constraint: the MCP tool census is pinned at 115 (tests/core/install/tool-ceiling.test.ts:348), so this ships as a new operation on brain_session_grep plus CLI parity, never a new tool.++## Card t_107a3249 (priority 3): Ranked channel-aware context surfacing and a recorded-session replay harness++Source: yoloshii/ClawMem commit 2668f37.++What upstream ships: a single channel-aware ordering key that ranks candidate memory context instead of a binary retrieve/skip decision, admission that honestly abstains, a rerank lane gated by measured eval, and a replay-eval harness that judges surfacing decisions against recorded sessions.++Validator verdict (premise_partly_false, two of three asks struck as already shipped): honest abstention ships as a recorded recall decision with an explicit abstain action (src/core/brain/recall-adequacy.ts:33, RECALL_ADEQUACY_ACTIONS; src/core/brain/recall-inject.ts abstain decision variant :340-357), and rerank influence is already gated by a measured eval (src/core/search/rerank-eval-gate.ts:91-129, operator-facing recommendation). What remains: the surfacing gate really is binary (SurfacingGateDecision {retrieve, reason}, src/core/search/surfacing-gate.ts:15-18, evaluateSurfacingGate :82-98) and there is no replay-eval harness for surfacing decisions (src/core/bench/phases.ts drives fixture questions, not recorded sessions; src/core/bench/failure-modes.ts:27-36 states the gate fails open by design and its false-fire rate is ~1 by construction, so the bench deliberately does not score it). One hard constraint: gate_telemetry deliberately stores only a SHA-256 prompt prefix and length, never the raw prompt (src/core/brain/gate-telemetry.ts:1-20), so a replay must source prompts from session_turn records or a session-shaped fixture. The hook channel already admits on a measured absolute key: matchQuality (RecallResultSet.idfWeightedCoverage, produced at src/core/search/pipeline/outcome.ts:126) against RECALL_INJECT_CONFIDENCE_FLOOR 0.35 (src/core/brain/recall-inject.ts:66, admission ladder decideOverRetrieval :481-574). The channel vocabulary exists: RECALL_CHANNEL = {mcp, cli, hook} at src/core/brain/recall-telemetry.ts:27-48.++Residue: one shared graded key/tier shape (admission axis = channel-calibrated absolute match quality; order axis = the existing fused composite, which is per-pool normalized and must never be a threshold basis), consumed by both brain_recall_gate (src/mcp/search-tools.ts:1293) and decideRecallInject, with the pure prompt-structural gate kept as the structural pre-tier and its binary decision projected for compatibility; plus a recorded-session replay bench suite scoring know_to_ask / false_fire the way decideRecallInject is already scored, closing the "not scoreable" caveat, with bookkeeping riding the existing opt-in gated telemetry thunk.++## Card t_607d429d (priority 1): LongMemEval public benchmark lane++Source: garrytan/gbrain v0.48.4.0.++What upstream ships: a LongMemEval public-benchmark suite scoring the official strict recall_all@5, excluding abstention questions, joining gold session ids without intermediate sanitization, pinning reranker/autocut/search knobs per run, caching embeddings so arms compare byte-identical vectors, and optionally LLM-judging answer accuracy with the official prompts.++Validator verdict (premise_confirmed after an earlier correction): the public-benchmark lane pattern exists - the LoCoMo adapter src/core/bench/locomo.ts (199 lines, converts a LoCoMo dataset into the existing BenchFixture, deterministic, network-free, judge opt-in) exposed as `o2b brain bench memory --fixture <path> --suite locomo` (src/cli/brain/verbs/bench.ts:23, suite guard :40-42, dispatch :52-53), tested in tests/core/bench/locomo.test.ts. No LongMemEval support exists. Two binding constraints: the bench pipeline is network-free BY DESIGN (disposable vault inside the run dir, keyword-only search pinned semantic-off at src/core/bench/phases.ts:124-126, judge optional and external via bench_judge_cmd / src/core/bench/judge.ts:29), so a suite needing real embeddings must declare a per-suite capability rather than quietly change what the pipeline does, and the embedding spend falls under the explicit apply-gate rule (src/core/search/indexer.ts:142-145, vector-backfill.ts, embedding-spend.ts). And resume is keyed on run id plus fixture hash (src/core/bench/run-store.ts:72-79), so per-run knob pinning must enter that hash or a resumed run silently mixes two configurations. Trap: the LoCoMo adapter sets expected_text on retrieval questions but evaluateQuestion never reads it for retrieval categories (phases.ts:343-367), so the LongMemEval converter must not rely on expected_text.++Residue: a suite adapter src/core/bench/longmemeval.ts (parser with named errors, converter to BenchFixture, abstention exclusion with recorded count, direct gold-session-id join), a committed tiny sample fixture with the full dataset operator-supplied, a per-suite capability declaration on the bench options ({embeddings: boolean}), run-identity knob pinning (SearchConfigOverrides-shaped, folded into the checkpoint hash), a strict recall_all@5 named metric family in the report, an embedding cache so arms compare byte-identical vectors, and judge glue reusing bench_judge_cmd with an extended stdin payload (question/answer/gold).++# Project context++Open Second Brain: a memory layer for AI agents living in an Obsidian vault, read and written through MCP servers, lifecycle hooks and the o2b CLI. TypeScript on Bun. Deterministic core: no model runs inside the algorithms; model work rides needs-llm-step envelopes the caller executes.++Recent commits:++259e4b70 fix(snapshot): decode readdir buffer entries as UTF-8 so exclusions match (v1.81.1) (#243)+28ea378b chore(deps): bump the github-actions group with 2 updates (#245)+745c4a95 chore(deps): bump the bun-minor-and-patch group with 4 updates (#246)+323fb9e4 feat: answer trust - verified quotes, claim provenance and durable source evidence (v1.81.0) (#249)+a00fa3f5 feat: recall quality - mined sessions, honest admission and a store that filters in SQL (v1.80.0) (#248)+3f029241 feat: write-side trust - identity, permission and review for every agent write (v1.79.0) (#247)+66f9d847 feat: credential custody under a passphrase and a verifiable trust surface (v1.78.0) (#244)+3afb94a5 feat: a truth layer you can correct and time-travel (v1.77.0) (#242)+e907c692 ci: balance windows test shards by measured duration (#241)+f3d7185e fix: keep generated cluster digests out of community detection (#240)+646a49df feat: freshen the search index on read, rewriting only changed chunks (v1.76.0) (#239)+78f924b9 feat: deliver context to subagent turns, hygiene digest at turn end and tiered context shrink (v1.75.0) (#238)+542d214b fix(opencode): support both plugin APIs (v1.74.1) (#190)+0cbb60b8 feat: near-duplicate defense across the fact lifecycle (v1.74.0) (#237)++Related files:++- Search pipeline: src/core/search/search.ts, src/core/search/pipeline/second-pass.ts, src/core/search/pipeline/iterative-recall.ts (proposed), src/core/search/coverage.ts, src/core/search/types.ts, src/core/search/index.ts, src/core/search/pipeline/outcome.ts, src/core/search/pipeline/attribution.ts, src/core/search/pipeline/cache-slot.ts+- Envelope spine: src/core/brain/llm-step.ts, src/core/brain/extract-signals.ts, src/core/brain/retrieval-plan.ts+- Session recall: src/core/brain/session-recall.ts, src/core/brain/recall-budget.ts, src/core/brain/continuity/types.ts, src/core/brain/link-graph/session-mining.ts, src/core/brain/entities/registry.ts+- Surfacing: src/core/search/surfacing-gate.ts, src/mcp/search-tools.ts, src/core/brain/gate-telemetry.ts, src/core/brain/recall-inject.ts, src/core/brain/recall-telemetry.ts+- Bench: src/core/bench/phases.ts, src/core/bench/types.ts, src/core/bench/fixture.ts, src/core/bench/run-store.ts, src/core/bench/judge.ts, src/core/bench/locomo.ts, src/core/bench/failure-modes.ts, src/cli/brain/verbs/bench.ts+- MCP and CLI surfaces: src/mcp/brain/recall-tools.ts, src/cli/brain/verbs/session-recall.ts, src/cli/command-manifest.ts, src/cli/brain/help-text.ts++Conventions:++- Mode-off byte-identical invariant: every opt-in feature must leave outcomes byte-identical when off (precedents: relational-arm doc contract, rerank-off reader tail, the twoPassEnabled kill-switch test at tests/core/search/two-pass.test.ts:66-70).+- Deterministic-first: the kernel never calls a model; caller-executed needs-llm-step envelopes with validating commit phases (brain_extract_signals one-tool-two-phases precedent: plan phase when the payload is absent, commit phase when present, phase discriminator in the response).+- Nothing writes silently, nothing degrades silently: typed explicit errors naming the shortfall; no silent fallbacks (v1.52.0 direction).+- Budget primitives are reused, never forked (applyCharBudget, text-budget).+- Telemetry and bookkeeping stay off the latency-critical path: opt-in, lazily-evaluated gated thunks.+- Bench harness is network-free by design: disposable vault, keyword-only default, external optional judge; deviations are declared per-suite capabilities with embedding spend under the explicit apply gate.+- Parallel implementation lanes over disjoint file sets with pinned cross-lane contracts; shared registration files are append-only with each lane appending only its own entries; census and ratchet tests arbitrate.++Constraints:++- No new MCP tools: the tool census is pinned at 115 by an equality test (tests/core/install/tool-ceiling.test.ts:348). Every new recall surface rides an existing tool's operations, an existing CLI verb, or the bench suite registry.+- Defaults off: every opt-in mode ships disabled with a byte-identical-off regression proof.+- Typed explicit errors; no silent fallbacks or silent truncation.+- No new external dependencies.+- Existing public API default shapes do not change (brain_search default response byte-identical; brain_session_grep without the new operation byte-identical; locomo bench reports byte-identical).+- This is one pull request: the four residues compose into one release with per-lane atomic commits on the shared feature branch.++# Required output format++Produce exactly 3 distinct architectural variants for how the four residues compose into the single wave pull request (lane structure, cross-lane contracts, integration order). For each variant:++### Variant N: <short name>+- **Approach**: 2-3 sentences describing the variant.+- **Trade-offs**: bullet list of pros and cons.+- **Complexity**: small | medium | large+- **Risk**: low | medium | high++After the three variants, add exactly one recommendation:++### Recommended: Variant N+**Rationale**: 2-3 sentences explaining why this variant over the others, considering the project context and constraints above.++Output nothing outside of these sections.diff --git a/docs/brainstorm/recall-quality-wave/design.md b/docs/brainstorm/recall-quality-wave/design.mdnew file mode 100644index 00000000..76258f51--- /dev/null+++ b/docs/brainstorm/recall-quality-wave/design.md@@ -0,0 +1,137 @@+# Recall quality wave 2 - iterative recall loop, coverage-first session recall, graded channel-aware surfacing with a replay harness, and a LongMemEval bench lane++**Status:** draft+**Author:** feature-release-playbook orchestrator+**Audience:** implementation++## Problem statement++Four verified cards in this wave share one defect family: recall quality is bounded by how many retrieval rounds run, by how session threads are selected, and by how surfacing decisions are made and measured. Hard multi-hop queries get at most one deterministic self-correcting second pass, so residual coverage gaps after that retry are never closed; session recall scores records by a one-line keyword count with no notion of thread coverage, topic budget or ranked chronological evidence, and silently drops what the budget cannot hold; the surfacing gate is a binary prompt-structural predicate with no graded admission key and no way to replay and score surfacing decisions against recorded sessions; and the bench has no LongMemEval suite, so Open Second Brain cannot produce like-for-like recall_all@5 receipts on the benchmark the memory field actually reports. All four residues are extensions of proven in-tree subsystems, verified anchor by anchor by the recon node.++## Scope++- t_6b943fc7 (lane A) - the corrected residue: generalize the single-fire second pass into a bounded N-round loop over the same pool-merging discipline, with deterministic k-group sub-query generation, a caller-executed decider envelope (needs-llm-step plan plus validating commit, mirroring the extract-signals pattern), a composed stop condition (round cap + composite deadline + coverage completeness + adapted marginal-value stop), a default-off config knob pair, per-round outcome observability, and a brain_search plan/commit round-trip that leaves the default response and cache keys byte-identical.+- t_2c2a883c (lane B) - the corrected residue: coverage-first retrieve-wide-then-compress over the existing lineage-scoped session-recall record set, an adaptive topic budget (corpus-shaped clamp with floor 12 and cap 16), relevance-ranked evidence selection re-emitted chronologically with recomputable diagnostics, a typed infeasibility error on floor violation, and entity-thread wiring that resolves a mined entity key to its mention rows to seed coverage - shipped as a new operation on brain_session_grep plus CLI parity, never a new tool.+- t_107a3249 (lane C) - the corrected residue: one shared graded surfacing key ({key, tier, admit, reason}: admission from channel-calibrated absolute match quality, order from the existing fused composite) consumed by both brain_recall_gate and decideRecallInject with the pure prompt-structural gate kept as the structural pre-tier and its binary decision projected for compatibility; extended gate telemetry (key, tier, channel) under the existing opt-in; and a recorded-session replay bench suite scoring know_to_ask / false_fire, closing the failure-modes "not scoreable" caveat.+- t_607d429d (lane D) - the corrected residue: a LongMemEval suite adapter beside locomo (parser with named errors, converter to BenchFixture, abstention exclusion with recorded count, direct gold-session-id join), a committed tiny sample fixture with the full dataset operator-supplied, a per-suite capability declaration ({embeddings: boolean}) delivered by a suite registry in the bench verb, run-identity knob pinning folded into the checkpoint hash, a shared embedding cache so arms compare byte-identical vectors, a strict recall_all@5 named report family, and judge glue reusing bench_judge_cmd with an extended stdin payload.+- Integration lane - census reconciliation, docs (mcp, cli-reference), CHANGELOG entry and the minor version bump with manifest sync inside this pull request, and the full local gate run.++## Out of scope++- New MCP tools: the tool census stays pinned at 115 (tests/core/install/tool-ceiling.test.ts:348). Every new surface rides an existing tool's operations, an existing CLI verb, or the bench suite registry.+- Rerank auto-promotion: applying the rerank eval verdict to runtime config automatically was struck by the validator as a separate, larger ask; the operator-facing measured gate ships as-is.+- Honest abstention and influence-gated rerank: both already ship (recall-adequacy actions; rerank-eval-gate verdict) and are not rebuilt.+- A first thread-recall verb or a source_turn stamp: session recall with lineage stitching ships, and source_turn_ids already persist; lane B layers on the existing lane and writes no new record kinds and no new persisted fields.+- Daemon-side hydrated-v1 projection: Open Second Brain has no daemon.+- Full LongMemEval dataset vendoring or download-at-run: a tiny committed sample plus an operator-supplied full-dataset path only; the loader stays pure and network-free.+- New config knobs for channel admission thresholds: per-channel thresholds ship as exported module constants this wave; operator tuning can layer later.+- A CLI mirror of the iterative plan/commit round-trip: the decider protocol serves MCP agent callers (the card's stated audience); a CLI mirror is deferred.+- Real-provider embedding calls in committed tests: CI certifies the LongMemEval lane on the deterministic local provider through the apply-gated path; real-provider scores remain a documented operator lane.++## Chosen approach++Variant 1: bench-first contract substrate with four parallel disjoint lanes (consultant recommendation, orchestrator agrees; full text of all variants and the decision record in `variants.md`).++Lane D owns the bench framework files and lands two behavior-preserving contract commits first: the suite registry with per-suite capability declaration in the bench verb, and run-identity knob pinning folded into the checkpoint hash. Lanes A (iterative recall loop), B (coverage-first session recall) and C (graded surfacing key, shared admission, telemetry v2) then run in parallel over fully disjoint file sets; Lane C's replay-harness tasks are the wave's one declared dependency, waiting on Lane D's two contract commits and appending only the replay suite registration on top of the bench framework. Lane D finishes the LongMemEval suite; lane C finishes the replay harness. One integrator pass closes census reconciliation, docs, the CHANGELOG entry, the version bump via scripts/sync-version.ts, and the full local gate run in CI order.++## Design decisions++1. **Delivery model: Variant 1, with bench file ownership pinned.** The bench framework files (`src/core/bench/phases.ts`, `src/core/bench/types.ts`, `src/cli/brain/verbs/bench.ts`) are exclusively Lane D's, with Lane C granted append-only rights for its own suite-registration entries exercisable only after Lane D's two contract commits land; every commit stays single-owner at the file level. The two recall behavior lanes (A, B) depend on nothing and start immediately. The one shared source file (`src/mcp/search-tools.ts`) is split by append-only ownership: Lane C owns the file and the `brain_recall_gate` tool definition; Lane A holds append-only rights limited to the `brain_search` tool definition and handler.+2. **t_6b943fc7 - where the loop pauses: a resumable core outcome, surfaced as a brain_search one-tool-two-phases round-trip.** The kernel never awaits a model: with the knob on and coverage gaps remaining after the deterministic rounds, `search()` returns a plan-phase outcome carrying the needs-llm-step envelope and an opaque single-use round token; the caller re-invokes with the token plus its decider payload, and the commit phase validates before the loop advances. Over MCP the round-trip rides `brain_search` itself - optional request fields (iterative flag, round token, decider payload), and a response phase discriminator (`final` | `needs-llm-step`) present only in the opt-in mode - mirroring the `brain_extract_signals` plan-when-payload-absent shape exactly. This resolves the recon's tension between "resumable outcome" and "brain_search response must not grow an envelope": the default response shape is untouched (byte-identical, fixture-pinned), the envelope exists only under the opt-in flag, and no new tool is needed. A second commit with an already-used token is refused with a typed error, never silently re-run.+3. **t_6b943fc7 - cache correctness: the new request fields join the brain_search cache key as a mode-on suffix.** The query-cache key composition is a documented compatibility surface (cache-slot.ts header); appending the iterative fields unconditionally would orphan every existing cached row. The fields are folded into the key suffix only when the iterative mode is on, so off-mode keys stay byte-identical and only mode-on rows (new by definition) use the extended layout. Plan-phase and commit-phase responses are deterministic functions of their inputs (vault, query, token, payload hash), so caching stays sound.+4. **t_6b943fc7 - stop condition: composed.** Round cap plus the existing composite deadline bound the loop; coverage completeness decides whether gaps remain; the advisor's marginal-value stop, extracted into a reusable predicate over an arbitrary density/latency curve, decides whether closing them is worth the latency. Adaptation rather than verbatim reuse: the advisor's curve is context-pack density, so the predicate is re-fed candidate-density and elapsed-time samples from the loop. The advisor's own `buildRetrievalPlan` output is pinned byte-identical by its existing tests.+5. **t_6b943fc7 - sub-query authorship: both lanes, deterministic floor first.** The generalized coverage planner (k term groups generalizing `planTargetedRetry`) is the always-available floor and is today's round-2 behavior generalized - the mode is useful with no model in the loop. Validated decider sub-queries are the additive rounds the card asks for: the envelope is emitted only when gaps remain after a deterministic round and the round cap allows one more; a declined or absent commit finalizes the loop honestly rather than blocking.+6. **t_6b943fc7 - knob placement: a new knob pair, not extended twoPassEnabled semantics.** `iterativeRecallEnabled` plus `iterativeRecallMaxRounds` (env-mirrored like its siblings) resolved alongside `twoPassEnabled`, default off. `twoPassEnabled`'s documented "at most one retry" contract stays untouched, and the byte-identical-off invariant is trivially auditable with the two-pass kill-switch test as the exact precedent.+7. **t_6b943fc7 - decider module placement and validators: search-domain module over the brain envelope spine.** New `src/core/search/decider-step.ts` imports `buildNeedsLlmStep` from `src/core/brain/llm-step.ts` (search modules already import brain modules; no import-direction ratchet exists). The commit phase mirrors `commitExtractedSignals`: a shape assert plus registered semantic checks - selected evidence ids must exist in the round's pool, sub-query count and length limits, single-use token enforcement - all typed named refusals.+8. **t_6b943fc7 - observability: a sibling optional field, not new reason strings.** `SearchOutcome` gains an optional iterative rounds record (per-round counts and stop reasons) projected in the outcome pipeline; existing `second_pass:` attribution strings are unchanged, and the field is absent when the mode is off so serialization stays byte-identical.+9. **t_2c2a883c - adaptive topic budget semantics: corpus-shaped clamp.** Facets are derived from the thread itself (distinct mined entity keys, summary-node clusters, role alternation) and the budget is `clamp(distinct facets, floor 12, cap 16)` with the floor, cap and facet-count logic exported like `DEFAULT_GROUP_SIZE` so operator config can layer later. Chosen over recall-pressure widening (two-pass, hard to keep deterministic and recomputable) and over per-vault config (operator-tuned, not adaptive). Diagnostics report the realized topic count honestly: a 3-facet thread floors at 12 and says 3 were realized.+10. **t_2c2a883c - typed infeasibility: floor violation only.** When the character budget cannot hold the floor-weighted selection, a typed error names requested and kept topics plus required chars so the caller can retry with a larger budget; above the floor, drops are returned in diagnostics, never silent. Any-drop-raises was rejected (unusable on long threads, collides with `applyCharBudget`'s contract used elsewhere); a truncation-flag-only result was rejected as exactly the silent degradation the v1.52.0 direction forbids. Over MCP the error maps to INVALID_PARAMS.+11. **t_2c2a883c - MCP surface: a new operation on brain_session_grep, never a new tool.** The coverage view (topic budget, coverage selection, diagnostics) plus an optional topic report on brain_session_describe are schema additions to the existing tool definitions; the 115-tool equality pin must not move. CLI-first-only was rejected because it leaves the card's stated beneficiary - the MCP recall and context-pack path - unable to call the lane.+12. **t_2c2a883c - budget primitive: wrap, never fork or edit.** `src/core/brain/recall-budget.ts` is frozen for this wave. Rank-then-reorder happens in the session-recall layer feeding `applyCharBudget` ranked-then-reordered; the typed infeasibility wraps the dropped outcome at the call site when the floor is violated. `collectRawRecords` and `compareRecords` provide the chronological re-emission.+13. **t_2c2a883c - entity dimension: read-side wiring only.** An entity key resolves to its existing `session_entity_mention` rows (provenance-grade, already written by imports; no new mining, no new record kind), and a coverage call seeded by that key returns the establishing turns chronologically. Unknown keys raise the same typed error family - never an empty silent result. The continuity schema does not move.+14. **t_107a3249 - the ranked key: two-part, one graded shape.** Admission uses channel-calibrated absolute match quality (`idfWeightedCoverage` - already produced by the pipeline, already threshold-proven by the hook floor, absolute across queries); order uses the existing fused composite, which is min-max normalized per pool and must never be a threshold basis (the exact defect recall-adequacy documents). Both surface as one `{key, tier, admit, reason}` decision. A prompt-prior scalar was rejected: it would break the gate's language-agnostic, keyword-free invariant that tests pin.+15. **t_107a3249 - computation site: one shared pure calculator, two consumers, gate stays pure.** New `src/core/search/surfacing-key.ts` computes key and tier from a retrieval result plus channel; `decideRecallInject`'s floor branches and `brain_recall_gate` both consume it, so hook and gate grade identically. `evaluateSurfacingGate` remains a pure prompt-structural pre-tier with its structural suppressions (empty, duplicate, slash_command, shell_command) as named short-circuits, and keeps projecting the binary `{retrieve, reason}` so the pinned gate contract tests stay green unchanged.+16. **t_107a3249 - channel means transport, thresholds are constants.** `RECALL_CHANNEL` (mcp/cli/hook) is the admission-calibration axis because every telemetry record already carries it and the replay harness can therefore reproduce it; finer surface distinctions belong in metadata. Per-channel thresholds ship as exported module constants - the hook keeps `RECALL_INJECT_CONFIDENCE_FLOOR` 0.35, and the mcp/cli diagnostic channels default to the same floor this wave - with no new config knobs.+17. **t_107a3249 - replay corpus: fixture-first with a session-record adapter.** Committed session-shaped fixtures (deterministic, network-free, the locomo pattern) drive the suite; a loader converts a vault's own `session_turn` records into the same fixture shape, giving regression proof against real sessions without committing raw prompts. Recorded `gate_telemetry` decisions are never re-executed - the module stores only prompt hashes by design, so replay always re-decides from source prompts.+18. **t_107a3249 - replay integration: a named suite through Lane D's registry, not a new category.** The replay phase rides the suite registry and the existing checkpoint/resume machinery; scoring reuses `scoreProactiveRecall` (know_to_ask / false_fire) and reports `injected_tokens` per turn; the phases invariant that an abstain injects nothing and costs zero is asserted. This avoids co-owning the bench category union and keeps `src/core/bench/types.ts` single-owner except for the pinned registration types.+19. **t_107a3249 - telemetry v2: additive payload under the existing opt-in.** `gate_telemetry` records gain optional key, tier and channel fields through the same lazily-evaluated gated thunk and `recall_gate_telemetry` opt-in; summary counts by tier; no new record kind, so the continuity reader and envelope censuses stay green. The opt-in-off path records nothing, unchanged.+20. **t_607d429d - dataset supply: committed sample plus operator path.** A tiny committed `longmemeval-sample.json` follows the locomo fixture precedent; the full dataset arrives as an operator-supplied file path resolved by the existing literal-then-fixture-dir logic. Full vendoring (hundreds of megabytes) and download-at-run (network inside the verb) were rejected; the official download is documented once in the suite docblock.+21. **t_607d429d - judge: bench_judge_cmd reused, payload extended additively.** The single external-judge contract stays; its stdin payload gains question, answer and gold when the suite provides them (absent for locomo, whose payload is unchanged), keeping the kernel model-free and the judge fail-open. Official LongMemEval prompt text lives in the module as constants pinned to a named upstream revision so the external command stays a dumb model call.+22. **t_607d429d - metric: a new named report family, never an overload.** `longmemeval: { recall_all_at_5, abstention_excluded }` joins the report and CLI output while the quality, latency and context_cost families stay untouched (the MemScore rule: families stay separate and named). Overloading pass_rate would hide what was excluded; a second report file would break the one-report resume model. Per-question scoring already equals all-gold-in-top-5 in the retrieval branch, so the aggregate is a named roll-off, not new scoring.+23. **t_607d429d - capability declaration shape: an in-file suite registry on the verb.** The two-line guard/dispatch in the bench verb becomes a registry mapping suite name to `{ loader, capabilities: { embeddings } }`; capabilities ride `BenchRunOptions` set by the CLI from the registry, the guard remains the single gate, the fixture schema is unchanged for the default path, and omitting `--suite` stays byte-identical (locomo). "What a suite may do" is explicit in code rather than flag-implied, which is the validator's stated constraint.+24. **t_607d429d - knob pinning: SearchConfigOverrides-shaped, folded into run identity.** A pinned-knobs record on `BenchRunOptions` is applied last via `resolveSearchConfig` (overrides win) and folded into the checkpoint hash input, so a resumed run that mixes configurations fails the hash guard loudly. The default pin equals today's hardcoded semantic-off override, so locomo report numbers stay identical; the one-time consequence is that in-flight runs started before the change no longer resume - the guard fails fast with a named error, documented in the suite docblock.+25. **t_607d429d - embedding caching: one signature-keyed cache file under the runs dir.** Keyed by provider, model and text hash, written by the suite's index phase only when the embeddings capability is declared, so both arms compare byte-identical vectors without store-schema changes. Spend always surfaces the plan through the apply-gated path (`indexer.ts` embeddings option, spend gate); it is never silently bypassed.+26. **t_607d429d - abstention and the expected_text trap: handled at conversion.** Abstention questions are dropped at conversion time with the exclusion count recorded in the suite receipt and report family (the fixture parser rejects unknown categories, so pass-through is not an option). Gold session ids join by direct set membership with unknown ids rejected, sanitized only at note-path materialization. The converter never sets or relies on `expected_text` for retrieval scoring, because `evaluateQuestion` ignores it for retrieval categories.+27. **Wave-wide house rules.** Every opt-in surface ships default off with a byte-identical-off regression proof; typed explicit errors everywhere, no silent fallbacks; the tool census (115), continuity reader/envelope censuses, tool-probe catalogue and parity ratchets move only in the same commits as their schema growth; no new external dependencies; no new persisted continuity record kinds.++## File changes++Lane A - iterative recall loop (t_6b943fc7):++- new `src/core/search/pipeline/iterative-recall.ts` (round driver, stop composition, resume token, envelope build hook)+- new `src/core/search/decider-step.ts` (needs-llm-step envelope content, commit validators, registered semantic checks)+- modify `src/core/search/coverage.ts` (k-group gap signal generalizing planTargetedRetry)+- modify `src/core/search/pipeline/second-pass.ts` (extract the shared gap-proposal half)+- modify `src/core/search/search.ts` (mode gate and loop hook at the 435-456 seam)+- modify `src/core/search/index.ts` (knob resolution, env mirror)+- modify `src/core/search/types.ts` (resolved knobs, optional iterative outcome field, request fields)+- modify `src/core/search/pipeline/outcome.ts` and `src/core/search/pipeline/attribution.ts` (per-round projection)+- modify `src/core/brain/retrieval-plan.ts` (extract the marginal-value stop as a reusable predicate)+- modify `src/core/search/pipeline/cache-slot.ts` (append the iterative request fields to the cache-key suffix, mode-on only)+- modify `src/mcp/search-tools.ts` (append-only: brain_search tool definition and handler only)+- new tests `tests/core/search/iterative-recall.test.ts`, `tests/core/search/decider-step.test.ts`+- extend `tests/core/search/two-pass.test.ts`, `tests/core/search/coverage-targeted-recall.test.ts`, `tests/core/search/coverage-unmeasurable.test.ts`, `tests/core/brain/retrieval-plan.test.ts`, `tests/mcp/search.test.ts`, `tests/mcp/brain-search-reasons.test.ts`++Lane B - coverage-first session recall (t_2c2a883c):++- modify `src/core/brain/session-recall.ts` (coverage selection, rank-then-reorder, diagnostics, typed error)+- new `src/core/brain/thread-topics.ts` (pure facet detection and budget clamp)+- modify `src/mcp/brain/recall-tools.ts` (coverage operation on brain_session_grep, optional topic report on brain_session_describe, INVALID_PARAMS mapping)+- modify `src/cli/brain/verbs/session-recall.ts` (flag parity)+- modify `src/core/brain/entities/registry.ts` (read-side entity-key to mention-rows resolution)+- append-only `src/cli/command-manifest.ts`, `src/cli/brain/help-text.ts`+- frozen `src/core/brain/recall-budget.ts` (wrapped at the call site, never edited)+- new tests `tests/core/brain/session-recall.coverage.test.ts`, `tests/core/brain/thread-topics.test.ts`+- extend `tests/core/brain/session-recall.test.ts`, `tests/core/brain/session-recall.lineage.test.ts`, `tests/core/brain/session-recall-private.test.ts`, `tests/core/brain/link-graph/session-mining.test.ts`, `tests/mcp/session-recall-tool.test.ts`, `tests/mcp/brain-tools-parity.test.ts`, `tests/helpers/tool-probe-catalogue.ts`, `tests/cli/brain-session-recall.test.ts`++Lane C - graded surfacing key and replay harness (t_107a3249):++- new `src/core/search/surfacing-key.ts` (shared pure key/tier calculator)+- modify `src/core/search/surfacing-gate.ts` (graded decision type, channel-aware input, binary projection retained)+- modify `src/core/brain/recall-inject.ts` (floor branches routed through the calculator)+- modify `src/core/brain/gate-telemetry.ts` (optional key/tier/channel payload, tier summary)+- modify `src/mcp/search-tools.ts` (owner of the file; toolBrainRecallGate response and telemetry thunk)+- new `src/core/bench/replay-fixture.ts`, `src/core/bench/replay.ts`+- modify `src/core/bench/failure-modes.ts` (close the not-scoreable caveat)+- append-only after Lane D's contract commits: `src/core/bench/phases.ts` (replay dispatch arm), `src/core/bench/types.ts` (suite registration types), `src/cli/brain/verbs/bench.ts` (registry entry)+- new tests `tests/core/bench/replay-fixture.test.ts`, `tests/core/bench/replay.test.ts`+- extend `tests/core/search/surfacing-gate.test.ts`, `tests/core/brain/recall-inject.test.ts`, `tests/hooks/recall-inject.test.ts`, `tests/mcp/recall-gate-telemetry.test.ts`, `tests/mcp/recall-gate-contract.test.ts`, `tests/mcp/recall-gate-turn-id.test.ts`, `tests/core/bench/failure-modes-baseline.test.ts`++Lane D - LongMemEval bench suite (t_607d429d):++- new `src/core/bench/longmemeval.ts` (parser, converter, abstention filter, metric constants, suite receipt)+- new `tests/fixtures/bench/longmemeval-sample.json`+- modify `src/cli/brain/verbs/bench.ts` (suite registry with capabilities, usage line, report printing)+- modify `src/core/bench/types.ts` (capabilities type, pinned-knobs type, report suite field)+- modify `src/core/bench/phases.ts` (BenchRunOptions growth, pin-driven benchSearchConfig, optional embeddings index phase, report family)+- modify `src/core/bench/run-store.ts` (pinned knobs folded into the checkpoint hash)+- modify `src/core/bench/judge.ts` (extended stdin payload)+- frozen `src/core/bench/locomo.ts`, `tests/core/bench/locomo.test.ts`, `tests/core/bench/fixture.test.ts` (fixture schema unchanged)+- new tests `tests/core/bench/longmemeval.test.ts`+- extend `tests/core/bench/phases.test.ts`, `tests/core/bench/run-store.test.ts`, `tests/cli/brain-bench.test.ts`++Integration lane:++- modify `docs/mcp.md`, `docs/cli-reference.md`, `CHANGELOG.md`, `package.json` plus the manifests synced by `scripts/sync-version.ts` (minor bump)+- census registration reconciliation across the ratchet tests listed above++## Risks and open questions++- **brain_search schema growth.** The tool is the primary agent-facing surface; the envelope exists only under the opt-in flag and the default response is fixture-pinned byte-identical. The append-only ownership split with Lane C (one file, two tool definitions) is mechanical but must be respected in every commit.+- **Query-cache compatibility.** The cache-key composition is a documented compatibility surface; the mode-on suffix keeps off-mode keys stable, but a mode-on key layout change orphans stale rows once. Rows live in the rebuildable search index, so the cost is a cold cache, never a wrong result.+- **Resume identity break.** Folding pinned knobs into the checkpoint hash means in-flight bench runs started before this change fail the resume guard. The failure is loud and named; the run is restarted, not silently mixed.+- **Census and ratchet drift.** The tool-ceiling equality test (115), the continuity reader and envelope censuses, the tool-probe catalogue and the parity tests arbitrate every surface growth; each moves only in the commit that grows its schema, and the integrator reconciles any drift.+- **Local CI versus operator reality.** LongMemEval numbers produced in CI come from the deterministic local provider through the apply-gated path; real-provider scores are an operator lane. The report carries the provider and model signature so numbers are never compared across signatures, and the embedding cache key includes that signature.+- **Threshold calibration.** The replay suite doubles as the measurement instrument for the channel admission constants; the constants land with their measured justification recorded in the module docblock and can be re-measured by re-running the suite. If the measured mcp/cli calibration disagrees with the 0.35 floor default before release, the recorded measurement wins and the docblock states it.+- **Envelope payload size on very large pools.** The plan-phase envelope lists candidate evidence ids and gaps; on very large pools it could grow. The round cap and the existing composite deadline bound the loop, and the envelope carries only ids and sub-queries, never hydrated content; if real fixtures still show oversized envelopes, the sub-query count limit tightens rather than the response shape growing a pagination axis.+- **Vector-cache arm isolation.** The shared embedding cache must key strictly on provider, model and text hash so the two arms never share a partially written file; the cache is written once per completed index phase (atomic write) before either arm reads it. If review finds an isolation hole, the named fallback is a per-run index plus an embedding-signature receipt compared across arms, decided with the measurement in hand.diff --git a/docs/brainstorm/recall-quality-wave/plan.md b/docs/brainstorm/recall-quality-wave/plan.mdnew file mode 100644index 00000000..a8b0fa8f--- /dev/null+++ b/docs/brainstorm/recall-quality-wave/plan.md@@ -0,0 +1,166 @@+# Recall quality wave 2 - implementation plan++Executed by the implement node with PARALLEL IMPLEMENTATION LANES. Lane D lands its two contract commits first; lanes A, B, C and the rest of D then run concurrently over disjoint files; the integrator finishes. Every task is atomic and commit-sized. No new MCP tools anywhere: the tool census is pinned at 115 (`tests/core/install/tool-ceiling.test.ts:348`), and every new recall surface rides an existing tool's operations, an existing CLI verb, or the bench suite registry. Every opt-in surface is default off with a byte-identical-off regression proof; failures are typed explicit errors, never silent fallbacks.++## Cross-lane contract++### (a) File ownership - every file has exactly one owner; overlap forbidden++- **Lane A** (iterative recall loop): `src/core/search/pipeline/iterative-recall.ts` (new), `src/core/search/decider-step.ts` (new), `src/core/search/coverage.ts`, `src/core/search/pipeline/second-pass.ts`, `src/core/search/search.ts`, `src/core/search/index.ts`, `src/core/search/types.ts`, `src/core/search/pipeline/outcome.ts`, `src/core/search/pipeline/attribution.ts`, `src/core/search/pipeline/cache-slot.ts`, `src/core/brain/retrieval-plan.ts`, and the A-lane tests listed per task.+- **Lane B** (coverage-first session recall): `src/core/brain/session-recall.ts`, `src/core/brain/thread-topics.ts` (new), `src/mcp/brain/recall-tools.ts`, `src/cli/brain/verbs/session-recall.ts`, `src/core/brain/entities/registry.ts` (read-side resolution only), and the B-lane tests listed per task. `src/core/brain/recall-budget.ts` is FROZEN: wrap `applyCharBudget` at the call site, never edit it.+- **Lane C** (graded surfacing + replay harness): `src/core/search/surfacing-key.ts` (new), `src/core/search/surfacing-gate.ts`, `src/core/brain/recall-inject.ts`, `src/core/brain/gate-telemetry.ts`, `src/core/bench/replay-fixture.ts` (new), `src/core/bench/replay.ts` (new), `src/core/bench/failure-modes.ts`, and the C-lane tests listed per task. Lane C additionally owns `src/mcp/search-tools.ts` as a file.+- **Lane D** (LongMemEval bench suite): `src/cli/brain/verbs/bench.ts`, `src/core/bench/types.ts`, `src/core/bench/phases.ts`, `src/core/bench/run-store.ts`, `src/core/bench/judge.ts`, `src/core/bench/longmemeval.ts` (new), `tests/fixtures/bench/longmemeval-sample.json` (new), and the D-lane tests listed per task. `src/core/bench/locomo.ts`, `tests/core/bench/locomo.test.ts` and `tests/core/bench/fixture.test.ts` are FROZEN for the wave and must stay green untouched.+- **Integrator**: docs pages, `CHANGELOG.md`, `package.json` + manifests synced by `scripts/sync-version.ts`, census registration fixes. No lane-owned source files.++### (b) The two shared files and their append-only splits++- `src/mcp/search-tools.ts`: Lane C owns the file and the `brain_recall_gate` tool definition, handler and telemetry thunk. Lane A holds append-only rights strictly limited to the `brain_search` tool definition and handler (iterative request fields, phase discriminator, cache-key suffix). No other region of the file may be touched by Lane A.+- Bench registration points (`src/core/bench/phases.ts` dispatch arm, `src/core/bench/types.ts` suite-registration types, `src/cli/brain/verbs/bench.ts` registry entry): Lane D owns all three. Lane C may append only its own `surfacing-replay` registration entries, and only after Lane D's two contract commits (Tasks 18 and 20) have landed.++### (c) Ordering - the bench contracts land FIRST++Lane D commits Task 18 (suite registry + per-suite capability declaration) and Task 20 (run-identity knob pinning) as its first two commits, before any other lane needs them and before D's own feature tasks. Lane C's replay-harness tasks (Tasks 15 and 16) depend on those two commits and build on top: the pure modules (`replay-fixture.ts`, `surfacing-key.ts`) can be written immediately, but the suite registration and phase dispatch wait. Lanes A and B depend on nothing and start immediately.++### (d) Dependency-wait rule++A lane whose upstream has not landed yet starts by writing its failing tests against the pinned contracts (they fail on the missing surface, which is the expected failure), then polls `git log -- <upstream files>` every 30 s for up to 12 min; after 30 min of waiting in total, escalate to the orchestrator instead of inventing the surface.++### (e) House rules++- Strict TDD: write the failing test first, run it, watch it fail with the expected error, then implement; refactor only with all tests green.+- One conventional commit per task (`feat(search): ...`, `feat(bench): ...`, `feat(brain): ...`); never bundle two tasks.+- Stage files by name; never `git add -A` or `git add .`; commit with `git commit --only <paths>`.+- Format and lint your own files before every commit; a green formatter and linter are a commit precondition, not end-of-PR cleanup. If the formatter touches files outside your lane, surface it instead of folding it in.+- Run tests with a throwaway HOME: `env HOME=$(mktemp -d) bun test <paths>`.+- Byte-identical-off proofs compare full serialized outcomes against frozen fixtures; a mode-on-but-inert comparison (mode on, no gaps, no operation requested) is part of every byte-identical test.+- Subprocess-spawning tests (fake judge commands) get explicit 20000 ms budgets; order-dependent assertions use sorted listings.++## Lane D - LongMemEval bench suite (contract commits first)++### Task 18: Suite registry and per-suite capability declaration (lane D, contract commit 1)+- **Files**: `src/cli/brain/verbs/bench.ts`, `src/core/bench/types.ts`, `src/core/bench/phases.ts`, `tests/cli/brain-bench.test.ts`, `tests/core/bench/phases.test.ts`+- **Acceptance**: a passing test drives the new registry mapping suite name to `{ loader, capabilities }`: `--suite longmemeval` reaches a stub loader, `--suite bogus` fails with the current message shape, omitting `--suite` stays byte-identical (locomo), capabilities ride `BenchRunOptions` set by the verb from the registry, and the default path still pins semantic off (`benchSearchConfig` assertion).+- **Depends on**: none (must be Lane D's first commit)++### Task 19: LongMemEval parser and converter (lane D)+- **Files**: `src/core/bench/longmemeval.ts` (new), `tests/fixtures/bench/longmemeval-sample.json` (new), `tests/core/bench/longmemeval.test.ts` (new)+- **Acceptance**: a passing test covers named parse errors, abstention questions excluded with the count recorded, direct gold-session-id join with unknown-id rejection, a converted fixture that round-trips `parseBenchFixture`, no reliance on `expected_text` for retrieval scoring, and an end-to-end `runMemoryBench` over the committed sample (the `tests/core/bench/locomo.test.ts` pattern).+- **Depends on**: Tasks 18, 20++### Task 20: Knob pinning into run identity (lane D, contract commit 2)+- **Files**: `src/core/bench/phases.ts`, `src/core/bench/types.ts`, `src/core/bench/run-store.ts`, `tests/core/bench/phases.test.ts`, `tests/core/bench/run-store.test.ts`+- **Acceptance**: a passing test pins a `SearchConfigOverrides`-shaped record on `BenchRunOptions`, applies it last via `resolveSearchConfig`, folds it into the checkpoint hash input, gives two runs with different pins different run ids, and fails the resume hash guard on a pin change; the default pin equals today's hardcoded semantic-off override so locomo report numbers stay identical.+- **Depends on**: Task 18 (same lane, lands immediately after)++### Task 21: Embedding capability path with a shared vector cache (lane D)+- **Files**: `src/core/bench/phases.ts`, `src/core/bench/types.ts`, `tests/core/bench/phases.test.ts`, `tests/core/bench/longmemeval.test.ts`+- **Acceptance**: a passing test declares the embeddings capability for the longmemeval registry entry, builds the disposable vault index through the apply-gated indexer options with the deterministic local provider (network-free), enables the semantic lane through the pin, asserts the embedding spend plan is surfaced and never silently bypassed, asserts a cache file under the runs dir keyed by provider+model+text hash makes both arms compare byte-identical vectors, and keeps the default-path semantic-off assertion green.+- **Depends on**: Tasks 18, 20++### Task 22: Strict recall_all@5 metric and report family (lane D)+- **Files**: `src/core/bench/phases.ts`, `src/core/bench/types.ts`, `src/cli/brain/verbs/bench.ts`, `tests/core/bench/phases.test.ts`, `tests/core/bench/longmemeval.test.ts`+- **Acceptance**: a passing test evaluates the persisted retrieval results at cutoff 5 over non-abstention questions and surfaces `longmemeval: { recall_all_at_5, abstention_excluded }` in report and CLI output with the quality, latency and context_cost families untouched and locomo reports byte-identical.+- **Depends on**: Tasks 19, 21++### Task 23: Judge glue for official prompts (lane D)+- **Files**: `src/core/bench/judge.ts`, `src/core/bench/longmemeval.ts`, `tests/core/bench/longmemeval.test.ts`+- **Acceptance**: a passing test extends the judge stdin payload with question, answer and gold when the suite provides them (absent for locomo, whose payload is unchanged), keeps the official prompt text as module constants pinned to a named LongMemEval revision, and runs end to end with a fake judge command echoing verdicts (explicit 20000 ms budget); the default judge stays skipped.+- **Depends on**: Task 19++## Lane A - iterative recall loop++### Task 1: Extract the marginal-value stop predicate (lane A)+- **Files**: `src/core/brain/retrieval-plan.ts`, `tests/core/brain/retrieval-plan.test.ts`+- **Acceptance**: a passing test calls the extracted predicate over a synthetic search-pool density curve (arbitrary density and elapsed-time samples, not the context pack) and asserts the stop verdict follows the advisor formula (0.25 floor fraction, p95 surcharge min 0.5 at 4000 ms scale, 0.5 max extra fraction); the advisor's `buildRetrievalPlan` output is byte-identical on the existing fixtures and every pre-existing test passes untouched.+- **Depends on**: none++### Task 2: Generalize the coverage gap signal into k sub-query groups (lane A)+- **Files**: `src/core/search/coverage.ts`, `src/core/search/pipeline/second-pass.ts`, `tests/core/search/coverage-targeted-recall.test.ts`, `tests/core/search/coverage-unmeasurable.test.ts`+- **Acceptance**: a passing test seeds a pool with k uncovered rare-term groups and asserts the generalized planner emits k groups ordered by significance; the single-group behavior for the existing round-two callers is byte-identical against a frozen fixture, and the unmeasurable-coverage case still yields zero groups.+- **Depends on**: none++### Task 3: Bounded round driver with deterministic sub-queries (lane A)+- **Files**: `src/core/search/pipeline/iterative-recall.ts` (new), `src/core/search/search.ts`, `src/core/search/index.ts`, `src/core/search/types.ts`, `tests/core/search/iterative-recall.test.ts` (new)+- **Acceptance**: a passing test runs a multi-hop seeded vault three ways: knob off produces an outcome byte-identical to the pre-change fixture (the `tests/core/search/two-pass.test.ts` kill-switch pattern, including mode-on-but-no-gaps); knob on runs bounded rounds that merge pools with round 2 recovering a chunk round 1 missed and the round cap respected; deadline expiry mid-loop degrades exactly as `tests/core/search/hybrid-deadline.test.ts` expects.+- **Depends on**: Tasks 1, 2++### Task 4: Decider envelope and commit validators (lane A)+- **Files**: `src/core/search/decider-step.ts` (new), `src/core/search/pipeline/iterative-recall.ts`, `tests/core/search/decider-step.test.ts` (new)+- **Acceptance**: a passing test builds the needs-llm-step envelope only when coverage gaps remain (never on a complete pool); the commit phase refuses unknown chunk ids, oversized or over-limit sub-queries, malformed shapes and an already-used round token with named typed errors; an accepted payload drives round N+1 with the pool growing only by the sub-query pulls.+- **Depends on**: Task 3++### Task 5: brain_search plan/commit round-trip (lane A)+- **Files**: `src/mcp/search-tools.ts` (append-only: brain_search tool definition and handler only), `src/core/search/pipeline/cache-slot.ts`, `tests/mcp/search.test.ts`, `tests/mcp/brain-search-reasons.test.ts`+- **Acceptance**: a passing test drives the MCP round-trip: the first call with the iterative flag returns a plan-phase response carrying the envelope and round token, the second call with the committed payload returns the final response; omitting the flag leaves the response byte-identical (existing `tests/mcp/search.test.ts` assertions untouched) and the cache key unchanged, while a mode-on call appends the new request fields to the cache-key suffix so plan and commit phases never collide with plain rows.+- **Depends on**: Task 4++### Task 6: Per-round outcome observability (lane A)+- **Files**: `src/core/search/types.ts`, `src/core/search/pipeline/outcome.ts`, `src/core/search/pipeline/attribution.ts`, `tests/core/search/two-pass.test.ts`+- **Acceptance**: a passing test reads per-round counts and stop reasons from the new optional outcome field with every existing attribution reason string unchanged; mode-off outcomes serialize without the field, byte-identical to the pre-change fixture.+- **Depends on**: Task 3++## Lane B - coverage-first session recall++### Task 7: Coverage-first thread selection core (lane B)+- **Files**: `src/core/brain/session-recall.ts`, `tests/core/brain/session-recall.coverage.test.ts` (new)+- **Acceptance**: a passing test imports a multi-segment lineage-linked thread and asserts the coverage call returns turns touching every detected facet, re-emitted in `compareRecords` chronological order with recomputable diagnostics; a grep call without the new operation returns byte-identical output against a frozen fixture (the omitted-operation convention, cf. `includeRaw`).+- **Depends on**: none++### Task 8: Adaptive topic budget (lane B)+- **Files**: `src/core/brain/thread-topics.ts` (new), `src/core/brain/session-recall.ts`, `tests/core/brain/thread-topics.test.ts` (new), `tests/core/brain/session-recall.coverage.test.ts`+- **Acceptance**: a passing test pins budget = clamp(distinct facets, floor 12, cap 16) with exported constants: a 40-facet thread caps at 16, a 3-facet thread floors at 12 and reports 3 realized topics honestly in diagnostics; the function is pure and deterministic across repeated calls.+- **Depends on**: Task 7++### Task 9: Typed infeasibility contract (lane B)+- **Files**: `src/core/brain/session-recall.ts`, `tests/core/brain/session-recall.coverage.test.ts`+- **Acceptance**: a passing test shrinks the character budget below the floor-weighted selection and asserts a typed error naming requested topics, kept topics and required chars; above the floor, drops appear in diagnostics and never silently; `applyCharBudget` stays frozen and its behavior for all other callers is unchanged (`tests/core/brain/recall-budget.test.ts` passes untouched).+- **Depends on**: Tasks 7, 8++### Task 10: MCP operation and CLI parity (lane B)+- **Files**: `src/mcp/brain/recall-tools.ts`, `src/cli/brain/verbs/session-recall.ts`, `src/cli/command-manifest.ts` (append-only), `src/cli/brain/help-text.ts` (append-only), `tests/mcp/session-recall-tool.test.ts`, `tests/mcp/brain-tools-parity.test.ts`, `tests/helpers/tool-probe-catalogue.ts`, `tests/cli/brain-session-recall.test.ts`+- **Acceptance**: a passing test calls the new coverage operation on brain_session_grep end to end with the typed infeasibility mapped to INVALID_PARAMS, the parity probe row and manifest entries pass, the optional brain_session_describe topic report renders the budget diagnostics, and `tests/core/install/tool-ceiling.test.ts` still pins 115 tools.+- **Depends on**: Tasks 7, 8, 9++### Task 11: Entity-thread wiring (lane B)+- **Files**: `src/core/brain/entities/registry.ts` (read-side resolution only), `src/core/brain/session-recall.ts`, `tests/core/brain/link-graph/session-mining.test.ts`, `tests/core/brain/session-recall.coverage.test.ts`+- **Acceptance**: a passing test resolves an entity key to its `session_entity_mention` rows and asserts a coverage call seeded by that key returns the turns that establish it, chronologically; an unknown key raises the same typed error family, never an empty silent result, and no new record kind is written (`tests/core/brain/continuity/reader-census.test.ts` and `record-envelope.test.ts` stay green untouched).+- **Depends on**: Task 7 (parallel with Tasks 8-10)++## Lane C - graded surfacing key and replay harness++### Task 12: Shared surfacing key calculator (lane C)+- **Files**: `src/core/search/surfacing-key.ts` (new), `src/core/search/surfacing-gate.ts`, `tests/core/search/surfacing-gate.test.ts`+- **Acceptance**: a passing test pins the graded shape `{ key, tier, admit, reason }` with admission from channel-calibrated absolute match quality (`idfWeightedCoverage`) and per-channel threshold constants exported; the structural suppressions stay named short-circuits, the binary `{retrieve, reason}` projection survives for the pinned contract tests, and the language-agnostic fails-open invariants in `tests/core/search/surfacing-gate.test.ts` hold unchanged.+- **Depends on**: none++### Task 13: Shared admission in the decision core (lane C)+- **Files**: `src/core/brain/recall-inject.ts`, `tests/core/brain/recall-inject.test.ts`, `tests/hooks/recall-inject.test.ts`+- **Acceptance**: a passing test asserts tier-boundary abstains (`below_floor`, `unmeasurable_quality`) decided through the shared calculator match the recorded decisions on a fixture corpus exactly, with the abstain reason vocabulary unchanged and the recorded empty-delivery invariant in `tests/hooks/recall-inject.test.ts` intact.+- **Depends on**: Task 12++### Task 14: Gate telemetry v2 (lane C)+- **Files**: `src/core/brain/gate-telemetry.ts`, `src/mcp/search-tools.ts` (owner: toolBrainRecallGate response and telemetry thunk), `tests/mcp/recall-gate-telemetry.test.ts`, `tests/mcp/recall-gate-contract.test.ts`, `tests/mcp/recall-gate-turn-id.test.ts`+- **Acceptance**: a passing test records optional key, tier and channel under the existing `recall_gate_telemetry` opt-in through the same lazily-evaluated gated thunk, summarizes counts by tier, keeps the fail-open contract and turn-id pins green, and leaves the opt-in-off path recording nothing; the continuity reader and envelope censuses stay green (no new record kind).+- **Depends on**: Task 12++### Task 15: Replay fixture loader (lane C)+- **Files**: `src/core/bench/replay-fixture.ts` (new), `tests/core/bench/replay-fixture.test.ts` (new)+- **Acceptance**: a passing test loads a committed session-shaped fixture into an ordered prompt sequence with expected surfacing outcomes (pure, deterministic, network-free) and converts a vault's `session_turn` records into the same fixture shape; the expected-outcome vocabulary is closed and unknown expectations are named rejections.+- **Depends on**: Tasks 18, 20 (bench framework contract commits)++### Task 16: Replay bench suite (lane C)+- **Files**: `src/core/bench/replay.ts` (new), `src/core/bench/phases.ts` (append-only dispatch arm), `src/core/bench/types.ts` (append-only registration types), `src/cli/brain/verbs/bench.ts` (append-only registry entry), `tests/core/bench/replay.test.ts` (new)+- **Acceptance**: a passing test replays a session containing a known should-abstain prompt and asserts a non-zero false-fire rate for a permissive gate and zero for the calibrated one, know_to_ask and false_fire scoring via `scoreProactiveRecall`, per-turn `injected_tokens` reporting, checkpoint and resume via the run store, and the phases invariant that an abstain injects nothing and costs zero.+- **Depends on**: Tasks 13, 14, 15++### Task 17: Close the not-scoreable caveat (lane C)+- **Files**: `src/core/bench/failure-modes.ts`, `tests/core/bench/failure-modes-baseline.test.ts`+- **Acceptance**: a passing baseline test asserts the gate's false-fire rate on the replay corpus is meaningfully bounded rather than near 1 by construction, and the rewritten docblock describes the graded gate instead of claiming the gate is unscoreable.+- **Depends on**: Task 16++## Integration++### Task 24: Integration gate - censuses, docs, version, full local gates (integrator)+- **Files**: `docs/mcp.md`, `docs/cli-reference.md`, `CHANGELOG.md`, `package.json` plus the manifests synced by `scripts/sync-version.ts`, census registration fixes+- **Acceptance**: the CI validate job's gates pass locally in CI order on the merged branch: format check, lint, the full test suite with a throwaway HOME, and manifest version sync (`sync-version.ts --check`, minor bump with the CHANGELOG entry and its compare link reference inside this pull request); the census pins are green - tool ceiling at 115, continuity reader and envelope censuses, tool-probe catalogue, parity tests - and `tests/core/bench/locomo.test.ts` passes untouched while the pre-existing byte-identical-off assertions inside `tests/core/bench/failure-modes-baseline.test.ts` and `tests/core/search/two-pass.test.ts` are preserved as the lanes' additions land.+- **Depends on**: Tasks 1-23diff --git a/docs/brainstorm/recall-quality-wave/variants.md b/docs/brainstorm/recall-quality-wave/variants.mdnew file mode 100644index 00000000..226afcc2--- /dev/null+++ b/docs/brainstorm/recall-quality-wave/variants.md@@ -0,0 +1,42 @@+# Variants - recall-quality wave++Audit trail for the brainstorm phase of the feature-release-playbook run on branch feat/recall-quality-wave, 2026-10-12. The consultant prompt is in `cli-output/prompt.md`. In this run the consultant role was performed by the same design agent that orchestrates the wave (no external consultant CLI was available); its reply is recorded verbatim in `cli-output/consultant.md` and repeated below as consultant work. The orchestrator decision follows the variants.++## Consultant variants (verbatim)++### Variant 1: Bench-first contract substrate with four parallel disjoint lanes+- **Approach**: Land the bench framework contracts first as two behavior-preserving commits owned by one bench lane: the per-suite capability declaration (a suite registry in the bench verb mapping suite to loader and capabilities) and run-identity knob pinning folded into the checkpoint hash. Then run four lanes in parallel over disjoint file sets - iterative recall loop, coverage-first session recall, graded surfacing key plus replay harness, and the rest of the LongMemEval suite - with the replay lane pinned as the one declared dependent on the two bench contract commits. A single integrator pass closes census reconciliation, docs, version bump and the full gate run.+- **Trade-offs**:+ - Maximal wall-clock parallelism: the two recall behavior lanes share no files with anything and start immediately.+ - Exactly one declared cross-lane dependency (replay harness waits on the bench contracts), so coordination cost is one paragraph of contract, not a meeting schedule.+ - The wave gains its measuring stick early: the replay suite and the LongMemEval lane can later produce before/after receipts for the behavior lanes inside the same pull request.+ - Cost: the contract must be written down precisely (who owns which file, append-only rights on the bench registration points), and the bench lane must commit its two contract commits before the replay lane starts.+- **Complexity**: medium+- **Risk**: low++### Variant 2: Serial quality stack in measurement-first order+- **Approach**: Build the four residues one at a time, each fully complete and green on the branch before the next starts, ordered so measurement always precedes behavior: LongMemEval bench suite, graded surfacing key and replay harness, coverage-first session recall, iterative recall loop. No lane structure, no cross-lane contracts; every change lands against a fully settled tree.+- **Trade-offs**:+ - Zero coordination cost and the simplest possible audit trail: each residue is a clean sequential commit series.+ - Every change is built against the previous change's final state, so no waiting rules or append-only ownership splits are needed.+ - Four sequential build-and-stabilize cycles stretch the release badly; the two recall behavior lanes are completely file-disjoint yet serialize unnecessarily.+ - Late lanes inherit churn from earlier lanes' unrelated refactors, widening the review surface per step.+- **Complexity**: small+- **Risk**: medium++### Variant 3: Two stacked half-waves - measurement, then behavior+- **Approach**: Split the wave into two stacked halves inside one pull request: half-wave one lands the two measurement residues (LongMemEval suite and the graded gate with its replay harness), half-wave two lands the two recall behavior residues (iterative loop and coverage-first session recall) and records their before/after numbers with the new harness. The halves share the branch sequentially; within each half the lanes run in parallel.+- **Trade-offs**:+ - Each half is independently verifiable, and the final pull request carries measured evidence for the behavior changes, which is the strongest possible receipt.+ - The behavior lanes are forced to wait for the full measurement half even though the iterative loop and coverage recall share nothing with the bench files.+ - Stacked half-wave history entangles reverts: rolling back one behavior lane drags the measurement lane it is stacked on.+ - The integrator faces two merge windows instead of one, doubling the census-reconciliation work.+- **Complexity**: medium+- **Risk**: medium++### Recommended: Variant 1+**Rationale**: The four residues are file-disjoint except one genuine seam - the replay harness needs the suite registry and knob pinning the bench lane owns - so parallel lanes with a single pinned dependency capture almost all of the serial variant's safety at a fraction of its wall clock. Landing the two behavior-preserving bench contracts first costs nothing and hands the wave its measuring stick before any behavior changes land, which is exactly the discipline the repo's byte-identical-off invariant wants. This is also the shape the previous recall-quality wave on this branch already executed successfully, so the tooling and audit conventions exist.++## Orchestrator decision++**Chosen: Variant 1 - bench-first contract substrate with four parallel disjoint lanes.** The consultant's recommendation is accepted without override. The recon touch-surface analysis confirms the four residues are file-disjoint with exactly one real dependency (Lane C's replay harness consumes Lane D's suite registry and run-identity knob pinning), so serializing or half-waving the wave would only add wall clock without removing any risk Variant 1 does not already pin. The branch itself just ran the prior recall-quality wave with this same substrate-then-lanes shape, so the append-only ownership mechanics, dependency-wait rule and census arbitration are proven here. One amendment to the consultant's sketch, recorded in the design doc and the plan contract: the bench framework files stay exclusively Lane D's except for Lane C's append-only suite-registration entries, exercisable only after the two contract commits land, keeping every commit single-owner at the file level.diff --git a/docs/cli-reference.md b/docs/cli-reference.mdindex b9798c83..c8878e99 100644--- a/docs/cli-reference.md+++ b/docs/cli-reference.md@@ -469,8 +469,8 @@ o2b brain generation-reports Record/list/summarise opt-in inbound LLM generatioo2b brain context-presets Show/suggest/diff read-only context budget presets (since v0.29.0)o2b brain pre-compact-extract Extract decision/commitment/outcome/rule/open-question continuity records from bounded text (since v0.29.0)o2b brain post-compact-audit Audit pinned-anchor survival after a compaction and re-assert drifted anchors (gated by post_compact_survival_audit)-o2b brain session-grep Search imported session recall raw turns and summary nodes (since v0.29.0)-o2b brain session-describe Count raw turns and deterministic summary depths for one session recall DAG (since v0.29.0)+o2b brain session-grep Search imported session recall raw turns and summary nodes; --operation coverage selects whole-thread coverage under --char-budget (since v0.29.0; coverage since v1.82.0)+o2b brain session-describe Count raw turns and deterministic summary depths for one session recall DAG; --topics adds the adaptive topic-budget report (since v0.29.0; --topics since v1.82.0)o2b brain session-expand Expand a session recall node to immediate sources and paginated raw turn content (since v0.29.0)o2b brain session-summary write|get|list a session-scoped structured digest (request/decisions/learnings/next_steps) (since v1.11.0)o2b brain idea-lineage Trace how a derived artifact was reached: observation -> synthesis -> conclusion over continuity sourceRefs or belief-evolution (since v1.11.0)@@ -529,8 +529,8 @@ o2b brain context-presets show [tight-context|long-context] --json; suggesto2b brain pre-compact-extract --session-id <id> --turn-start <id> --turn-end <id> --text <bounded-text> [--host <name>] [--max-chars <n>] [--json]o2b brain post-compact-audit [--session-id <id>] [--no-reassert] [--force] [--vault <path>] [--json] - reads { session_id, messages } JSON from stdin; gated off by default (post_compact_survival_audit), --force overrideso2b brain import-session <path> --recall [--recall-session-id <id>] [--recall-summary-group-size <n>] [--json]-o2b brain session-grep --query <text> [--session-id <id>] [--limit <n>] [--snippet-chars <n>] [--json]-o2b brain session-describe --session-id <id> [--json]+o2b brain session-grep --query <text> [--session-id <id>] [--limit <n>] [--snippet-chars <n>] [--json]; --operation coverage --char-budget <n> [--entity-key <key>] [--session-id <id>] [--json] - coverage-first thread selection; match-only flags refuse under coverage and --char-budget refuses under match (since v1.82.0)+o2b brain session-describe --session-id <id> [--topics] [--json]o2b brain session-expand <record-id> [--raw-limit <n>] [--cursor <offset>] [--json]o2b brain handoff <session-file> [--session-id <id>] [--format auto|claude|codex|hermes] [--json] - write Brain/handoffs/<date>-<scope>.md (since v0.37.0)o2b brain hygiene scan | apply --ids <id,...> [--detectors conflicts,dedup,freshness,usefulness,slug-collisions,tags,capture-scope] [--dry-run] [--json] - hygiene findings pipeline; review findings never execute (since v1.3.0); the default sweep runs every detector except the opt-in ones (since v1.64.0: `slug-collisions` is default-on and reports same-stem groups such as topic.md beside topic-2.md as info findings, `tags` is opt-in and audits inline body tags only - frontmatter tags arrays are out of scope; since v1.67.0 `capture-scope` is default-on and warns, with proposed action review, when a retrievable page of active knowledge cites only sources that are currently url-only; since v1.81.0 the detector also names a cited source whose durable archive entry under Brain/.archives/ is missing or no longer matches the hash stamped on the page)@@ -568,11 +568,13 @@ Trigger generation, brief delivery, and gate telemetry are pull-based or config-```texto2b brain continuity export --format atof|atif [--session <id>] [--month YYYY-MM] [--out <dir>] [--json] - read-only trajectory export of the continuity store; private records dropped, redacted text stays masked-o2b brain bench memory --fixture <name|path> [--resume <run-id>] [--runs-dir <dir>] [--json] - memory quality benchmark over a disposable fixture vault; quality, latency, and context cost reported separately; checkpoint/resume by run id; exit 1 on any failed question+o2b brain bench memory --fixture <name|path> [--suite <name>] [--resume <run-id>] [--runs-dir <dir>] [--json] - memory quality benchmark over a disposable fixture vault; quality, latency, and context cost reported separately; checkpoint/resume by run id; exit 1 on any failed question. Suites (since v1.82.0): longmemeval (strict recall_all@5 over the LongMemEval dataset shape; committed sample fixture, full dataset operator-supplied, judge glue over bench_judge_cmd) and surfacing-replay (replays a recorded prompt corpus through the shipped decision core and scores know_to_ask / false_fire)```The benchmark never touches the configured vault - the fixture materializes into `<runs-dir>/<run-id>/vault` (default runs dir `.open-second-brain/bench-runs/`, gitignored). The optional `bench_judge_cmd` config key (env `OPEN_SECOND_BRAIN_BENCH_JUDGE_CMD`) arms an advisory external judge; absent means the judge phase is skipped. The full observability contract (event kinds, gates, correlation ids, payload safety, schema version) lives in `docs/observability.md`.+Since v1.82.0 the verb's suite registry maps a `--suite` name to its loader plus a declared capability set (`{embeddings: boolean}`): omitting `--suite` stays the byte-identical default path, and the semantic lane is reachable only for a suite that declared the embeddings capability (longmemeval does; arming the pin is an API-only move this wave - the CLI exposes no knob or floor flag). The run identity folds the pinned search knobs and the proactive-recall admission floor into the checkpoint hash beside the fixture hash, so a resumed run that would mix configurations fails the identity guard by name instead of comparing two pipelines; in-flight runs started before the change fail the resume guard loudly and restart. `--suite longmemeval` converts the official LongMemEval dataset shape - abstention questions drop at conversion with the count recorded, gold sessions join by direct id membership and an unknown id is a named parse error - and reports the strict `longmemeval: {recall_all_at_5, abstention_excluded}` family beside the untouched quality, latency and context_cost families; the committed sample fixture `tests/fixtures/bench/longmemeval-sample.json` certifies CI and the full dataset is an operator-supplied path (never downloaded at run time). The judge glue reuses `bench_judge_cmd`: when the suite provides them, the stdin payload's questions carry `question`, `answer` and `gold` beside the usual result fields, and the official prompt text ships as module constants pinned to a named upstream revision, so the external command stays a dumb model call; suites without judge input keep the payload byte for byte. `--suite surfacing-replay` replays a recorded prompt corpus (a committed session fixture, or a vault's own session turns converted to the same shape) through the shipped decision core and scores the graded surfacing gate's know_to_ask / false_fire rates under the same denominations the proactive-recall metric uses, so the gate's calibration is a measured number a re-run re-measures.+### Externalized session payloads (payload registry)```text@@ -1331,6 +1333,31 @@ refused by the registry with its reason, not waved through. `dismiss`records the key in the artifact's dismissal set, and future mine runs skipit.+### Coverage-first session recall (since v1.82.0)++```text+o2b brain session-grep --operation coverage --char-budget <n> [--entity-key <key>] [--session-id <id>] [--json] - coverage-first thread selection: facets from the thread itself, fanned out under the adaptive topic budget, selected under the budget, returned chronologically with diagnostics+o2b brain session-describe --session-id <id> --topics [--json] - add the adaptive topic-budget report the coverage operation fans out under+```++`--operation coverage` replaces the grep's term matching with thread+coverage over the same lineage-scoped record set. The facets are the+thread's own - distinct mined entity keys and depth-1 summary clusters -+and the fan-out runs under the adaptive topic budget+`clamp(distinct facets, floor 12, cap 16)`: a 40-facet thread caps at 16,+a 3-facet thread floors at 12 and reports 3 realized topics honestly in+the diagnostics. The selection is re-emitted in chronological order under+the required `--char-budget` beside recomputable diagnostics; a budget+that cannot hold the floor-weighted selection is a typed error naming the+requested topics, the kept ones and the required characters - a retry+bound, never a silent truncation. `--entity-key` seeds the fan-out from+the `session_entity_mention` rows an import already mined - no new mining,+no new record kind - and an entity no record mentions is refused by name,+never answered with an empty result. The operations keep their flags to+themselves: `--query`, `--since`, `--before`, `--limit` and+`--snippet-chars` refuse under coverage, and `--char-budget` refuses under+match.+### Source distillation```text@@ -2517,6 +2544,54 @@ snapshot is arbitrated by that same live filter. A mixed filter mapstraddles the tiers by design. Absent filters compile byte-identical SQL tobefore this wave.+### Iterative recall (since v1.82.0)++The single self-correcting second pass generalizes into a bounded loop.+`search_iterative_recall_enabled` (`OPEN_SECOND_BRAIN_SEARCH_ITERATIVE`,+default off) lets gap-driven rounds run past it: each round re-measures+pool coverage, emits follow-up sub-queries from the uncovered rare-term+groups, merges what they recover into the same ranked pool, and stops on+coverage completeness, a round that recovers nothing, the marginal-value+stop the retrieval advisor already used, the round cap+(`search_iterative_recall_max_rounds` /+`OPEN_SECOND_BRAIN_SEARCH_ITERATIVE_MAX_ROUNDS`, default 2, clamped to 8)+or the composite deadline. With the knob off the outcome and the+query-cache keys are byte-identical; the cache suffix that separates+iterative rows exists only in the opt-in mode.++The deterministic coverage planner is the floor and needs no model. The+additive decider rounds ride the MCP `brain_search` tool as a plan/commit+round-trip, with no CLI mirror this wave: a call with `iterative: true`+whose measurable gaps survive the deterministic budget pauses with+`iterative.phase: "needs-llm-step"` - the decider envelope, the candidate+pool ids, the uncovered gaps and an opaque single-use round token - and+the caller re-invokes with `iterative_token` and `iterative_payload`+(`{evidence, subQueries}`), validated in full before any pull runs. A+replayed token refuses `token_used`, a mismatched one `token_mismatch`,+and a commit with the loop disabled is refused by name instead of reading+as a plain answer. The round-trip runs on the single-vault path only: any+iterative field beside `global: true` is refused at the argument layer.+Every loop that ran at least one round - a committed call, or a plain+final - answers with an `iterative` marker at `phase: "final"` carrying+the per-round records and the stop reason; a call the mode did nothing+for carries no marker at all.++### The graded surfacing key (since v1.82.0)++Recall admission has one shared calculator. The recall gate's+prompt-structural predicate stays the structural pre-tier with its named+short-circuits, and admission is graded from absolute match quality - the+IDF-weighted coverage a search outcome already reports - calibrated per+transport channel (`mcp`, `cli`, `hook`), each floor an exported module+constant at the hook's 0.35; the fused composite stays an ordering signal+and is never a threshold basis. `brain_recall_gate` and the recall-inject+hook's floor branches consume the same `{key, tier, admit, reason}`+decision, so a tier boundary answers with the same reason on every+channel, and the binary `{retrieve, reason}` projection survives+unchanged for existing callers. Gate telemetry under the existing+`recall_gate_telemetry` opt-in records the key, the tier and the channel+on measured decisions, and its summary counts by tier.+### The reserved visibility token (since v1.54.0)```textdiff --git a/docs/mcp.md b/docs/mcp.mdindex b0e8fa0d..3d1fee53 100644--- a/docs/mcp.md+++ b/docs/mcp.md@@ -378,9 +378,9 @@ flags for a narrower per-process full server.| `brain_audit` | Read-only per-preference mutation trail (create / promote / update / retire / merge) with agent, reason, revision + content-hash before/after. | `pref_id` || `brain_brief` | Read-only Brain summary for any window: `view: morning \| daily \| weekly \| monthly \| operator \| digest`. | `view` || `brain_analytics` | Read-only Brain analytics for any lens: `view: timeline \| attention_flows \| belief_evolution \| concept_synthesis \| dedup`. `view=dedup` summarises the persisted exact-hash ingest dedup records into a trend plus a per-source re-ingest ranking; every count is an exact sha-256 drop, never a semantic figure (the semantic detectors nominate merge candidates and never drop). | `view` |-| `brain_search` | Read-only vault search with optional structured query lanes, explicit focus hints, time ranges, evidence-pack diagnostics, a selectable recall `profile` (`fast \| balanced \| thorough`), an FTS `match_mode` (`all` \| `any`), and since v1.80.0 a pushed `kind` filter (`page` \| `section`) plus SQL pushdown for the promoted `properties` keys. | `query` |+| `brain_search` | Read-only vault search with optional structured query lanes, explicit focus hints, time ranges, evidence-pack diagnostics, a selectable recall `profile` (`fast \| balanced \| thorough`), an FTS `match_mode` (`all` \| `any`), a pushed `kind` filter (`page` \| `section`) plus SQL pushdown for the promoted `properties` keys (since v1.80.0), and since v1.82.0 an opt-in iterative recall loop (`iterative`, `iterative_token`, `iterative_payload`) whose surviving coverage gaps pause with a plan the caller answers. | `query` || `brain_recall_feedback` | Record explicit up/down recall feedback for one search result; feeds the deterministic learned-weight fold. | `query`, `result_path`, `verdict` |-| `brain_recall_gate` | Read-only classifier for whether an automatic recall attempt should run; returns `retrieve` plus a stable reason. When the caller passes `scores` AND `match_quality` (the `idf_weighted_coverage` a search outcome reports - the two stand or fall together, and an incomplete pair is refused), also attaches an adequacy verdict (`sufficient` \| `weak` \| `insufficient`), a recommended action (`proceed` \| `re_recall` \| `abstain`), and an optional `escalate` flag. The LEVEL is decided by `match_quality` alone; the scores decide only the usable-result count. Thresholds via `recall_adequacy_sufficient` / `recall_adequacy_weak` / `recall_adequacy_min_results`. | `prompt` |+| `brain_recall_gate` | Read-only classifier for whether an automatic recall attempt should run; returns `retrieve` plus a stable reason. When the caller passes `scores` AND `match_quality` (the `idf_weighted_coverage` a search outcome reports - the two stand or fall together, and an incomplete pair is refused), also attaches an adequacy verdict (`sufficient` \| `weak` \| `insufficient`), a recommended action (`proceed` \| `re_recall` \| `abstain`), and an optional `escalate` flag. The LEVEL is decided by `match_quality` alone; the scores decide only the usable-result count. Thresholds via `recall_adequacy_sufficient` / `recall_adequacy_weak` / `recall_adequacy_min_results`. Since v1.82.0 a measured call also returns the shared graded surfacing key (`key`, `tier`) beside the binary decision. | `prompt` || `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`. Takes the same adequacy pair as `brain_recall_gate` under its own spelling, `recall_scores` AND `match_quality`: both or neither, an incomplete pair is refused, and the schema states it as `dependentRequired` keyed on this tool's own scores name. | `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; since v1.80.0 the `dead_weight` operation reports in-scope pages no recorded recall ever surfaced. | `operation` |@@ -396,8 +396,8 @@ flags for a narrower per-process full server.| `brain_pre_compact_extract` | Extract decision/commitment/outcome/rule/open-question records from bounded text into continuity storage. | `session_id`, `turn_start`, `turn_end`, `text` || `brain_hygiene` | Memory hygiene: `scan` findings (conflicts, dedup, freshness, usefulness; since v1.64.0 `slug-collisions` is default-on — same-stem allocation residue such as `topic.md` beside `topic-2.md` — and `tags` is opt-in, auditing inline body tags only, never frontmatter tags arrays; since v1.67.0 `capture-scope` is default-on and warns when active knowledge rests only on `url-only` sources; the default is the sweep of every registered detector except the opt-in ones), `apply` selected ids, `refresh` stale pages; since v1.81.0 `archive_get` resolves an ingest summary's `source_archive_hash` to its archived bytes under `Brain/.archives/` (local reach only, and the `capture-scope` scan also names a cited source whose archive entry is missing or mismatched). Resolver command comes from `_brain.yaml` only. When `hygiene_digest_enabled` is on in the machine config, the same default-sweep findings are also pushed at turn end as a one-line digest (Stop hook, once per change), so this pull surface doubles as a push channel. With the optional `dedup` decision-model use in enforce, `scan` dedup findings carry an advisory `decision_model` verdict; `apply` never reads it. | `mode` || `brain_anticipatory_context` | Turn-specific context bundle kept warm by lifecycle hooks, keyed by the session's lineage root; reports `cache_state` warm / stale / miss. | `session_id` |-| `brain_session_grep` | Search imported session recall raw turns and deterministic summary nodes. | `query` |-| `brain_session_describe` | Describe raw-turn counts and summary depths for one imported session recall DAG. | `session_id` |+| `brain_session_grep` | Search imported session recall raw turns and deterministic summary nodes; since v1.82.0 `operation: "coverage"` runs the coverage-first thread selection under a `char_budget` instead of a grep. | `query` |+| `brain_session_describe` | Describe raw-turn counts and summary depths for one imported session recall DAG; `topics: true` adds the adaptive topic-budget report the coverage operation fans out under (since v1.82.0). | `session_id` || `brain_session_expand` | Expand a raw or summary session recall node to immediate sources and paginated raw turn content. | `id` || `brain_sources` | Read-only dashboard of signals grouped by (agent, source_type) with active/processed and distinct-topic counts. | — || `brain_create_note` | Write an actual vault note file (path + frontmatter + content) atomically inside the vault. Distinct from `brain_note` (log append); refuses traversal, the Brain root, excluded paths, any destination outside the declared write binding, and — by default — clobbering. Opt-in: `if_exists: "skip"` returns `outcome: "skipped"` instead of creating, `strict` validates the document before writing and reports coded violations, and `template` + `template_variables` render the body through a closed two-construct grammar (`{{name}}` substitution; `{{#name}}…{{/name}}` presence sections and list iteration with `{{.}}`). Unknown placeholders are left intact. | `path` |@@ -539,6 +539,63 @@ cleanup removes the source's orphaned archive entries best-effort, and`brain_session_summary` `get` and `list` omit the `session_id` key of adigest that has no session instead of answering `""`, matching theno-session read rule every continuity reader applies.+Since v1.82.0 `brain_search` can keep querying after the single+self-correcting second pass: `iterative: true` opts one query into the+bounded iterative recall loop, which re-measures pool coverage each round,+emits follow-up sub-queries from the uncovered rare-term groups, and merges+what they recover into the same ranked pool, until coverage completes, a+round stops paying, the round cap or the composite deadline is reached, or+a round recovers nothing. The loop is inert unless the operator's+`search_iterative_recall_enabled` knob is on+(`OPEN_SECOND_BRAIN_SEARCH_ITERATIVE`; the round cap+`search_iterative_recall_max_rounds` /+`OPEN_SECOND_BRAIN_SEARCH_ITERATIVE_MAX_ROUNDS` defaults to 2 and clamps+to 8), and with the knob off the response and the query-cache keys are+byte-identical - the cache suffix that separates iterative rows exists+only in the opt-in mode. When measurable gaps survive the deterministic+budget, the call pauses instead of finishing: the response carries an+`iterative` marker at `phase: "needs-llm-step"` with the decider envelope+(`llm_step`), the candidate `pool_ids` the decider selects evidence from,+the uncovered `gaps`, and an opaque single-use round `token`. The caller+re-invokes with `iterative_token` plus `iterative_payload`+(`{evidence: [chunkId, ...], subQueries: [...]}`), which is validated in+full before any pull runs: unknown chunk ids, oversized or over-limit+sub-queries, sub-queries carrying no significant terms, a replayed token+(`token_used`) and a mismatched one (`token_mismatch`) are typed refusals+surfaced as caller errors, and a fully-formed commit arriving while the+loop is disabled is refused by name instead of reading as a plain answer.+The round-trip is a single-vault loop: any `iterative` field combined with+`global: true` is refused by name at the argument layer, so no iterative+field ever reaches the federated legs. A committed call, and a plain call+whose loop ran at least one gap-driven round, answer with the same marker+at `phase: "final"`, carrying the per-round records (the terms, the group+count, what was added, the elapsed time, and whether the deterministic+floor or the decider authored the sub-queries) and the `stop_reason`+(`coverage_complete`, `no_sub_query`, `no_progress`, `round_cap`,+`marginal_value`, `deadline`, `decider_round`); a call the mode did+nothing for carries no marker at all, so the serialized outcome stays+byte-identical whenever the mode did nothing.++Since v1.82.0 `brain_session_grep` also answers `operation: "coverage"`:+the coverage-first thread selection over the same lineage-scoped record+set. Facets come from the thread itself - distinct mined entity keys and+depth-1 summary clusters - and fan out under the adaptive topic budget+`clamp(distinct facets, floor 12, cap 16)`; the selected turns return in+chronological order under the required `char_budget` beside recomputable+diagnostics that report the realized topic count honestly. `entity_key`+optionally seeds the fan-out from the session-entity-mention rows an+import already mined, and an entity no record mentions is refused by name,+never answered with an empty result. The operations keep their arguments+to themselves: `char_budget` under `match`, and `query`, `since`,+`before`, `limit`, `snippet_chars`, `include_raw` and `raw_budget_chars`+under `coverage`, are each refused as not applicable. A budget that cannot+hold the floor-weighted selection is a typed infeasibility mapped to+`INVALID_PARAMS`, naming the requested topics, the kept ones and the+required characters - a retry bound, never a silent truncation.+`brain_session_describe` accepts `topics: true`, which adds the+`topic_report` the coverage operation fans out under (the detected facets,+the budget and the realized topics); without it the response is+byte-identical.`brain_context_presets` supports `operation: "show"|"suggest"|"diff"`; and`brain_generation_reports` supports `action: "record"|"list"|"summary"` -`record` is gated (default off) by a per-call `enable` flag or the@@ -565,7 +622,15 @@ to its owning vault at the configuration level. `brain_idea_lineage` accepts `id`explicit`; `explicit: true` always returns `retrieve: true`. Sincev1.69.0 it also accepts an optional `turn_id` (a string of at most 512characters), recorded on the `gate_telemetry` record when that telemetry-is on.+is on. Since v1.82.0 a call that carries the scores and `match_quality`+pair also returns the shared graded surfacing key beside the binary+decision: `key` is the measured match quality the admission floor reads+(null exactly where nothing was measurable, a structurally suppressed+prompt) and `tier` is the closed admission vocabulary (`explicit`,+`suppressed`, `admitted`, `below_floor`, `unmeasurable_quality`); without+a measurement both fields are absent and the response is byte-identical.+The recall-inject hook's floor branches consume the same calculator, so a+tier boundary answers with the same reason on every channel.Optional decision-model `answerable` signal (see[decision-models/answerable.md](decision-models/answerable.md)): with rerank@@ -1221,7 +1286,11 @@ aging inbox signals.decision when the `recall_gate_telemetry` config key is `"true"`(default off) - decision, stable reason, host, SHA-256 prompt prefix;never the raw prompt. `brain_recall_telemetry` gains `gate_list` /-`gate_summary` operations.+`gate_summary` operations. Since v1.82.0 a record whose call carried a+measured quality also carries the graded surfacing key - `key`, `tier`+and the `channel` the decision arrived over - and `gate_summary` counts+the measured records by tier; the opt-in-off path records nothing, and no+new record kind exists.The MCP server emits one `mcp_route_latency` continuity record per toolcall when the `mcp_route_metrics_enabled` config keydiff --git a/docs/observability.md b/docs/observability.mdindex b0174511..6f5c3a5a 100644--- a/docs/observability.md+++ b/docs/observability.md@@ -135,7 +135,7 @@ Every continuity record shares one envelope, and exactly these eight fields in t|---|---|---|| `recall_telemetry` | opt-in per call (`telemetry` option/param); the prompt-time hook emitter is gated by `recall_inject_enabled` instead | `packContext` (`mode: context_pack`), `buildPreCompressPack` (`mode: pre_compress`), `brain_search` MCP handler (`mode: search`), `brain_query` MCP handler (`mode: query`, since v0.40.0 - payload carries the query kind only, never the supplied preference id / topic / timestamp), and since v1.46.0 the `UserPromptSubmit` recall-inject hook (`mode: search`, `channel: hook`, mapping its inject / abstain / error decision onto `ok` / `empty` / `error`; with the optional `recall_inject` decision-model use in `shadow` or `enforce`, `metadata` gains a `decision_model` object - `mode`, `outcome` (`ok`, `not_sent` or `degraded`), `latency_ms`, `notes_dropped`, `abstained` - and the abstain reason `decision_model_abstain`, never prompt or note text; see `docs/decision-models/recall-inject.md`) || `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; a call carrying `decision_answerable` while that decision-model use is on adds `adequacy_level` and `decision_answerable` (`probability`, `disagrees`); since v1.69.0 a call carrying `turn_id` records it under `turn_id`, which the read-model lifts like every other turn id |+| `gate_telemetry` | config key `recall_gate_telemetry` (default off) | `brain_recall_gate` MCP handler; a call carrying `decision_answerable` while that decision-model use is on adds `adequacy_level` and `decision_answerable` (`probability`, `disagrees`); since v1.69.0 a call carrying `turn_id` records it under `turn_id`, which the read-model lifts like every other turn id; since v1.82.0 a call that carried a measured quality also records the graded surfacing key - `key` (null exactly where nothing was measurable), `tier` and the `channel` the decision arrived over - and the summary counts the measured records by tier (`by_tier`) || `negative_recall` | config key `recall_gate_telemetry` (default off - the SAME gate as `gate_telemetry` above, so one config decision governs both observations the recall gate makes) | `brain_recall_gate` MCP handler on the zero-usable-result path only (`emitNegativeRecallTelemetry` in `src/core/brain/gate-telemetry.ts`) - one record per gate call whose caller reported no usable result, carrying the typed corpus verdict (`state`, `complete`, the named `unknown_reason` when the verdict is `unknown`, `reason`) plus the reduced coverage receipt when one could be built (`coverage_digest`, `documents`, `chunks`, `schema_version`, `embedding_signature`, `last_indexed_at`, `scope`, `unindexed_roots`). Two receipt fields are not copied into the payload: `index_path` is deliberately dropped - a host filesystem path is not vault content and these records sync between devices, and the digest already binds it; the `embeddings` census the receipt carries is likewise absent from the payload and likewise bound by `coverage_digest`, so a reader comparing two records still sees a keyword-only index differ from a fully embedded one. Same prompt invariant as `gate_telemetry`: a SHA-256 prefix (`prompt_hash`) and the length (`prompt_chars`), never the prompt. A call with usable results writes NO record, so a corpus statement is never invented for an attempt that had one || `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, plus the optional `decision_ms` and allowlisted `stages` timings |@@ -220,6 +220,6 @@ No-consumer regression tests cover each gated surface, so a future call site can- `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`.-- `o2b brain bench memory` measures memory quality over disposable fixture vaults and reports quality, latency, context cost, and failure modes as separate families (`o2b.bench.v2` report schema). Beyond the retrieval categories it scores three failure modes the retrieval questions cannot see: `proactive_recall` drives `decideRecallInject` over the fixture and reports `know_to_ask_failure_rate` and `false_fire_rate` (both denominated in decisions, so a strategy that always injects scores worse than one that abstains correctly); `write_fidelity` grades the provenance that survives the shipped extraction, insertion and dedup path with no model call; `source_isolation` asserts on delivered context-pack contents under a requested owner scope and gates at zero. `context_cost.avg_injected_tokens` is `estimateTokens` over the strings the bench actually injected — the suite's one token estimator. Two things the numbers do NOT say: `recall_inject_enabled` is off by default, so the proactive metric describes a capability rather than delivered behaviour, and `integrity.owner_scope_delivery` is off by default, so an isolation fixture must set it to `fail` or the gate is vacuous. The committed baseline is `tests/fixtures/bench/failure-modes.baseline.json`, compared by `tests/core/bench/failure-modes-baseline.test.ts` inside the ordinary `bun test` gate.+- `o2b brain bench memory` measures memory quality over disposable fixture vaults and reports quality, latency, context cost, and failure modes as separate families (`o2b.bench.v2` report schema). Beyond the retrieval categories it scores three failure modes the retrieval questions cannot see: `proactive_recall` drives `decideRecallInject` over the fixture and reports `know_to_ask_failure_rate` and `false_fire_rate` (both denominated in decisions, so a strategy that always injects scores worse than one that abstains correctly); `write_fidelity` grades the provenance that survives the shipped extraction, insertion and dedup path with no model call; `source_isolation` asserts on delivered context-pack contents under a requested owner scope and gates at zero. `context_cost.avg_injected_tokens` is `estimateTokens` over the strings the bench actually injected — the suite's one token estimator. Two things the numbers do NOT say: `recall_inject_enabled` is off by default, so the proactive metric describes a capability rather than delivered behaviour, and `integrity.owner_scope_delivery` is off by default, so an isolation fixture must set it to `fail` or the gate is vacuous. The committed baseline is `tests/fixtures/bench/failure-modes.baseline.json`, compared by `tests/core/bench/failure-modes-baseline.test.ts` inside the ordinary `bun test` gate. Since v1.82.0 the verb's suite registry maps a `--suite` name to its loader plus a declared capability set (`{embeddings: boolean}`; omitting `--suite` stays the byte-identical locomo default), the run identity folds the pinned search knobs and the proactive-recall admission floor into the checkpoint hash beside the fixture hash - a resumed run that would mix configurations fails the identity guard by name - and two suites join locomo: `--suite longmemeval` scores the LongMemEval dataset shape with the strict `longmemeval: {recall_all_at_5, abstention_excluded}` family (the committed sample fixture certifies CI, the full dataset is operator-supplied, and the judge rides `bench_judge_cmd` with `question`/`answer`/`gold` added to the stdin payload only for suites that provide them; the embeddings capability is apply-gated and its arming is API-only this wave, with a shared provider+model+text-hash vector cache under the runs dir), and `--suite surfacing-replay` replays a recorded prompt corpus through the shipped decision core and scores the graded surfacing gate's know_to_ask / false_fire rates, which closes the caveat that the structural gate alone was not scoreable: the graded admission key is a measured bound, and the replay suite is the instrument that re-measures it.Consumers should treat unknown record kinds and unknown payload fields as fine - skip what you do not recognize (the store and read-model already behave this way).diff --git a/openclaw.plugin.json b/openclaw.plugin.jsonindex 41161dde..0c15e40f 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.81.1",+ "version": "1.82.0","activation": { "onStartup": true },"skills": ["./skills"],"contracts": {diff --git a/package.json b/package.jsonindex faf5723b..c5c3309a 100644--- a/package.json+++ b/package.json@@ -1,6 +1,6 @@{"name": "open-second-brain",- "version": "1.81.1",+ "version": "1.82.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 25ee9ae9..a78a7822 100644--- a/plugin.yaml+++ b/plugin.yaml@@ -1,5 +1,5 @@name: open-second-brain-version: "1.81.1"+version: "1.82.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 c56952fe..842c0b59 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.81.1",+ "version": "1.82.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/codex/README.md b/plugins/codex/README.mdindex 975be39c..9bb971bf 100644--- a/plugins/codex/README.md+++ b/plugins/codex/README.md@@ -98,8 +98,8 @@ The full router with readiness criteria is [`install.md`](https://github.com/ite- **Preferences that learn and expire.** Signals, a deterministic dream pass, confidence and retirement: [how it works](https://github.com/itechmeat/open-second-brain/blob/main/docs/how-it-works.md#a-preferences-lifecycle).- **Reversible changes.** Brain mutations take a snapshot first; `o2b brain rollback` restores it: [snapshots](https://github.com/itechmeat/open-second-brain/blob/main/docs/how-it-works.md#snapshots-and-rollback).- **Attributed writes.** `o2b brain writes` lists every note write by agent and device, `writes revert` plans a restore, `o2b brain freeze` stops all writers, and `o2b brain log verify` checks the hash-chained log: [Brain CLI](https://github.com/itechmeat/open-second-brain/blob/main/docs/cli-reference.md#brain-observing-memory).-- **Search.** Keyword search with an optional semantic lane, result explanations, recall profiles and compact cards: [search CLI](https://github.com/itechmeat/open-second-brain/blob/main/docs/cli-reference.md#search), [ranking](https://github.com/itechmeat/open-second-brain/blob/main/docs/how-it-works.md#full-text-search).-- **Session recall.** Import agent transcripts already on disk and search them: [session logs](https://github.com/itechmeat/open-second-brain/blob/main/docs/cli-reference.md#session-logs-this-machine-already-has-since-v1500).+- **Search.** Keyword search with an optional semantic lane, result explanations, recall profiles and compact cards; an opt-in iterative loop (`search_iterative_recall_enabled`, default off) keeps querying when coverage gaps survive, pausing with a plan the caller answers through `brain_search`'s round trip: [search CLI](https://github.com/itechmeat/open-second-brain/blob/main/docs/cli-reference.md#search), [iterative recall](https://github.com/itechmeat/open-second-brain/blob/main/docs/cli-reference.md#iterative-recall-since-v1820), [ranking](https://github.com/itechmeat/open-second-brain/blob/main/docs/how-it-works.md#full-text-search).+- **Session recall.** Import agent transcripts already on disk, search them, or select whole-thread coverage under a character budget (`o2b brain session-grep --operation coverage --char-budget <n>`, with `--entity-key` seeding the fan-out from mined entity mentions): [session logs](https://github.com/itechmeat/open-second-brain/blob/main/docs/cli-reference.md#session-logs-this-machine-already-has-since-v1500), [coverage](https://github.com/itechmeat/open-second-brain/blob/main/docs/cli-reference.md#coverage-first-session-recall-since-v1820).- **Hygiene.** `o2b brain hygiene scan` finds contested, duplicate, stale and unused memories; `apply` runs only the findings you pick: [maintenance](https://github.com/itechmeat/open-second-brain/blob/main/docs/cli-reference.md#maintenance-and-operator-surfaces).- **Claim ledger.** `o2b brain truth ingest` records an entity claim with an optional validity window (`--valid-from`/`--valid-until`; with the flags absent, a window on the source record's frontmatter is adopted and frozen at ingest), `truth events` recalls a windowed slice of the ledger, and `truth state` grounds an agent-stated claim with an anchoring verdict - committed, or reported back with reason codes. `truth state` accepts an optional opaque `--sample-id` naming the context-pack sample the claim drew on, and claim reads report the receipt and outcome provenance behind it at the caller's reach - "receipt known, outcome unknown", never an invented verdict: [entity truth CLI](https://github.com/itechmeat/open-second-brain/blob/main/docs/cli-reference.md#entity-truth-and-self-improving-dream-since-v0430).- **Corrections.** `o2b brain lifecycle correct <target>` reports a correction's blast radius and retires the affected records - validity-closed by default, tombstoned with `--flatly-wrong`, dry run by default and `--apply` to write. A retired record that recall can still serve is served only beside its correction, never alone: [belief lifecycle CLI](https://github.com/itechmeat/open-second-brain/blob/main/docs/cli-reference.md#belief-lifecycle-and-decision-memory-since-v1330).@@ -123,7 +123,7 @@ The full router with readiness criteria is [`install.md`](https://github.com/ite## What is new-1.81.0 is the answer-trust release: it narrows the gap between what an agent was given and what its answer can be believed on. A Stop-hook step verifies the quotations in the assistant's answer against the note cited for them or the evidence recall actually injected (`quote_check.recall|active|subagent` in `Brain/_brain.yaml`, each `off|shadow|enforce`, default `shadow` - annotate-only, one `additionalContext` note per turn; `enforce` adds one Brain-log record per turn). `o2b brain truth state` accepts an optional opaque `--sample-id` naming the context-pack sample a claim drew on, and claim reads report the receipt and outcome provenance behind it at the caller's reach. Trusted local-file ingest now archives a source's bytes content-addressed under `Brain/.archives/` (redacted before persist, refused past 1 MiB, never pruned) with the hash stamped on the summary page; the capture-scope hygiene detector and a count-only doctor section name missing or mismatched evidence, and `brain_hygiene` `archive_get` reads an entry back at local reach. A record with no session id is read as no-session everywhere - scoped recall excludes it, grouping skips it, the session digest omits the key - dissolving the phantom blank-session bucket, with a count-only `blank-session-identity` doctor check for what older writers left behind. A repair lane closes the outstanding review findings: attribute narrowing in search falls a document whose indexed snapshot went stale through to the live filter instead of silently excluding it. Every release is described in the [CHANGELOG](https://github.com/itechmeat/open-second-brain/blob/main/CHANGELOG.md).+1.82.0 is the recall-quality release: it widens what recall reaches and makes every surfacing decision measurable. `brain_search` gains a bounded iterative recall loop (`search_iterative_recall_enabled`, default off, byte-identical off): when coverage gaps survive the deterministic rounds, the call pauses with a plan - the decider envelope, the candidate pool and an opaque single-use round token - and the caller commits `{evidence, subQueries}` back through `iterative_token`/`iterative_payload` to run one validated round more, with per-round records and the stop reason on the final marker. `o2b brain session-grep --operation coverage --char-budget <n>` selects whole-thread coverage instead of grep matches - facets from the thread's own mined entity keys and summary clusters, fanned out under an adaptive topic budget (floor 12, cap 16), returned chronologically with diagnostics - and `o2b brain session-describe --topics` renders the topic report. Recall admission moves to one shared graded surfacing key: the recall-inject hook and `brain_recall_gate` grade the same channel-calibrated match quality against the same floor, gate telemetry records key, tier and channel under the existing opt-in, and the bench scores it all - a suite registry gains a LongMemEval lane with a strict `recall_all@5` report family and judge glue over `bench_judge_cmd`, plus a surfacing-replay suite that replays recorded prompts through the shipped decision core. Every release is described in the [CHANGELOG](https://github.com/itechmeat/open-second-brain/blob/main/CHANGELOG.md).## Documentationdiff --git a/plugins/hermes/_schemas.py b/plugins/hermes/_schemas.pyindex 06836af7..ae3ca375 100644--- a/plugins/hermes/_schemas.py+++ b/plugins/hermes/_schemas.py@@ -242,219 +242,226 @@ STATIC_TOOL_SCHEMAS: tuple[dict[str, Any], ...] = ({'name': 'brain_feedback','filtering.'}},'additionalProperties': False}},{'name': 'brain_search',- 'description': 'Full-text search across the vault. Optional semantic layer when configured. '- 'Read-only. When a query misses, consult brain_recall_gate before widening '- 'recall: it classifies whether widening is warranted.',- 'inputSchema': {'type': 'object',- 'properties': {'query': {'type': 'string',- 'minLength': 1,- 'maxLength': 2000,- 'description': 'What to recall from the vault. Matched '- 'against the index by keyword, '- 'semantics, or both.'},- 'query_document': {'type': 'string',- 'minLength': 1,- 'maxLength': 4000,- 'description': 'Line-oriented query program '- 'with intent:, lex:, vec: and '- 'hyde: lanes, steering each '- 'retrieval layer separately. '- "Absent means 'query' drives "- 'every lane.'},- 'focus_query': {'type': 'string',- 'minLength': 1,- 'maxLength': 1000,- 'description': 'Steer this one call towards a '- 'working-set topic without '- 'persisting a session focus.'},- 'focus_path_prefix': {'type': 'string',- 'minLength': 1,- 'maxLength': 256,- 'description': 'Steer this one call towards '- 'a vault subtree, paired '- 'with focus_query as a '- 'transient focus.'},- 'focus_session': {'type': 'string',+ 'description': 'Full-text search across the vault. Optional semantic layer when configured. '+ 'Read-only. When a query misses, consult brain_recall_gate before widening recall: it '+ 'classifies whether widening is warranted.',+ 'inputSchema': {'type': 'object',+ 'properties': {'query': {'type': 'string',+ 'minLength': 1,+ 'maxLength': 2000,+ 'description': 'What to recall from the vault. Matched '+ 'against the index by keyword, semantics, or '+ 'both.'},+ 'query_document': {'type': 'string','minLength': 1,- 'maxLength': 128,- 'description': 'Session id whose bound focus '- 'applies (falls back to the '- 'global focus).'},- 'evidence_pack': {'type': 'boolean',- 'description': 'Return the evidence pack: '- 'matched/missing terms, '- 'coverage, abstention text and '- 'the false-absence guard. '- 'Default false.'},- 'include_superseded': {'type': 'boolean',- 'description': 'History mode for relation '- 'polarity: keep matched '- 'superseded predecessors '- 'undemoted and skip '- 'successor pull-in. Default '- 'false.'},- 'since': {'type': 'string',- 'maxLength': 64,- 'description': 'Hard filter on event time (validity, '- 'body anchor, mtime last): at/after this '- 'point. ISO date/datetime, today, '- 'yesterday, last week, last month, '- '<n>h/<n>d/<n>w.'},- 'until': {'type': 'string',- 'maxLength': 64,- 'description': 'Hard filter on event time (validity, '- 'body anchor, mtime last): at/before '- "this point. Same forms as 'since'."},- 'limit': {'type': 'integer',- 'minimum': 1,- 'maximum': 50,- 'description': 'How many ranked results to return. '- 'Default 10.'},- 'semantic': {'type': 'boolean',- 'description': 'Force the semantic lane on or off. '- 'Absent lets the configured hybrid '- 'strategy decide.'},- 'keyword_only': {'type': 'boolean',- 'description': 'Skip the semantic lane entirely, '- 'so no embedding is needed. '- 'Default false.'},- 'match_mode': {'type': 'string',- 'enum': ['all', 'any'],- 'description': "FTS match breadth: 'all' (default) "- "requires every term; 'any' matches "- 'a document carrying any one term. '- 'Absent leaves the implicit AND.'},- 'disclosure': {'type': 'string',- 'enum': ['full', 'cards'],- 'description': "Result depth: 'full' (default) "- 'returns full chunk content; '- "'cards' returns token-cheap "- 'layer-1 cards — drill a hit with '- 'brain_search_expand.'},- 'profile': {'type': 'string',- 'enum': ['fast', 'balanced', 'thorough'],- 'description': 'Named recall profile '- '(fast|balanced|thorough): a fixed '- 'knob preset, preferred over persisted '- 'self-tuning. Absent leaves ranking '- 'unchanged.'},- 'explain': {'type': 'boolean',- 'description': 'Add a per-result score_breakdown plus '- 'the retrieval_decision_trace and '- 'memory_trust_assessment receipts. '- 'Default false.'},- 'trust': {'type': 'boolean',- 'description': 'Stamp each result with inline trust '- 'metadata (age_days, superseded, '- 'conflict), computed at read time. '- 'Default false.'},- 'threshold': {'type': 'number',- 'minimum': 0,- 'maximum': 1,- 'description': 'Relevance floor in [0,1] on the '- 'final score; drops weaker hits so '- 'an irrelevant query returns no '- 'match. Default 0 (disabled).'},- 'rerank': {'type': 'boolean',- 'description': 'Re-order the threshold-qualified '- 'results by core textual relevance '- '(keyword + semantic). Default false.'},- 'reinforce': {'type': 'array',- 'maxItems': 50,- 'items': {'type': 'string',- 'minLength': 1,- 'maxLength': 512},- 'description': 'Paths proven useful: recorded to '- 'the reinforce ledger and lifted '- '(bounded) before the top_k cut. '- 'Default absent.'},- 'record_access': {'type': 'boolean',- 'description': 'Record the surfaced paths as '- 'one activation access event '- '(feeds the usage-aware ranking '- 'layer). Default true; never '- 'recorded for global searches.'},- 'global': {'type': 'boolean',- 'description': 'Cross-vault union: search profile '- 'vaults and read-only recall sources '- 'too, merging results with origin '- 'labels. Default false (active vault '- 'only).'},- 'path_prefix': {'type': 'string',- 'maxLength': 256,- 'description': 'Restrict results to this vault '- 'subtree. Absent searches the '- 'whole vault.'},- 'telemetry': {'type': 'boolean',- 'description': 'Emit one recall-telemetry '- 'continuity record for this call. '- 'Default false.'},- 'telemetry_host': {'type': 'string',- 'maxLength': 200,- 'description': 'Optional host/client label '- 'recorded on the telemetry '- 'record.'},- 'session_id': {'type': 'string',- 'maxLength': 512,- 'description': 'Optional session correlation id '- 'recorded on the telemetry record.'},- 'turn_id': {'type': 'string',- 'maxLength': 512,- 'description': 'Optional turn correlation id recorded '- 'on the telemetry record.'},- 'properties': {'type': 'object',- 'description': 'Optional frontmatter filter; '- 'values within a key OR, keys AND. '- 'type, pinned, visibility as '- 'indexed; other keys narrow on the '- 'attribute snapshot, judged live.',- 'additionalProperties': {'type': 'array',- 'items': {'type': 'string'}}},- 'kind': {'type': 'string',- 'enum': ['page', 'section'],- 'description': 'Restrict candidates by chunk kind: '- "'page' matches each document's "- 'frontmatter/head chunk (chunk 0), '- "'section' everything after it. Absent "- 'searches all chunks.'},- 'degree': {'type': 'array',- 'description': 'Graph-degree predicates over '- 'backlink/outlink counts, e.g. '- "'backlinks=0' (orphans) or "- "'outlinks>=5' (hubs); ANDed. Absent = "- 'no filter.',- 'items': {'type': 'string'}},- 'visibility': {'type': 'array',- 'description': 'Optional content-visibility scope; '- 'untagged pages always match, '- 'tagged pages only when this scope '- 'includes one of their values.',- 'items': {'type': 'string'}},- 'agent_scope': {'type': 'string',- 'description': 'Optional agent-ownership scope; '- 'shared (ownerless) pages always '- 'match, owner-tagged pages only '- 'their owner. Absent = no '- 'ownership filtering.'},- 'session_scope': {'type': 'string',- 'description': 'Optional session-scope filter; '- 'pages with no session always '- 'match, session-tagged pages '- 'only this session. Absent = no '- 'session filtering.'},- 'project_scope': {'type': 'string',- 'description': 'Optional project-scope filter; '- 'pages with no project always '- 'match, project-tagged pages '- 'only this project. Absent = no '- 'project filtering.'}},- 'required': ['query'],- 'additionalProperties': False}},+ 'maxLength': 4000,+ 'description': 'Line-oriented query program with '+ 'intent:, lex:, vec: and hyde: '+ 'lanes, steering each retrieval '+ 'layer separately. Absent means '+ "'query' drives every lane."},+ 'focus_query': {'type': 'string',+ 'minLength': 1,+ 'maxLength': 1000,+ 'description': 'Steer this one call towards a '+ 'working-set topic without persisting a '+ 'session focus.'},+ 'focus_path_prefix': {'type': 'string',+ 'minLength': 1,+ 'maxLength': 256,+ 'description': 'Steer this one call towards a '+ 'vault subtree, paired with '+ 'focus_query as a transient '+ 'focus.'},+ 'focus_session': {'type': 'string',+ 'minLength': 1,+ 'maxLength': 128,+ 'description': 'Session id whose bound focus applies '+ '(falls back to the global focus).'},+ 'evidence_pack': {'type': 'boolean',+ 'description': 'Return the evidence pack: '+ 'matched/missing terms, coverage, '+ 'abstention text and the '+ 'false-absence guard. Default false.'},+ 'include_superseded': {'type': 'boolean',+ 'description': 'History mode for relation '+ 'polarity: keep matched '+ 'superseded predecessors '+ 'undemoted and skip successor '+ 'pull-in. Default false.'},+ 'since': {'type': 'string',+ 'maxLength': 64,+ 'description': 'Hard filter on event time (validity, body '+ 'anchor, mtime last): at/after this point. '+ 'ISO date/datetime, today, yesterday, last '+ 'week, last month, <n>h/<n>d/<n>w.'},+ 'until': {'type': 'string',+ 'maxLength': 64,+ 'description': 'Hard filter on event time (validity, body '+ 'anchor, mtime last): at/before this point. '+ "Same forms as 'since'."},+ 'limit': {'type': 'integer',+ 'minimum': 1,+ 'maximum': 50,+ 'description': 'How many ranked results to return. Default '+ '10.'},+ 'semantic': {'type': 'boolean',+ 'description': 'Force the semantic lane on or off. Absent '+ 'lets the configured hybrid strategy '+ 'decide.'},+ 'keyword_only': {'type': 'boolean',+ 'description': 'Skip the semantic lane entirely, so '+ 'no embedding is needed. Default '+ 'false.'},+ 'match_mode': {'type': 'string',+ 'enum': ['all', 'any'],+ 'description': "FTS match breadth: 'all' (default) "+ "requires every term; 'any' matches a "+ 'document carrying any one term. Absent '+ 'leaves the implicit AND.'},+ 'disclosure': {'type': 'string',+ 'enum': ['full', 'cards'],+ 'description': "Result depth: 'full' (default) returns "+ "full chunk content; 'cards' returns "+ 'token-cheap layer-1 cards — drill a hit '+ 'with brain_search_expand.'},+ 'profile': {'type': 'string',+ 'enum': ['fast', 'balanced', 'thorough'],+ 'description': 'Named recall profile '+ '(fast|balanced|thorough): a fixed knob '+ 'preset, preferred over persisted '+ 'self-tuning. Absent leaves ranking '+ 'unchanged.'},+ 'explain': {'type': 'boolean',+ 'description': 'Add a per-result score_breakdown plus the '+ 'retrieval_decision_trace and '+ 'memory_trust_assessment receipts. Default '+ 'false.'},+ 'trust': {'type': 'boolean',+ 'description': 'Stamp each result with inline trust metadata '+ '(age_days, superseded, conflict), computed '+ 'at read time. Default false.'},+ 'threshold': {'type': 'number',+ 'minimum': 0,+ 'maximum': 1,+ 'description': 'Relevance floor in [0,1] on the final '+ 'score; drops weaker hits so an '+ 'irrelevant query returns no match. '+ 'Default 0 (disabled).'},+ 'rerank': {'type': 'boolean',+ 'description': 'Re-order the threshold-qualified results by '+ 'core textual relevance (keyword + '+ 'semantic). Default false.'},+ 'reinforce': {'type': 'array',+ 'maxItems': 50,+ 'items': {'type': 'string',+ 'minLength': 1,+ 'maxLength': 512},+ 'description': 'Paths proven useful: recorded to the '+ 'reinforce ledger and lifted (bounded) '+ 'before the top_k cut. Default absent.'},+ 'record_access': {'type': 'boolean',+ 'description': 'Record the surfaced paths as one '+ 'activation access event (feeds the '+ 'usage-aware ranking layer). Default '+ 'true; never recorded for global '+ 'searches.'},+ 'global': {'type': 'boolean',+ 'description': 'Cross-vault union: search profile vaults '+ 'and read-only recall sources too, merging '+ 'results with origin labels. Default false '+ '(active vault only).'},+ 'path_prefix': {'type': 'string',+ 'maxLength': 256,+ 'description': 'Restrict results to this vault '+ 'subtree. Absent searches the whole '+ 'vault.'},+ 'telemetry': {'type': 'boolean',+ 'description': 'Emit one recall-telemetry continuity '+ 'record for this call. Default false.'},+ 'telemetry_host': {'type': 'string',+ 'maxLength': 200,+ 'description': 'Optional host/client label recorded '+ 'on the telemetry record.'},+ 'session_id': {'type': 'string',+ 'maxLength': 512,+ 'description': 'Optional session correlation id '+ 'recorded on the telemetry record.'},+ 'turn_id': {'type': 'string',+ 'maxLength': 512,+ 'description': 'Optional turn correlation id recorded on '+ 'the telemetry record.'},+ 'properties': {'type': 'object',+ 'description': 'Optional frontmatter filter; values '+ 'within a key OR, keys AND. type, '+ 'pinned, visibility as indexed; other '+ 'keys narrow on the attribute snapshot, '+ 'judged live.',+ 'additionalProperties': {'type': 'array',+ 'items': {'type': 'string'}}},+ 'kind': {'type': 'string',+ 'enum': ['page', 'section'],+ 'description': "Restrict candidates by chunk kind: 'page' "+ "matches each document's frontmatter/head "+ "chunk (chunk 0), 'section' everything after "+ 'it. Absent searches all chunks.'},+ 'degree': {'type': 'array',+ 'description': 'Graph-degree predicates over '+ "backlink/outlink counts, e.g. 'backlinks=0' "+ "(orphans) or 'outlinks>=5' (hubs); ANDed. "+ 'Absent = no filter.',+ 'items': {'type': 'string'}},+ 'visibility': {'type': 'array',+ 'description': 'Optional content-visibility scope; '+ 'untagged pages always match, tagged '+ 'pages only when this scope includes one '+ 'of their values.',+ 'items': {'type': 'string'}},+ 'agent_scope': {'type': 'string',+ 'description': 'Optional agent-ownership scope; shared '+ '(ownerless) pages always match, '+ 'owner-tagged pages only their owner. '+ 'Absent = no ownership filtering.'},+ 'session_scope': {'type': 'string',+ 'description': 'Optional session-scope filter; pages '+ 'with no session always match, '+ 'session-tagged pages only this '+ 'session. Absent = no session '+ 'filtering.'},+ 'project_scope': {'type': 'string',+ 'description': 'Optional project-scope filter; pages '+ 'with no project always match, '+ 'project-tagged pages only this '+ 'project. Absent = no project '+ 'filtering.'},+ 'iterative': {'type': 'boolean',+ 'description': 'Opt in to the bounded iterative recall '+ 'loop (default off). Surviving gaps pause '+ 'with a plan; resume via '+ 'iterative_payload. Inert unless the knob '+ 'is on.'},+ 'iterative_token': {'type': 'string',+ 'maxLength': 128,+ 'description': 'The round token from a plan-phase '+ 'response, submitted beside '+ 'iterative_payload. Requires '+ 'iterative: true; single use - a '+ 'replayed token is refused by '+ 'name.'},+ 'iterative_payload': {'type': 'object',+ 'description': 'Decider payload answering a '+ 'plan-phase envelope: { evidence: '+ '[chunkId, ...], subQueries: '+ '[...] }, validated before any '+ 'pull runs. Requires '+ 'iterative_token.'}},+ 'required': ['query'],+ 'additionalProperties': False}},{'name': 'brain_recall_gate',- 'description': 'Classify whether an automatic recall attempt should run. Diagnostics only; does '- 'not search. Pass `scores` AND `match_quality` TOGETHER for an adequacy verdict — '- 'sufficient/proceed, weak/re_recall, insufficient/abstain; either alone is '- 'INVALID_PARAMS (see `dependentRequired`).',+ 'description': 'Classify whether recall should run. Diagnostics only; does not search. Pass '+ '`scores` AND `match_quality` together for an adequacy verdict; either alone is '+ 'INVALID_PARAMS (see `dependentRequired`). A measurement decides the verdict: '+ 'below-floor quality answers retrieve false. `admit` echoes it.','inputSchema': {'type': 'object','properties': {'prompt': {'type': 'string','minLength': 1,diff --git a/plugins/hermes/plugin.yaml b/plugins/hermes/plugin.yamlindex 25ee9ae9..a78a7822 100644--- a/plugins/hermes/plugin.yaml+++ b/plugins/hermes/plugin.yaml@@ -1,5 +1,5 @@name: open-second-brain-version: "1.81.1"+version: "1.82.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 1cc44186..c2340d61 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.81.1"+version = "1.82.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/cli/brain/help-text.ts b/src/cli/brain/help-text.tsindex 913a4104..12deaa1f 100644--- a/src/cli/brain/help-text.ts+++ b/src/cli/brain/help-text.ts@@ -158,8 +158,10 @@ Brain verbs (observing memory):inbox-drain Classify and route staged captures (dry-run; --apply to route)repair-lane Propose memory-graph edges (dry-run; --apply --confirm to write, holdout-gated)orphan-repair Detach dangling session references from observations (dry-run; --apply --confirm)- session-grep Search imported session recall turns and summaries- session-describe Describe an imported session recall DAG+ session-grep Search session recall turns/summaries; --operation coverage+ selects whole-thread coverage under --char-budget+ session-describe Describe an imported session recall DAG (--topics renders+ the adaptive topic-budget report)session-expand Expand a session recall node to source turnslint Self-healing structural checks (--consolidate); --apply to writeactions Ranked maintenance action list (dedup + lint + footprint)@@ -1242,13 +1244,20 @@ export const VERB_HELP: Record<string, string> = {" --workday-start HH:MM --workday-end HH:MM clip focus blocks to a daily window\n" +" [--json]\n","session-grep":- "usage: o2b brain session-grep --query <text> [--session-id <id>] [--limit <n>] [--snippet-chars <n>] [--since <t>] [--before <t>] [--vault <path>] [--json]\n" ++ "usage: o2b brain session-grep --query <text> [--operation match] [--session-id <id>] [--limit <n>] [--snippet-chars <n>] [--since <t>] [--before <t>] [--vault <path>] [--json]\n" ++ " o2b brain session-grep --operation coverage --char-budget <n> [--entity-key <key>] [--session-id <id>] [--vault <path>] [--json]\n" +"Search imported session recall raw turns and summary nodes. --since and\n" +"--before bound results to a time window (ISO date/datetime, today/\n" +- "yesterday/last week/last month, or <n>h/<n>d/<n>w); --before is inclusive.\n",+ "yesterday/last week/last month, or <n>h/<n>d/<n>w); --before is inclusive.\n" ++ "--operation coverage runs the coverage-first thread selection instead:\n" ++ "facets detected from the thread, fanned out under the adaptive topic\n" ++ "budget (floor 12, cap 16), selected under --char-budget, returned\n" ++ "chronologically with selection diagnostics. A budget that cannot hold\n" ++ "the floor-weighted selection is refused, never silently truncated.\n","session-describe":- "usage: o2b brain session-describe --session-id <id> [--vault <path>] [--json]\n" +- "Describe counts and summary depths for an imported session recall DAG.\n",+ "usage: o2b brain session-describe --session-id <id> [--topics] [--vault <path>] [--json]\n" ++ "Describe counts and summary depths for an imported session recall DAG.\n" ++ "--topics adds the adaptive topic-budget report (floor 12, cap 16).\n","session-expand":"usage: o2b brain session-expand <record-id> [--raw-limit <n>] [--cursor <offset>] [--vault <path>] [--json]\n" +"Expand a raw or summary session recall node to immediate sources and paginated raw turn content.\n",diff --git a/src/cli/brain/verbs/bench.ts b/src/cli/brain/verbs/bench.tsindex 045bb8aa..fa5b3a2e 100644--- a/src/cli/brain/verbs/bench.ts+++ b/src/cli/brain/verbs/bench.ts@@ -14,22 +14,286 @@ import { existsSync } from "node:fs";import { join, resolve } from "node:path";import { loadBenchFixture } from "../../../core/bench/fixture.ts";+import { LONGMEMEVAL_SUITE_NAME, loadLongMemEvalFixture } from "../../../core/bench/longmemeval.ts";import { loadLocomoFixture } from "../../../core/bench/locomo.ts";+import { loadReplayBenchFixture } from "../../../core/bench/replay.ts";import { runMemoryBench } from "../../../core/bench/phases.ts";+import type {+ BenchPinnedKnobs,+ BenchSuiteLoad,+ BenchSuiteRegistration,+} from "../../../core/bench/types.ts";import { defaultConfigPath, resolveBenchJudgeCmd } from "../../../core/config.ts";-import { fail, parse } from "../helpers.ts";+import { CliError, fail, parse } from "../helpers.ts";const USAGE =- "usage: o2b brain bench memory --fixture <name|path> [--suite locomo] [--resume <run-id>] [--runs-dir <dir>] [--json]";+ "usage: o2b brain bench memory --fixture <name|path> [--suite <name>] [--pin <json>] " ++ "[--recall-floor <n>] [--resume <run-id>] [--runs-dir <dir>] [--json]";const DEFAULT_RUNS_DIR = join(".open-second-brain", "bench-runs");const REPO_FIXTURE_DIR = join("tests", "fixtures", "bench");+/** A suite name must be safe to echo into errors, reports and run ids. */+const SUITE_NAME_PATTERN = /^[a-z0-9][a-z0-9_-]*$/;++/**+ * The path with no `--suite`: a native fixture loads directly. Not a+ * named suite - it is the byte-identical default the registry must+ * preserve.+ */+const DEFAULT_SUITE_REGISTRATION: BenchSuiteRegistration = Object.freeze({+ loader: (fixturePath: string): BenchSuiteLoad => ({ fixture: loadBenchFixture(fixturePath) }),+ capabilities: Object.freeze({ embeddings: false }),+});++/**+ * Suite registry: maps a `--suite` name to its loader and declared+ * capabilities. This map is the appendable registration point - suite+ * modules add their own entries here (or through+ * {@link registerBenchSuite}), never a new branch in the verb body.+ */+const BENCH_SUITES = new Map<string, BenchSuiteRegistration>([+ [+ "locomo",+ Object.freeze({+ loader: (fixturePath: string): BenchSuiteLoad => ({+ fixture: loadLocomoFixture(fixturePath),+ }),+ capabilities: Object.freeze({ embeddings: false }),+ }),+ ],+ [+ LONGMEMEVAL_SUITE_NAME,+ Object.freeze({+ loader: loadLongMemEvalFixture,+ capabilities: Object.freeze({ embeddings: true }),+ }),+ ],+ [+ "surfacing-replay",+ Object.freeze({+ loader: (fixturePath: string): BenchSuiteLoad => ({+ fixture: loadReplayBenchFixture(fixturePath),+ }),+ capabilities: Object.freeze({ embeddings: false }),+ }),+ ],+]);++/** Register a bench suite. Refuses an invalid or already-taken name. */+export function registerBenchSuite(name: string, registration: BenchSuiteRegistration): void {+ if (!SUITE_NAME_PATTERN.test(name)) {+ throw new Error(`bench suite name is invalid: '${name}'`);+ }+ if (BENCH_SUITES.has(name)) {+ throw new Error(`bench suite already registered: ${name}`);+ }+ BENCH_SUITES.set(name, registration);+}++/** Look up a registered suite by name. */+export function benchSuite(name: string): BenchSuiteRegistration | undefined {+ return BENCH_SUITES.get(name);+}++/** Registered suite names, sorted for stable listings. */+export function benchSuiteNames(): ReadonlyArray<string> {+ return [...BENCH_SUITES.keys()].toSorted();+}++/**+ * The knob names a `--pin` may set. Listed by hand against+ * {@link BenchPinnedKnobs} - the `satisfies` bounds make a renamed or+ * removed member a compile error - because TypeScript types have no+ * runtime keys to reflect on. A NEW member compiles silently until it is+ * listed here; a pin that names it is then refused, which is the loud+ * maintenance path, not a silent one.+ */+const BENCH_PIN_KNOBS = [+ "chunkSize",+ "chunkOverlap",+ "chunkMinSize",+ "keywordWeight",+ "semanticWeight",+ "fusionMode",+ "rrfK",+ "recall",+ "shutdownGraceMs",+ "hybridDeadlineMs",+ "resumeReindex",+ "ftsTokenize",+ "freshen",+ "scopeRules",+ "semantic",+ "rerank",+] as const satisfies ReadonlyArray<keyof BenchPinnedKnobs>;++/**+ * The knobs the harness itself owns: the run's vault identity. A pin may+ * never set them - pointing the bench at the operator's configured vault+ * is the one thing the harness exists to never do.+ */+const BENCH_PIN_HARNESS_KEYS = ["configPath", "dbPath", "vault"] as const satisfies ReadonlyArray<+ keyof BenchPinnedKnobs+>;++/** Member names of the pin's nested knob families, same listing rule. */+const BENCH_PIN_NESTED_KEYS: Readonly<Record<string, ReadonlyArray<string>>> = {+ semantic: [+ "enabled",+ "provider",+ "baseUrl",+ "model",+ "apiKey",+ "apiKeys",+ "allowInsecureHttp",+ "dimension",+ "timeoutMs",+ "concurrency",+ "batchSize",+ "batchTokens",+ "inputWindowTokens",+ "maxRetries",+ "costGateUsd",+ "priceOverride",+ "queryPrefix",+ "passagePrefix",+ "extraBody",+ ] as const satisfies ReadonlyArray<keyof NonNullable<BenchPinnedKnobs["semantic"]>>,+ rerank: [+ "enabled",+ "kind",+ "baseUrl",+ "model",+ "envKey",+ "apiKey",+ "allowInsecureHttp",+ "topK",+ "minScore",+ "relationalRerankPin",+ "decisionModel",+ ] as const satisfies ReadonlyArray<keyof NonNullable<BenchPinnedKnobs["rerank"]>>,+ recall: [+ "mmrLambda",+ "maxHops",+ "hopDecay",+ "maxExpansionPerHit",+ "recencyShape",+ "recencyScale",+ "recencyAmplitude",+ "intentEnabled",+ "synonymEnabled",+ "synonymMaxTerms",+ "cacheEnabled",+ "cacheTtlSeconds",+ "relationPolarityEnabled",+ "relationalArmEnabled",+ "retrievalTrustGateEnabled",+ "supersedeFadeEnabled",+ "learnedWeightsEnabled",+ "activationEnabled",+ "twoPassEnabled",+ "iterativeRecallEnabled",+ "iterativeRecallMaxRounds",+ "poolMultiplier",+ "selfTuningEnabled",+ "chainStopEnabled",+ "chainStopScore",+ "trigramPrefilterEnabled",+ "trigramPrefilterMinChunks",+ "trigramPrefilterMaxSelectivity",+ "metadataBoostGateEnabled",+ ] as const satisfies ReadonlyArray<keyof NonNullable<BenchPinnedKnobs["recall"]>>,+ freshen: ["intervalSeconds", "embeddings", "configPath"] as const satisfies ReadonlyArray<+ keyof NonNullable<BenchPinnedKnobs["freshen"]>+ >,+ scopeRules: ["ignore", "include"] as const satisfies ReadonlyArray<+ keyof NonNullable<BenchPinnedKnobs["scopeRules"]>+ >,+};++/**+ * Parse the `--pin` value into a {@link BenchPinnedKnobs} object.+ *+ * Garbage is refused by name: non-JSON, a non-object, a knob the harness+ * owns, an unknown knob, and a nested family that is not an object or+ * names an unknown member. VALUE semantics stay with+ * `resolveSearchConfig`, which applies the pin last and reports its own+ * named errors for a bad provider name or an out-of-range number - this+ * validation refuses shape garbage the resolver would silently ignore,+ * because an ignored override would pin nothing and report a run under a+ * configuration it did not run.+ *+ * An explicit pin REPLACES the default keyword-only pin+ * (`DEFAULT_BENCH_KNOB_PIN`) wholesale: `--pin '{"keywordWeight":0.7}'`+ * alone leaves the semantic lane env-driven, and the run then fails the+ * embeddings-capability gate loudly unless the suite declared it or the+ * pin also carries `"semantic":{"enabled":false}`.+ */+export function parseBenchPinnedKnobs(raw: string): BenchPinnedKnobs {+ let parsed: unknown;+ try {+ parsed = JSON.parse(raw);+ } catch (e) {+ throw new CliError(+ `brain bench memory: --pin is not valid JSON: ${e instanceof Error ? e.message : String(e)}`,+ );+ }+ if (parsed === null || typeof parsed !== "object" || Array.isArray(parsed)) {+ throw new CliError("brain bench memory: --pin must be a JSON object of search knobs");+ }+ const pin = parsed as Record<string, unknown>;+ for (const key of Object.keys(pin)) {+ if ((BENCH_PIN_HARNESS_KEYS as ReadonlyArray<string>).includes(key)) {+ throw new CliError(+ `brain bench memory: --pin may not set '${key}' - the harness owns the run's ${key}`,+ );+ }+ if (!(BENCH_PIN_KNOBS as ReadonlyArray<string>).includes(key)) {+ throw new CliError(+ `brain bench memory: --pin has an unknown knob '${key}' (known knobs: ${BENCH_PIN_KNOBS.join(", ")})`,+ );+ }+ const nestedKeys = BENCH_PIN_NESTED_KEYS[key];+ const value = pin[key];+ if (nestedKeys === undefined) continue;+ if (value === null || typeof value !== "object" || Array.isArray(value)) {+ throw new CliError(`brain bench memory: --pin '${key}' must be a JSON object`);+ }+ for (const nested of Object.keys(value as Record<string, unknown>)) {+ if (!(nestedKeys as ReadonlyArray<string>).includes(nested)) {+ throw new CliError(+ `brain bench memory: --pin '${key}.${nested}' is not a known knob (known: ${nestedKeys.join(", ")})`,+ );+ }+ }+ }+ return pin as BenchPinnedKnobs;+}++/**+ * Parse the `--recall-floor` value: absent keeps the shipped admission+ * floor; present it must be a positive number, and it becomes part of the+ * run identity (a resumed run whose floor changed fails the guard).+ */+export function parseRecallFloorFlag(raw: string | undefined): number | undefined {+ if (raw === undefined) return undefined;+ const value = Number(raw);+ if (raw.trim() === "" || !Number.isFinite(value) || value <= 0) {+ throw new CliError(+ `brain bench memory: --recall-floor must be a positive number, got '${raw}'`,+ );+ }+ return value;+}+export async function cmdBrainBench(argv: string[]): Promise<number> {if (argv[0] !== "memory") return fail(USAGE);const { flags } = parse(argv.slice(1), {fixture: { type: "string" },suite: { type: "string" },+ pin: { type: "string" },+ "recall-floor": { type: "string" },resume: { type: "string" },"runs-dir": { type: "string" },json: { type: "boolean" },@@ -37,8 +301,15 @@ export async function cmdBrainBench(argv: string[]): Promise<number> {const fixtureFlag = typeof flags["fixture"] === "string" ? flags["fixture"].trim() : "";if (fixtureFlag === "") return fail(USAGE);const suite = typeof flags["suite"] === "string" ? flags["suite"].trim() : "";- if (suite !== "" && suite !== "locomo") {- return fail(`brain bench memory: unknown --suite '${suite}' (supported: locomo)`);+ let registration = DEFAULT_SUITE_REGISTRATION;+ if (suite !== "") {+ const known = BENCH_SUITES.get(suite);+ if (known === undefined) {+ return fail(+ `brain bench memory: unknown --suite '${suite}' (supported: ${benchSuiteNames().join(", ")})`,+ );+ }+ registration = known;}const fixturePath = resolveFixturePath(fixtureFlag);if (fixturePath === null) {@@ -47,10 +318,11 @@ export async function cmdBrainBench(argv: string[]): Promise<number> {);}- // The LoCoMo suite loads a LoCoMo-shaped dataset and converts it to a- // BenchFixture; the default path loads a native fixture directly.- const fixture =- suite === "locomo" ? loadLocomoFixture(fixturePath) : loadBenchFixture(fixturePath);+ // One dispatch for every suite: the registry entry owns loading and+ // declares what the suite may do; the capabilities and the loader's+ // conversion receipt ride BenchRunOptions.+ const loaded = registration.loader(fixturePath);+ const fixture = loaded.fixture;const runsDir = resolve(typeof flags["runs-dir"] === "string" && flags["runs-dir"].trim() !== ""? flags["runs-dir"].trim()@@ -58,10 +330,23 @@ export async function cmdBrainBench(argv: string[]): Promise<number> {);const resume = typeof flags["resume"] === "string" ? flags["resume"].trim() : undefined;const judgeCmd = resolveBenchJudgeCmd(defaultConfigPath());+ // Refusals throw CliError with the offending value named; the+ // dispatcher prints them and exits non-zero.+ const pinFlag = typeof flags["pin"] === "string" ? flags["pin"] : undefined;+ const pinnedKnobs: BenchPinnedKnobs | undefined =+ pinFlag === undefined ? undefined : parseBenchPinnedKnobs(pinFlag);+ const recallFloor = parseRecallFloorFlag(+ typeof flags["recall-floor"] === "string" ? flags["recall-floor"] : undefined,+ );const report = await runMemoryBench({fixture,runsDir,+ ...(suite !== "" ? { suite } : {}),+ capabilities: registration.capabilities,+ ...(pinnedKnobs !== null ? { pinnedKnobs } : {}),+ ...(recallFloor !== undefined ? { recallFloor } : {}),+ ...(loaded.receipt !== undefined ? { suiteReceipt: loaded.receipt } : {}),...(resume !== undefined && resume !== "" ? { resume } : {}),...(judgeCmd !== undefined ? { judgeCmd } : {}),});@@ -83,6 +368,12 @@ export async function cmdBrainBench(argv: string[]): Promise<number> {`false_fire ${report.failure_modes.false_fire_rate} ` +`isolation_violations ${report.failure_modes.source_isolation_violations}\n`,);+ if (report.longmemeval !== undefined) {+ process.stdout.write(+ `longmemeval: recall_all@5 ${report.longmemeval.recall_all_at_5} ` ++ `abstention_excluded ${report.longmemeval.abstention_excluded}\n`,+ );+ }process.stdout.write(`judge: ${report.judge.status}\n`);for (const question of report.questions) {process.stdout.write(diff --git a/src/cli/brain/verbs/session-recall.ts b/src/cli/brain/verbs/session-recall.tsindex dfad4842..2de36383 100644--- a/src/cli/brain/verbs/session-recall.ts+++ b/src/cli/brain/verbs/session-recall.ts@@ -1,8 +1,12 @@import {+ coverageSessionRecall,describeSessionRecall,expandSessionRecall,searchSessionRecall,+ SessionCoverageEntityUnknownError,+ SessionCoverageInfeasibleError,} from "../../../core/brain/session-recall.ts";+import { MINED_KEY_MAX_LENGTH } from "../../../core/brain/link-graph/session-mining.ts";import { resolveTimeRange } from "../../../core/search/time-range.ts";import { SearchError } from "../../../core/search/types.ts";import { CliError, brainVerbContext, parse } from "../helpers.ts";@@ -17,8 +21,24 @@ export async function cmdBrainSessionGrep(argv: string[]): Promise<number> {"snippet-chars": { type: "string" },since: { type: "string" },before: { type: "string" },+ operation: { type: "string" },+ "char-budget": { type: "string" },+ "entity-key": { type: "string" },});const vault = brainVerbContext(flags).vault;+ // Coverage-first selection (t_2c2a883c) rides this verb as an explicit+ // operation; omitted is the historical grep, byte-identical.+ const operation = stringOptional(flags["operation"]) ?? "match";+ if (operation === "coverage") return runSessionGrepCoverage(vault, flags);+ if (operation !== "match") {+ throw new CliError(`brain session-grep: operation must be 'match' or 'coverage'`);+ }+ if (stringOptional(flags["char-budget"]) !== undefined) {+ throw new CliError("brain session-grep: --char-budget applies to --operation coverage only");+ }+ if (stringOptional(flags["entity-key"]) !== undefined) {+ throw new CliError("brain session-grep: --entity-key applies to --operation coverage only");+ }// Conversation-chronology bounds (S1): --since / --before parse through// the shared time-range grammar; --before maps onto the inclusive upper// edge. Absent bounds leave the search unbounded (byte-identical).@@ -50,6 +70,58 @@ export async function cmdBrainSessionGrep(argv: string[]): Promise<number> {return 0;}+/**+ * The coverage operation (t_2c2a883c): coverage-first thread selection+ * under --char-budget, with the typed floor-violation infeasibility+ * surfaced as the CLI error it is.+ */+function runSessionGrepCoverage(+ vault: string,+ flags: Record<string, string | boolean | string[] | undefined>,+): number {+ for (const inapplicable of ["query", "since", "before", "limit", "snippet-chars"] as const) {+ if (flags[inapplicable] !== undefined) {+ throw new CliError(+ `brain session-grep: --${inapplicable} is not applicable to --operation coverage; it filters the match operation`,+ );+ }+ }+ const charBudget = positiveIntegerOptional(+ flags["char-budget"],+ "brain session-grep",+ "--char-budget",+ );+ if (charBudget === undefined) {+ throw new CliError("brain session-grep: --char-budget is required for --operation coverage");+ }+ // The miner's own cap, for parity with the MCP tool: mined keys run to+ // MINED_KEY_MAX_LENGTH, so a 129-200 character URL or path key can seed+ // coverage here, and a longer one is refused by name instead of being+ // silently unmatchable against every mined row.+ const entityKey = stringOptional(flags["entity-key"]);+ if (entityKey !== undefined && entityKey.length > MINED_KEY_MAX_LENGTH) {+ throw new CliError(+ `brain session-grep: --entity-key must be at most ${MINED_KEY_MAX_LENGTH} characters`,+ );+ }+ let result;+ try {+ result = coverageSessionRecall(vault, {+ ...(stringOptional(flags["session-id"]) !== undefined+ ? { sessionId: stringOptional(flags["session-id"]) }+ : {}),+ ...(entityKey !== undefined ? { entityKey } : {}),+ charBudget,+ });+ } catch (exc) {+ if (exc instanceof SessionCoverageInfeasibleError) throw new CliError(exc.message);+ if (exc instanceof SessionCoverageEntityUnknownError) throw new CliError(exc.message);+ throw exc;+ }+ writeOutput(result, flags["json"] === true);+ return 0;+}+function sessionGrepBounds(since: string | undefined,before: string | undefined,@@ -74,10 +146,12 @@ export async function cmdBrainSessionDescribe(argv: string[]): Promise<number> {vault: { type: "string" },json: { type: "boolean" },"session-id": { type: "string" },+ topics: { type: "boolean" },});const vault = brainVerbContext(flags).vault;const result = describeSessionRecall(vault, {sessionId: requiredString(flags["session-id"], "brain session-describe", "--session-id"),+ ...(flags["topics"] === true ? { topics: true } : {}),});writeOutput(result, flags["json"] === true);return 0;diff --git a/src/cli/command-manifest.ts b/src/cli/command-manifest.tsindex 49f6989b..74e53777 100644--- a/src/cli/command-manifest.ts+++ b/src/cli/command-manifest.ts@@ -793,8 +793,18 @@ export const CLI_COMMAND_MANIFEST: CliRootManifest = Object.freeze({"Detach dangling session references from observations (dry-run by default)",[flag("vault", "string"), flag("apply", "boolean"), flag("confirm", "string")],),- command("session-grep", "Search imported session recall turns and summaries"),- command("session-describe", "Describe an imported session recall DAG"),+ command(+ "session-grep",+ "Search imported session recall turns and summaries; --operation coverage selects whole-thread coverage",+ [+ flag("operation", "string"),+ flag("char-budget", "string"),+ flag("entity-key", "string"),+ ],+ ),+ command("session-describe", "Describe an imported session recall DAG", [+ flag("topics", "boolean"),+ ]),command("session-expand", "Expand a session recall node to its source turns"),command("lint", "Self-healing structural checks; --consolidate --apply writes the fixes", [flag("vault", "string"),diff --git a/src/core/bench/embedding-cache.ts b/src/core/bench/embedding-cache.tsnew file mode 100644index 00000000..9c9c0eb3--- /dev/null+++ b/src/core/bench/embedding-cache.ts@@ -0,0 +1,355 @@+/**+ * Shared vector cache for capability-declaring bench suites+ * (recall-quality wave, t_607d429d).+ *+ * One cache file under the RUNS directory - shared by every run+ * ("arm") against the same runs dir - keyed by the embedding identity+ * triple (provider, model, dimension) plus the SHA-256 of the chunk+ * text. The suite's index phase is the only writer: it applies cached+ * vectors straight into the run's disposable store (no provider+ * contact, no spend), hands only the misses to the indexer's+ * apply-gated embedding phase - which re-prices and re-gates that+ * census itself - then reads every stored vector back and rewrites the+ * cache atomically once the phase completed. Because a hit IS the+ * earlier arm's stored bytes, arms compare byte-identical vectors by+ * construction, without touching the store schema.+ *+ * The spend plan is computed over the FULL pending census through+ * `planEmbeddingSpend` and surfaced on the receipt; a blocked gate is a+ * named refusal before any provider contact. The bench never passes+ * `forceCost` and never bypasses the plan.+ *+ * Scale bound, stated honestly: this backend is one JSON file of float+ * arrays, read fully into memory and rewritten atomically per run, with+ * the pending census looked up through a Map keyed by chunk id. That+ * serves bench runs up to roughly 10^4 chunks. LongMemEval at `_s`+ * scale is about 10^5 chunks - past what one in-memory JSON file should+ * hold; a suite that size needs a different cache (one file per key, or+ * SQLite), not this one.+ *+ * Deterministic and network-free under the deterministic local provider+ * the CI pin selects; a real provider is an operator lane through the+ * same explicit capability-plus-pin gate.+ */++import { existsSync, readFileSync, renameSync, writeFileSync } from "node:fs";+import { join } from "node:path";++import { sha256Hex } from "../integrity/digest.ts";+import {+ COST_GATE_KEY,+ formatEstimatedUsd,+ planEmbeddingSpend,+ priceSpendPlan,+} from "../search/embedding-spend.ts";+import { makeProvider } from "../search/embeddings/provider.ts";+import { indexVault, runEmbeddingPhase, type EmbeddingPhaseTally } from "../search/indexer.ts";+import { Store } from "../search/store.ts";+import type { ResolvedSearchConfig } from "../search/types.ts";+import type { BenchEmbeddingReceipt } from "./types.ts";++/** Typed failure of the bench embedding path. Errors surface by name. */+export class BenchEmbeddingError extends Error {}++/** Field sentinel of an unknown model or dimension, keeping keys parseable. */+const SIGNATURE_SENTINEL = "?";++/** NFC, trim, lowercase: the one canonicalization for identity tokens. */+function canonicalSignatureToken(raw: string): string {+ return raw.normalize("NFC").trim().toLowerCase();+}++/**+ * The bench's own rendering of the embedding identity: the+ * `<provider>:<model>:<dimension>` triple plus the resolved+ * query/passage prefixes, canonicalized exactly like the store's+ * identity so cache keys match across runs. Rendered here+ * rather than imported because the module that exports the shared+ * renderer also carries a token estimator, and the bench pins exactly+ * one estimator - the census is on the import path.+ */+export function benchEmbeddingSignature(+ provider: string,+ model: string | null,+ dimension: number | null,+ queryPrefix: string,+ passagePrefix: string,+): string {+ const modelField = model === null ? SIGNATURE_SENTINEL : canonicalSignatureToken(model);+ const dimensionField = dimension === null ? SIGNATURE_SENTINEL : String(dimension);+ // The prefixes join the signature because the stored bytes depend on+ // them as much as on the model: the provider input is the prefixed+ // text, and BenchPinnedKnobs.semantic can pin either prefix. Two arms+ // that differ only in prefix pins must never share an entry.+ return (+ `${canonicalSignatureToken(provider)}:${modelField}:${dimensionField}:` ++ `${canonicalSignatureToken(queryPrefix)}:${canonicalSignatureToken(passagePrefix)}`+ );+}++/** Cache file shared by every bench run under one runs directory. */+export const BENCH_VECTOR_CACHE_FILENAME = "embedding-cache.json";++/** The spend receipt each capability run writes beside its report. */+export const BENCH_EMBEDDING_RECEIPT_FILENAME = "embeddings.json";++export const BENCH_VECTOR_CACHE_SCHEMA = "o2b.bench.vectors.v1";++interface VectorCache {+ readonly schema: string;+ readonly entries: Record<string, ReadonlyArray<number>>;+}++/** Runs-directory path of the shared vector cache. */+export function benchVectorCachePath(runsDir: string): string {+ return join(runsDir, BENCH_VECTOR_CACHE_FILENAME);+}++/**+ * Cache key for one chunk: the embedding identity triple plus the text+ * hash. The dimension joins the key because vectors of different+ * dimensions are incomparable even at the same provider and model - the+ * comparability rule the identity signature exists for.+ */+export function benchVectorCacheKey(signature: string, text: string): string {+ return `${signature}|${sha256Hex(text)}`;+}++/**+ * Load the shared cache. An absent file is an empty cache; a malformed+ * one is a named error - the cache is repo-owned state, and silently+ * re-embedding over a corrupt file would hide why two arms disagreed.+ * A file stamped with another schema is foreign state by the same rule:+ * its vectors are never served as hits.+ */+function loadVectorCache(runsDir: string): Record<string, ReadonlyArray<number>> {+ const path = benchVectorCachePath(runsDir);+ if (!existsSync(path)) return {};+ let raw: unknown;+ try {+ raw = JSON.parse(readFileSync(path, "utf8"));+ } catch (e) {+ throw new BenchEmbeddingError(+ `bench vector cache is not readable JSON at ${path}: ${e instanceof Error ? e.message : String(e)}`,+ );+ }+ if (raw === null || typeof raw !== "object" || Array.isArray(raw)) {+ throw new BenchEmbeddingError(`bench vector cache at ${path} must be an object`);+ }+ // Every writer stamps the schema, so a missing or foreign one means the+ // file was not written by this module's generation: applying its bytes+ // as cache hits would compare vectors across incomparable identities.+ const schema = (raw as Record<string, unknown>)["schema"];+ if (schema !== BENCH_VECTOR_CACHE_SCHEMA) {+ throw new BenchEmbeddingError(+ `bench vector cache at ${path} has schema '${String(schema)}', expected ` ++ `'${BENCH_VECTOR_CACHE_SCHEMA}' - refusing to serve vectors across cache generations`,+ );+ }+ const entries = (raw as Record<string, unknown>)["entries"];+ if (entries === undefined) return {};+ if (entries === null || typeof entries !== "object" || Array.isArray(entries)) {+ throw new BenchEmbeddingError(`bench vector cache at ${path} needs an entries object`);+ }+ const parsed: Record<string, ReadonlyArray<number>> = {};+ for (const [key, value] of Object.entries(entries as Record<string, unknown>)) {+ if (!Array.isArray(value) || !value.every((n) => typeof n === "number" && Number.isFinite(n))) {+ throw new BenchEmbeddingError(+ `bench vector cache at ${path}: entry '${key}' must be an array of finite numbers`,+ );+ }+ parsed[key] = Object.freeze([...value]);+ }+ return parsed;+}++/**+ * Rewrite the shared cache atomically: a temp file renamed over the+ * target, so an arm never reads a partially written file and a crash+ * leaves the previous generation intact.+ */+function writeVectorCache(runsDir: string, entries: Record<string, ReadonlyArray<number>>): void {+ const cache: VectorCache = { schema: BENCH_VECTOR_CACHE_SCHEMA, entries };+ const path = benchVectorCachePath(runsDir);+ const tmp = `${path}.${process.pid}.tmp`;+ writeFileSync(tmp, `${JSON.stringify(cache, null, 2)}\n`, "utf8");+ renameSync(tmp, path);+}++/** The stored-model spelling, matching the indexer's embedding phase. */+function storedEmbeddingModel(config: ResolvedSearchConfig): string | null {+ return config.semantic.model ?? makeProvider(config.semantic).model;+}++/** Same digest formula the indexer records alongside every vector. */+function embeddingHashOf(vector: ReadonlyArray<number>): string {+ return sha256Hex(vector.map((x) => x.toFixed(8)).join(","));+}++/**+ * Build the disposable vault's index with real vectors, through the+ * apply-gated indexer path and the shared vector cache.+ *+ * Order matters: the chunk-only index runs first (no provider contact),+ * the full spend plan is computed and gated over its census, cache hits+ * are applied without any provider, and only the misses reach the+ * indexer's embedding phase - handed in as a plan the phase re-prices+ * and re-gates itself, unforced. Every pending vector is then read back+ * from the store and the cache is rewritten atomically.+ */+export async function embedBenchVaultIndex(opts: {+ config: ResolvedSearchConfig;+ runsDir: string;+}): Promise<BenchEmbeddingReceipt> {+ const { config, runsDir } = opts;+ // Chunk-only index: walk, chunk, FTS - the apply-gated phase below is+ // the only provider contact in the whole run.+ await indexVault(config);+ const model = storedEmbeddingModel(config);+ if (model === null) {+ throw new BenchEmbeddingError(+ "bench embedding: no embedding model is stored on the index; the capability path needs an indexed model to key vectors",+ );+ }+ const provider = makeProvider(config.semantic);+ const signature = benchEmbeddingSignature(+ config.semantic.provider,+ model,+ provider.dimension ?? null,+ config.semantic.queryPrefix ?? "",+ config.semantic.passagePrefix ?? "",+ );+ const store = await Store.open(config, { mode: "write" });+ try {+ const plan = planEmbeddingSpend(store, config);+ const cache = loadVectorCache(runsDir);+ const prefixes = {+ query: config.semantic.queryPrefix ?? "",+ passage: config.semantic.passagePrefix ?? "",+ };+ interface Hit {+ readonly chunkId: number;+ readonly key: string;+ readonly vector: ReadonlyArray<number>;+ }+ const hits: Hit[] = [];+ const misses: Array<{ chunkId: number; content: string; key: string }> = [];+ for (const item of plan.pending) {+ const key = benchVectorCacheKey(signature, item.content);+ const cached = cache[key];+ if (cached !== undefined) {+ hits.push({ chunkId: item.chunkId, key, vector: cached });+ } else {+ misses.push({ chunkId: item.chunkId, content: item.content, key });+ }+ }+ // The spend gate prices the misses census, the chunks this arm would+ // actually embed: an arm the shared cache serves whole makes zero+ // provider contact, and gating it on the full census would refuse+ // exactly the runs the cache exists for. With misses, the verdict+ // over the misses subset is the honest one - the phase's own gate+ // re-checks the same census at write time. Pending entries are+ // keyed by chunk id once, so pricing the misses stays linear in the+ // census rather than a scan per miss.+ if (misses.length > 0) {+ const pendingByChunkId = new Map(plan.pending.map((p) => [p.chunkId, p]));+ const missesPlan = priceSpendPlan(+ misses.map((m) => {+ const pending = pendingByChunkId.get(m.chunkId);+ if (pending === undefined) throw new BenchEmbeddingError("census split lost a chunk");+ return pending;+ }),+ config,+ );+ if (missesPlan.gate.blocked) {+ throw new BenchEmbeddingError(+ `bench embedding spend gate refused (${missesPlan.gate.reason}): estimated ` ++ `${formatEstimatedUsd(missesPlan.estimatedUsd)} for ${missesPlan.pending.length} chunk(s) exceeds ` ++ `${COST_GATE_KEY} ${formatEstimatedUsd(config.semantic.costGateUsd)} - the bench never ` ++ `bypasses the spend plan`,+ );+ }+ }+ // Cache hits carry an earlier arm's exact bytes: same signature, so+ // the same model, dimension and prefix bookkeeping apply.+ if (hits.length > 0) {+ const dim = hits[0]!.vector.length;+ store.ensureEmbeddingModel(model, dim, prefixes);+ for (const hit of hits) {+ store.vecUpsert(+ hit.chunkId,+ new Float32Array(hit.vector),+ model,+ dim,+ embeddingHashOf(hit.vector),+ );+ }+ }+ const tally: EmbeddingPhaseTally = { embeddingsComputed: 0, embeddingsRetries: 0 };+ if (misses.length > 0) {+ // Only the misses are spend, and the phase prices and gates that+ // census itself - the verdict acted on is always the phase's own.+ await runEmbeddingPhase(store, config, tally, {+ plan: priceSpendPlan(+ misses.map((miss) => ({ chunkId: miss.chunkId, content: miss.content })),+ config,+ ),+ });+ }+ // Read every pending vector back from the store - the stored bytes+ // are canonical, whether they came from the cache or the provider -+ // and rewrite the cache in one atomic generation.+ const entries: Record<string, ReadonlyArray<number>> = { ...cache };+ for (const item of plan.pending) {+ const stored = store.embeddingForChunk(item.chunkId);+ if (stored === null) {+ throw new BenchEmbeddingError(+ `bench embedding cache: chunk ${item.chunkId} has no stored vector after the embedding phase`,+ );+ }+ entries[benchVectorCacheKey(signature, item.content)] = Object.freeze([...stored]);+ }+ writeVectorCache(runsDir, entries);+ return Object.freeze({+ provider: config.semantic.provider,+ model,+ signature,+ planned: plan.pending.length,+ cache_hits: hits.length,+ cache_misses: misses.length,+ tokens: plan.tokens,+ estimated_usd: plan.estimatedUsd,+ price_source: plan.quote.source,+ gate: plan.gate,+ ...(tally.spend !== undefined ? { forced: tally.spend.forced } : {}),+ });+ } finally {+ await store.close();+ }+}++/**+ * Read back the spend receipt of a resumed run whose index phase+ * completed in an earlier invocation. A run pinned to the semantic lane+ * without the artifact is broken state, not an empty receipt.+ */+export function readBenchEmbeddingReceipt(runDir: string): BenchEmbeddingReceipt {+ const path = join(runDir, BENCH_EMBEDDING_RECEIPT_FILENAME);+ if (!existsSync(path)) {+ throw new BenchEmbeddingError(+ `bench run is missing the embedding spend receipt at ${path} - the index phase of a semantic-pinned run must have written one`,+ );+ }+ let raw: unknown;+ try {+ raw = JSON.parse(readFileSync(path, "utf8"));+ } catch (e) {+ throw new BenchEmbeddingError(+ `bench embedding spend receipt is not readable JSON at ${path}: ${e instanceof Error ? e.message : String(e)}`,+ );+ }+ if (raw === null || typeof raw !== "object" || Array.isArray(raw)) {+ throw new BenchEmbeddingError(`bench embedding spend receipt at ${path} must be an object`);+ }+ return Object.freeze({ ...(raw as BenchEmbeddingReceipt) });+}diff --git a/src/core/bench/failure-modes.ts b/src/core/bench/failure-modes.tsindex f9d09726..30341dec 100644--- a/src/core/bench/failure-modes.ts+++ b/src/core/bench/failure-modes.ts@@ -24,16 +24,25 @@* injects `Brain/active.md` wholesale every session - so there is nothing* there to score.*- * Second, THE PRESSURE IS ON THE FLOOR, NOT THE GATE.- * `evaluateSurfacingGate` (`src/core/search/surfacing-gate.ts`) fails open- * by design: every non-empty, non-duplicate, non-slash, non-shell prompt- * retrieves, so its false-fire rate is ~1 by construction and scoring it- * would be theatre. The only- * discriminating bound in the decision core is- * `RECALL_INJECT_CONFIDENCE_FLOOR`, so that is where the anti-gaming term- * bites: {@link scoreProactiveRecall} counts a false fire exactly as- * heavily as a silent miss, which is what makes a strategy that always- * injects score strictly worse than one that abstains correctly.+ * Second, THE GATE IS SCOREABLE, AND THE BOUND IS THE GRADED KEY. The+ * structural predicate (`evaluateSurfacingGate`,+ * `src/core/search/surfacing-gate.ts`) still fails open by design - every+ * non-empty, non-duplicate, non-slash, non-shell prompt retrieves - so a+ * rate computed over THAT predicate alone would read ~1 by construction.+ * Admission does not ride that predicate: it rides the shared graded+ * surfacing key (`src/core/search/surfacing-key.ts`), channel-calibrated+ * absolute match quality (`idfWeightedCoverage`) compared against the+ * floor, which is a measured bound rather than a structural tautology.+ * The surfacing-replay suite (`src/core/bench/replay.ts`, `--suite+ * surfacing-replay`) is the instrument that scores it: it replays a+ * recorded prompt corpus through the shipped decision core and posts the+ * gate's false-fire and know-to-ask rates under the same+ * {@link scoreProactiveRecall} denominations, so the calibration is a+ * measured number that a re-run of the suite re-measures. The anti-gaming+ * term still bites: {@link scoreProactiveRecall} counts a false fire+ * exactly as heavily as a silent miss, which is what makes a strategy+ * that always injects score strictly worse than one that abstains+ * correctly.** A measured caveat that used to belong with the number, kept because it* is what the floor's current shape is a response to: through the shippeddiff --git a/src/core/bench/fixture.ts b/src/core/bench/fixture.tsindex 5b1f3574..feaeaa49 100644--- a/src/core/bench/fixture.ts+++ b/src/core/bench/fixture.ts@@ -19,12 +19,27 @@ import {type BenchFixture,type BenchFixtureContinuity,type BenchFixtureNote,+ type BenchJudgeInput,type BenchQuestion,RETRIEVAL_CATEGORIES,} from "./types.ts";+/**+ * Named relaxations of the canonical fixture invariants. Each option is+ * an opt-in a caller must vouch for explicitly - never a looser default.+ */+export interface ParseBenchFixtureOptions {+ /**+ * Accept `notes: []`. The replay converter passes this: a recorded+ * session with no ingested notes has nothing to materialize, and its+ * prompts are judged against an empty vault. Committed fixture files+ * keep the non-empty requirement.+ */+ readonly allowEmptyNotes?: boolean;+}+/** Parse and validate a raw fixture document. Throws named errors. */-export function parseBenchFixture(raw: unknown): BenchFixture {+export function parseBenchFixture(raw: unknown, opts?: ParseBenchFixtureOptions): BenchFixture {if (raw === null || typeof raw !== "object" || Array.isArray(raw)) {throw new Error("bench fixture: expected a JSON object");}@@ -34,7 +49,7 @@ export function parseBenchFixture(raw: unknown): BenchFixture {const description = nonEmptyString(record["description"]);const notesRaw = record["notes"];- if (!Array.isArray(notesRaw) || notesRaw.length === 0) {+ if (!Array.isArray(notesRaw) || (notesRaw.length === 0 && opts?.allowEmptyNotes !== true)) {throw new Error("bench fixture: notes must be a non-empty array");}const notes = notesRaw.map(parseNote);@@ -148,6 +163,7 @@ function parseQuestion(raw: unknown, index: number): BenchQuestion {`bench fixture: question ${id} has an unknown category (expected one of ${BENCH_CATEGORIES.join(", ")})`,);}+ const judgeInput = parseJudgeInput(record["judge_input"]);const question: BenchQuestion = Object.freeze({id,category,@@ -182,6 +198,13 @@ function parseQuestion(raw: unknown, index: number): BenchQuestion {...(nonEmptyString(record["prompt"]) !== undefined? { prompt: nonEmptyString(record["prompt"]) }: {}),+ // Replay glue (surfacing-replay): the prompt this question follows,+ // consumed by the structural gate the phase pipeline reproduces.+ // Present only when the fixture carries it, so every fixture without+ // one parses byte-identically.+ ...(nonEmptyString(record["previous_prompt"]) !== undefined+ ? { previous_prompt: nonEmptyString(record["previous_prompt"]) }+ : {}),// `expect_inject` is the one boolean field, and `false` is its most// load-bearing value (the anti-gaming half of the fixture), so it is// read by type rather than by truthiness.@@ -203,11 +226,39 @@ function parseQuestion(raw: unknown, index: number): BenchQuestion {...(stringArray(record["forbidden_ids"]) !== undefined? { forbidden_ids: stringArray(record["forbidden_ids"]) }: {}),+ // Judge glue (longmemeval): present only when the fixture carries+ // it, so every default-path fixture parses byte-identically.+ ...(judgeInput !== undefined ? { judge_input: judgeInput } : {}),});validateQuestionShape(question);return question;}+/**+ * Parse the optional official-prompt judge input. Absent means absent;+ * present it is validated as a whole - a half-stated input is a named+ * error, never a silently partial payload.+ */+function parseJudgeInput(raw: unknown): BenchJudgeInput | undefined {+ if (raw === undefined) return undefined;+ if (raw === null || typeof raw !== "object" || Array.isArray(raw)) {+ throw new Error("bench fixture: judge_input must be an object");+ }+ const record = raw as Record<string, unknown>;+ const question = nonEmptyString(record["question"]);+ if (question === undefined) throw new Error("bench fixture: judge_input needs a question");+ const answer = nonEmptyString(record["answer"]);+ const gold = stringArray(record["gold"]);+ if (gold === undefined || gold.length === 0) {+ throw new Error("bench fixture: judge_input needs a non-empty gold array");+ }+ return Object.freeze({+ question,+ ...(answer !== undefined ? { answer } : {}),+ gold: Object.freeze([...gold]),+ });+}+function validateQuestionShape(question: BenchQuestion): void {if (RETRIEVAL_CATEGORIES.has(question.category)) {if (question.query === undefined || (question.expected_paths ?? []).length === 0) {diff --git a/src/core/bench/judge.ts b/src/core/bench/judge.tsindex e3249f1e..e1d83fba 100644--- a/src/core/bench/judge.ts+++ b/src/core/bench/judge.ts@@ -18,7 +18,7 @@import { runJsonCommandBridge } from "../reliability/command-bridge.ts";-import type { BenchQuestionResult, BenchReport } from "./types.ts";+import type { BenchJudgeInput, BenchQuestionResult, BenchReport } from "./types.ts";export interface JudgeOutcome {readonly status: BenchReport["judge"]["status"];@@ -26,11 +26,39 @@ export interface JudgeOutcome {readonly verdicts?: Readonly<Record<string, boolean>>;}+/**+ * Evaluate the questions, optionally enriched with the suite-provided+ * judge input.+ *+ * The stdin payload stays `{ questions: [...] }`; a question whose+ * suite provides {@link BenchJudgeInput} carries three extra fields -+ * `question`, `answer` (when the dataset states one) and `gold` - and a+ * question without one keeps the exact pre-existing shape, so payloads+ * for suites without judge input are unchanged byte for byte. The+ * suite's prompt constants are self-written (see+ * `LONGMEMEVAL_PROMPT_PROVENANCE`); nothing upstream pins them.+ */export function runJudge(cmd: string | undefined,questions: ReadonlyArray<BenchQuestionResult>,+ judgeInputs?: ReadonlyMap<string, BenchJudgeInput>,): JudgeOutcome {- const result = runJsonCommandBridge(cmd, { questions }, { label: "judge command" });+ const payload = {+ questions: questions.map((result) => {+ const input = judgeInputs?.get(result.id);+ if (input === undefined) return result;+ return {+ ...result,+ question: input.question,+ ...(input.answer !== undefined ? { answer: input.answer } : {}),+ gold: [...input.gold],+ ...(input.evidence !== undefined+ ? { evidence: input.evidence.map((e) => ({ path: e.path, text: e.text })) }+ : {}),+ };+ }),+ };+ const result = runJsonCommandBridge(cmd, payload, { label: "judge command" });if (result.status === "skipped") return Object.freeze({ status: "skipped" });if (result.status === "error") {return Object.freeze({ status: "error", detail: result.detail });diff --git a/src/core/bench/longmemeval.ts b/src/core/bench/longmemeval.tsnew file mode 100644index 00000000..db91761a--- /dev/null+++ b/src/core/bench/longmemeval.ts@@ -0,0 +1,696 @@+/**+ * LongMemEval benchmark suite adapter (recall-quality wave, t_607d429d).+ *+ * LongMemEval (Wu et al., 2024) is the long-term-memory benchmark the+ * field reports recall_all@5 on. This module adds it beside LoCoMo as an+ * ADDITIVE named suite: a fail-fast parser over the official dataset+ * shape (a JSON array of question entries, each carrying its haystack+ * sessions), and a converter into the existing {@link BenchFixture} the+ * unchanged `runMemoryBench` consumes.+ *+ * Network-free by design: the loader is pure over its input file. The+ * committed sample fixtures certify CI: `longmemeval-official-sample.json`+ * pins the OFFICIAL dataset shape, `longmemeval-sample.json` the legacy+ * sample shape; the full dataset arrives as an operator-supplied path+ * resolved by the bench verb's literal-then-repo-fixture-dir logic. The+ * official download lives at https://github.com/xiaowu0162/LongMemEval+ * (the dataset ships as JSON: longmemeval_s.json, longmemeval_m.json,+ * longmemeval_oracle.json) - never fetched at run time.+ *+ * Both dataset shapes are accepted, official first: the official files+ * spell the keys `question_id` / `haystack_session_ids` /+ * `haystack_sessions`, mark abstention by a question id ending in+ * `_abs`, and use the six official question types; the legacy sample+ * shape uses `q_id` / `haystack_session_id` / `haystack_session`, an+ * explicit `abstention` question type, and the pre-wave type spellings.+ *+ * Two traps are handled HERE, at conversion, not downstream:+ *+ * - `expected_text` is NEVER set. `evaluateQuestion` ignores it for+ * retrieval categories, so a gold answer pinned there would silently+ * score nothing. The gold answer rides the judge payload instead+ * (judge.ts), and scoring is expected_paths containment at the+ * {@link LONGMEMEVAL_RECALL_CUTOFF}.+ * - Gold session ids join by direct set membership against the entry's+ * own haystack ids; an unknown id is a named parse error. Ids are+ * sanitized only when they become note paths.+ * - Each entry's evidence is namespaced under its own question's+ * subtree (`sessions/<question_id>/...`): LongMemEval scores every+ * question against its OWN haystack (~50 sessions), and evidence+ * pooled across entries would have every query search the union of+ * all haystacks. Residual, stated honestly: the fixture schema has+ * no per-question retrieval scope, so the disjoint subtrees keep+ * the gold paths per-question but cannot stop the ranker from+ * surfacing another scope's notes inside the cutoff - full+ * per-question retrieval needs a scope field on the fixture+ * question plus a rank-time filter in the retrieve phase.+ *+ * Abstention questions are dropped at conversion time with the exclusion+ * count recorded in the suite receipt - the fixture parser rejects+ * unknown categories, so pass-through is not an option, and the report+ * family surfaces the count rather than hiding it.+ */++import { readFileSync } from "node:fs";++import { parseBenchFixture } from "./fixture.ts";+import {+ RETRIEVAL_CATEGORIES,+ type BenchCategory,+ type BenchFixture,+ type BenchFixtureContinuity,+ type BenchFixtureNote,+ type BenchQuestion,+} from "./types.ts";++/** The suite's registered name in the bench verb's suite registry. */+export const LONGMEMEVAL_SUITE_NAME = "longmemeval";++/**+ * Provenance of the answer-judging prompts below, stated honestly: they+ * are SELF-WRITTEN in the spirit of the upstream evaluation - its+ * `evaluate_qa.py` judges a model's response against the reference+ * answer with per-question-type prompts - but they are NOT a+ * transcription of the upstream text, and nothing upstream pins their+ * wording. The dataset itself ships as JSON in the same repository and+ * is downloaded by operators - never at run time.+ */+export const LONGMEMEVAL_PROMPT_PROVENANCE =+ "self-written prompts following the evaluate_qa.py approach in github.com/xiaowu0162/LongMemEval (arXiv:2410.10813); not transcribed from upstream - the dataset ships as longmemeval_s.json / longmemeval_m.json / longmemeval_oracle.json";++/**+ * Answer-judging prompt, system half (self-written; see+ * {@link LONGMEMEVAL_PROMPT_PROVENANCE}). The external judge command+ * composes its model call from this and the per-question template, so+ * the command itself stays a dumb model call and the prompt text has+ * exactly one home in the tree.+ */+export const LONGMEMEVAL_JUDGE_SYSTEM_PROMPT = Object.freeze(+ "You are a meticulous evaluator of long-term conversational memory. " ++ "Judge the provided answer against the reference answer and the gold " ++ "evidence, using only what the evidence supports. Answer with strict " ++ 'JSON: {"correct": true} when the answer is supported, {"correct": false} otherwise.',+);++/**+ * Answer-judging prompt, per-question half (self-written; see+ * {@link LONGMEMEVAL_PROMPT_PROVENANCE}). The placeholders are the judge+ * payload's own field names, so a judge command renders the prompt+ * straight from the stdin JSON. Gold evidence is carried as the gold+ * sessions' ids (the payload stays bounded); a judge that wants their+ * conversation text resolves the ids from the dataset it already has.+ */+export const LONGMEMEVAL_JUDGE_QUESTION_TEMPLATE = Object.freeze(+ "Question: {question}\n" ++ "Reference answer: {answer}\n" ++ "Gold evidence sessions: {gold}\n" ++ "Decide whether the answer is supported by the gold evidence.",+);++export interface LongMemEvalTurn {+ readonly role: string;+ readonly content: string;+}++/** One dataset entry, in the official LongMemEval question shape. */+export interface LongMemEvalEntry {+ readonly q_id: string;+ readonly question_type: string;+ readonly question: string;+ readonly answer?: string;+ /**+ * The date the question was asked (official `question_date`). An+ * entry that states none is dated by its last haystack session - the+ * question follows the sessions it was built from.+ */+ readonly question_date: string;+ readonly haystack_session_id: ReadonlyArray<string>;+ readonly haystack_session: ReadonlyArray<ReadonlyArray<LongMemEvalTurn>>;+ readonly haystack_dates: ReadonlyArray<string>;+ readonly answer_session_ids: ReadonlyArray<string>;+}++export interface LongMemEvalDataset {+ readonly name?: string;+ readonly entries: ReadonlyArray<LongMemEvalEntry>;+}++/** What conversion decided, surfaced beside the converted fixture. */+export interface LongMemEvalReceipt {+ /** Abstention questions dropped at conversion time. */+ readonly abstention_excluded: number;+}++export interface LongMemEvalConversion {+ readonly fixture: BenchFixture;+ readonly receipt: LongMemEvalReceipt;+}++class LongMemEvalParseError extends Error {}++/** The explicit legacy-shape question type whose entries measure abstention. */+export const LONGMEMEVAL_ABSTENTION_TYPE = "abstention";++/** Suffix the official dataset puts on abstention question ids. */+const OFFICIAL_ABSTENTION_SUFFIX = "_abs";++/**+ * True when an entry measures abstention and is excluded from scoring.+ * The official dataset marks abstention by a `question_id` ending in+ * `_abs`; the legacy sample shape uses the explicit `abstention`+ * question type. Both paths stay live.+ */+export function isLongMemEvalAbstention(+ entry: Pick<LongMemEvalEntry, "q_id" | "question_type">,+): boolean {+ return (+ entry.question_type === LONGMEMEVAL_ABSTENTION_TYPE ||+ entry.q_id.endsWith(OFFICIAL_ABSTENTION_SUFFIX)+ );+}++/**+ * The recall cutoff the suite scores at: a question passes retrieval+ * when EVERY gold session note ranks inside the top k. Drives both the+ * converted questions' `top_k` and the strict report metric.+ */+export const LONGMEMEVAL_RECALL_CUTOFF = 5;++/**+ * Question types -> OSB's canonical retrieval categories. The official+ * dataset's six types come first (`single-session-*` all read as the+ * single-hop category - each asks about one session, only the turn+ * role or preference focus differs, and scoring is identical+ * expected_paths containment for all of them); the legacy sample+ * shape's spellings follow. Abstention entries map to nothing: they+ * are excluded, never converted.+ */+const QUESTION_TYPE_TO_CATEGORY: Readonly<Record<string, BenchCategory>> = Object.freeze({+ "single-session-user": "single_hop",+ "single-session-assistant": "single_hop",+ "single-session-preference": "single_hop",+ "multi-session": "multi_evidence",+ "temporal-reasoning": "temporal",+ "knowledge-update": "contradiction",+ "single-hop": "single_hop",+ "multi-hop": "multi_evidence",+ "open-domain": "single_hop",+});++/** Every question type the parser accepts, abstention included. */+export const LONGMEMEVAL_QUESTION_TYPES: ReadonlyArray<string> = Object.freeze([+ ...Object.keys(QUESTION_TYPE_TO_CATEGORY),+ LONGMEMEVAL_ABSTENTION_TYPE,+]);++/** Minutes between turns of one session when deriving turn timestamps. */+const TURN_TIMESTAMP_STEP_MS = 60_000;++/**+ * Parse and validate a raw LongMemEval dataset: either the official bare+ * array of question entries or a `{ name, questions }` wrapper naming+ * the dataset. Fail-fast with a named {@link LongMemEvalParseError}.+ *+ * Haystack sessions are merged across entries by id for validation:+ * entries share sessions, and one id must carry the same TURNS+ * everywhere - a content mismatch is a named error rather than a+ * silently doubled note. Dates are assigned per instance upstream, so+ * a date difference between entries is tolerated (first write wins).+ */+export function parseLongMemEvalDataset(raw: unknown): LongMemEvalDataset {+ let entriesRaw: ReadonlyArray<unknown>;+ let name: string | undefined;+ if (Array.isArray(raw)) {+ entriesRaw = raw;+ } else if (+ raw !== null &&+ typeof raw === "object" &&+ Array.isArray((raw as Record<string, unknown>)["questions"])+ ) {+ const wrapper = raw as Record<string, unknown>;+ if (typeof wrapper["name"] === "string" && wrapper["name"].trim() !== "") {+ name = wrapper["name"];+ }+ entriesRaw = wrapper["questions"] as ReadonlyArray<unknown>;+ } else {+ throw new LongMemEvalParseError(+ "LongMemEval dataset must be an array of questions or a { name, questions } object",+ );+ }+ if (entriesRaw.length === 0) {+ throw new LongMemEvalParseError("LongMemEval dataset needs a non-empty questions array");+ }+ const sessions = new Map<+ string,+ { date: string; turns: ReadonlyArray<LongMemEvalTurn>; entry: string }+ >();+ const entries = entriesRaw.map((entry, index) => parseEntry(entry, index, sessions));+ return { ...(name !== undefined ? { name } : {}), entries };+}++/**+ * Read a field under both dataset spellings: the official files spell+ * it `official`, the legacy sample shape `legacy`. Official first; a+ * legacy key is read only when the official one is absent.+ */+function readKey(r: Record<string, unknown>, official: string, legacy: string): unknown {+ const value = r[official];+ return value !== undefined ? value : r[legacy];+}++function parseEntry(+ raw: unknown,+ index: number,+ sessions: Map<string, { date: string; turns: ReadonlyArray<LongMemEvalTurn>; entry: string }>,+): LongMemEvalEntry {+ if (raw === null || typeof raw !== "object") {+ throw new LongMemEvalParseError(`LongMemEval dataset: questions[${index}] must be an object`);+ }+ const r = raw as Record<string, unknown>;+ const qId = asString(+ readKey(r, "question_id", "q_id"),+ `questions[${index}].question_id (legacy q_id)`,+ );+ const questionType = asString(r["question_type"], `questions[${index}] (${qId}).question_type`);+ if (!(LONGMEMEVAL_QUESTION_TYPES as ReadonlyArray<string>).includes(questionType)) {+ throw new LongMemEvalParseError(+ `LongMemEval dataset: question '${qId}' has an unknown question_type '${questionType}' ` ++ `(expected one of ${LONGMEMEVAL_QUESTION_TYPES.join(", ")})`,+ );+ }+ const abstention = isLongMemEvalAbstention({ q_id: qId, question_type: questionType });+ const question = asString(r["question"], `questions[${index}] (${qId}).question`);+ const answer = answerOf(r["answer"]);++ const sessionIds = stringArray(+ readKey(r, "haystack_session_ids", "haystack_session_id"),+ `questions[${index}] (${qId}).haystack_session_ids (legacy haystack_session_id)`,+ true,+ );+ const sessionsRaw = readKey(r, "haystack_sessions", "haystack_session");+ if (!Array.isArray(sessionsRaw) || sessionsRaw.length !== sessionIds.length) {+ throw new LongMemEvalParseError(+ `LongMemEval dataset: question '${qId}' haystack_sessions (legacy haystack_session) ` ++ `must be an array aligned with haystack_session_ids`,+ );+ }+ const dates = stringArray(+ r["haystack_dates"],+ `questions[${index}] (${qId}).haystack_dates`,+ true,+ );+ if (dates.length !== sessionIds.length) {+ throw new LongMemEvalParseError(+ `LongMemEval dataset: question '${qId}' haystack_dates must be an array aligned with haystack_session_ids`,+ );+ }+ const localIds = new Set<string>();+ sessionIds.forEach((sessionId, j) => {+ localIds.add(sessionId);+ const turns = parseTurns(+ sessionsRaw[j],+ `questions[${index}] (${qId}).haystack_sessions[${j}]`,+ );+ const date = asValidDate(dates[j]!, `questions[${index}] (${qId}).haystack_dates[${j}]`);+ mergeSession(sessions, sessionId, date, turns, qId);+ });++ let gold: ReadonlyArray<string> = [];+ if (!abstention) {+ gold = stringArray(+ r["answer_session_ids"],+ `questions[${index}] (${qId}).answer_session_ids`,+ true,+ );+ if (gold.length === 0) {+ throw new LongMemEvalParseError(+ `LongMemEval dataset: question '${qId}' (${questionType}) needs a non-empty answer_session_ids`,+ );+ }+ for (const id of gold) {+ if (!localIds.has(id)) {+ throw new LongMemEvalParseError(+ `LongMemEval dataset: question '${qId}' references unknown session '${id}'`,+ );+ }+ }+ }+ // The official entries carry question_date; an entry that states none+ // is dated by its last haystack session.+ const questionDateRaw = r["question_date"];+ const questionDate =+ questionDateRaw === undefined+ ? dates[dates.length - 1]!+ : asValidDate(+ asString(questionDateRaw, `questions[${index}] (${qId}).question_date`),+ `questions[${index}] (${qId}).question_date`,+ );+ return {+ q_id: qId,+ question_type: questionType,+ question,+ ...(answer !== undefined ? { answer } : {}),+ question_date: questionDate,+ haystack_session_id: sessionIds,+ haystack_session: sessionIds.map((_, j) =>+ parseTurns(sessionsRaw[j], `haystack_sessions[${j}]`),+ ),+ haystack_dates: dates,+ answer_session_ids: gold,+ };+}++function mergeSession(+ sessions: Map<string, { date: string; turns: ReadonlyArray<LongMemEvalTurn>; entry: string }>,+ sessionId: string,+ date: string,+ turns: ReadonlyArray<LongMemEvalTurn>,+ entryId: string,+): void {+ const existing = sessions.get(sessionId);+ if (existing !== undefined) {+ // Upstream assigns haystack dates PER INSTANCE, so the same session+ // id can legitimately carry a different date in each entry; the+ // first write wins. Only a content mismatch means the dataset is+ // inconsistent - one id whose turns disagree between entries.+ if (JSON.stringify(existing.turns) !== JSON.stringify(turns)) {+ throw new LongMemEvalParseError(+ `LongMemEval dataset: session '${sessionId}' is inconsistent between entries '${existing.entry}' and '${entryId}'`,+ );+ }+ return;+ }+ sessions.set(sessionId, { date, turns, entry: entryId });+}++function parseTurns(raw: unknown, field: string): ReadonlyArray<LongMemEvalTurn> {+ if (!Array.isArray(raw) || raw.length === 0) {+ throw new LongMemEvalParseError(`LongMemEval dataset: ${field} must be a non-empty turn array`);+ }+ return raw.map((turn, k) => {+ if (turn === null || typeof turn !== "object") {+ throw new LongMemEvalParseError(`LongMemEval dataset: ${field}[${k}] must be an object`);+ }+ const t = turn as Record<string, unknown>;+ return {+ role: asString(t["role"], `${field}[${k}].role`),+ content: asString(t["content"], `${field}[${k}].content`),+ };+ });+}++function asString(value: unknown, field: string): string {+ if (typeof value !== "string" || value.trim() === "") {+ throw new LongMemEvalParseError(`LongMemEval dataset: ${field} must be a non-empty string`);+ }+ return value;+}++/**+ * Parse a dataset date into epoch milliseconds, deterministically as+ * UTC. The official dates look like `2023/05/20 (Sat) 02:21`, which+ * JavaScript would read in the host's local zone - so the slash forms+ * are rebuilt as UTC by hand. A naive ISO date-time (no offset) is read+ * as UTC by the same rule, date-only ISO is UTC by spec, and+ * offset-explicit ISO forms parse as stated. Any other shape returns+ * NaN - the caller refuses it by name rather than letting the host+ * zone decide.+ */+function parseDatasetDateMs(value: string): number {+ const trimmed = value.trim();+ const slash = /^(\d{4})\/(\d{1,2})\/(\d{1,2})(?:\s+\([^()]*\))?(?:\s+(\d{1,2}):(\d{2}))?$/.exec(+ trimmed,+ );+ if (slash !== null) {+ return Date.UTC(+ Number(slash[1]),+ Number(slash[2]) - 1,+ Number(slash[3]),+ slash[4] !== undefined ? Number(slash[4]) : 0,+ slash[5] !== undefined ? Number(slash[5]) : 0,+ );+ }+ const naiveIso = /^(\d{4})-(\d{2})-(\d{2})T(\d{1,2}):(\d{2})(?::(\d{2})(?:\.(\d{1,3}))?)?$/.exec(+ trimmed,+ );+ if (naiveIso !== null) {+ return Date.UTC(+ Number(naiveIso[1]),+ Number(naiveIso[2]) - 1,+ Number(naiveIso[3]),+ Number(naiveIso[4]),+ Number(naiveIso[5]),+ naiveIso[6] !== undefined ? Number(naiveIso[6]) : 0,+ naiveIso[7] !== undefined ? Number(naiveIso[7]) : 0,+ );+ }+ if (+ /^\d{4}-\d{2}-\d{2}$/.test(trimmed) ||+ /^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}(:\d{2}(\.\d{1,3})?)?(Z|[+-]\d{2}:?\d{2})$/.test(trimmed)+ ) {+ return Date.parse(trimmed);+ }+ return Number.NaN;+}++function asValidDate(value: string, field: string): string {+ if (Number.isNaN(parseDatasetDateMs(value))) {+ throw new LongMemEvalParseError(+ `LongMemEval dataset: ${field} must be a valid date, got '${value}'`,+ );+ }+ return value;+}++function stringArray(value: unknown, field: string, nonEmpty: boolean): ReadonlyArray<string> {+ if (!Array.isArray(value) || !value.every((item) => typeof item === "string" && item !== "")) {+ throw new LongMemEvalParseError(`LongMemEval dataset: ${field} must be an array of strings`);+ }+ if (nonEmpty && value.length === 0) {+ throw new LongMemEvalParseError(`LongMemEval dataset: ${field} must be a non-empty array`);+ }+ return Object.freeze([...value]);+}++/** Sanitize a dataset id into one safe note-path segment. */+function sanitizePathSegment(raw: string): string {+ return raw.replace(/[^A-Za-z0-9_-]/g, "-");+}++/**+ * The path scope of one question's evidence: every note, continuity+ * record and expected path of an entry lives under+ * `sessions/<question_id>/`, so one question's haystack never pools+ * with another's. Two distinct question ids that sanitize to the same+ * scope would silently merge haystacks, so that is a named error.+ */+function questionScope(qId: string, claimed: Map<string, string>): string {+ const scope = sanitizePathSegment(qId);+ const owner = claimed.get(scope);+ if (owner !== undefined) {+ throw new LongMemEvalParseError(+ owner === qId+ ? `LongMemEval dataset: question id '${qId}' appears twice`+ : `LongMemEval dataset: question ids '${owner}' and '${qId}' sanitize to the same path scope '${scope}'; their haystacks would merge`,+ );+ }+ claimed.set(scope, qId);+ return scope;+}++/** Vault-relative note path for a session inside its question's scope. */+function sessionNotePath(scope: string, sessionId: string): string {+ return `sessions/${scope}/${sanitizePathSegment(sessionId)}.md`;+}++/**+ * Note body for one scoped session copy. The header names the question+ * scope on purpose: a session shared by several entries materializes+ * once per scope, and bodies that stayed byte-identical would collide+ * in the indexer's content-hash skip - only the first scope's copy+ * would ever index, dangling every other scope's gold path.+ */+function sessionNoteBody(+ scope: string,+ sessionId: string,+ turns: ReadonlyArray<LongMemEvalTurn>,+): string {+ return (+ `# Session ${sessionId} (question ${scope})\n\n` ++ turns.map((t) => `${t.role}: ${t.content}`).join("\n")+ );+}++function turnTimestamp(sessionDate: string, turnIndex: number): string {+ return new Date(+ parseDatasetDateMs(sessionDate) + turnIndex * TURN_TIMESTAMP_STEP_MS,+ ).toISOString();+}++/**+ * The judge reference answer, as the payload may carry it: strings pass+ * through; upstream states some counting answers as numbers, so finite+ * numbers are coerced with String(). Any other non-string type stays+ * refused - an answer that cannot be a string is dropped, never guessed.+ */+function answerOf(value: unknown): string | undefined {+ if (typeof value === "string" && value !== "") return value;+ if (typeof value === "number" && Number.isFinite(value)) return String(value);+ return undefined;+}++/**+ * Convert a parsed LongMemEval dataset into an OSB {@link BenchFixture}+ * plus its receipt. Each entry's evidence is namespaced under its own+ * question's subtree - its sessions become evidence notes and+ * session_turn continuity records at `sessions/<question_id>/...` - and+ * every non-abstention question becomes a retrieval question whose+ * expected_paths point at its gold session notes inside that same+ * subtree and whose top_k is the {@link LONGMEMEVAL_RECALL_CUTOFF}.+ * Abstention entries are excluded with the count recorded.+ *+ * Scoping is what keeps the suite's task like-for-like: LongMemEval+ * scores every question against ITS OWN haystack (~50 sessions), so+ * evidence pooled across entries would have every query search the+ * union of all haystacks. A session shared by several entries is+ * materialized once per scope - the trade is cross-entry note dedupe+ * for per-question isolation, which is what the metric scores.+ */+export function longMemEvalToBenchFixture(dataset: LongMemEvalDataset): LongMemEvalConversion {+ let abstentionExcluded = 0;+ const notes: BenchFixtureNote[] = [];+ const continuity: BenchFixtureContinuity[] = [];+ const questions: BenchQuestion[] = [];+ const claimedScopes = new Map<string, string>();+ for (const entry of dataset.entries) {+ if (isLongMemEvalAbstention(entry)) {+ abstentionExcluded += 1;+ continue;+ }+ const scope = questionScope(entry.q_id, claimedScopes);+ const scopedPaths = new Map<string, string>();+ const claimedInScope = new Map<string, string>();+ entry.haystack_session_id.forEach((sessionId, j) => {+ if (scopedPaths.has(sessionId)) return;+ const path = sessionNotePath(scope, sessionId);+ // Distinct session ids can sanitize to one note path (a/b and+ // a-b); within one scope the evidence of both would silently+ // merge into one note, so the collision is a named parse error.+ const collisionOwner = claimedInScope.get(path);+ if (collisionOwner !== undefined) {+ throw new LongMemEvalParseError(+ `LongMemEval dataset: question '${entry.q_id}' has session ids '${collisionOwner}' and '${sessionId}' ` ++ `that sanitize to the same note path '${path}'; the evidence of both would merge`,+ );+ }+ claimedInScope.set(path, sessionId);+ const turns = entry.haystack_session[j]!;+ const date = entry.haystack_dates[j]!;+ notes.push({ path, body: sessionNoteBody(scope, sessionId, turns) });+ turns.forEach((turn, i) => {+ continuity.push({+ kind: "session_turn" as const,+ created_at: turnTimestamp(date, i),+ payload: {+ question_id: entry.q_id,+ session_id: sessionId,+ role: turn.role,+ text: turn.content,+ },+ });+ });+ scopedPaths.set(sessionId, path);+ });+ questions.push({+ id: entry.q_id,+ category: QUESTION_TYPE_TO_CATEGORY[entry.question_type]!,+ query: entry.question,+ top_k: LONGMEMEVAL_RECALL_CUTOFF,+ expected_paths: entry.answer_session_ids.map((id) => {+ const path = scopedPaths.get(id);+ if (path === undefined) {+ // The parser guarantees gold ids join the entry's own+ // haystack; this names the impossible instead of emitting a+ // dangling path.+ throw new LongMemEvalParseError(+ `LongMemEval dataset: question '${entry.q_id}' references unknown session '${id}'`,+ );+ }+ return path;+ }),+ judge_input: Object.freeze({+ question: entry.question,+ ...(entry.answer !== undefined ? { answer: entry.answer } : {}),+ gold: Object.freeze([...entry.answer_session_ids]),+ }),+ });+ }+ if (questions.length === 0) {+ // A dataset of only abstention entries converts to zero questions,+ // which parseBenchFixture refuses generically; name the real cause -+ // the abstention filter, not a missing dataset.+ throw new LongMemEvalParseError(+ `LongMemEval dataset: every one of the ${abstentionExcluded} question(s) is an abstention entry and was excluded from scoring; nothing remains to evaluate`,+ );+ }+ const fixture = parseBenchFixture({+ name: `longmemeval-${dataset.name ?? "suite"}`,+ description:+ "LongMemEval dataset converted to the OSB bench fixture; each question's haystack is scoped under its own subtree and abstention questions are excluded from scoring.",+ notes,+ continuity,+ questions,+ });+ return { fixture, receipt: { abstention_excluded: abstentionExcluded } };+}++/** Load a LongMemEval dataset file and convert it to a suite load. */+export function loadLongMemEvalFixture(path: string): LongMemEvalConversion {+ let raw: unknown;+ try {+ raw = JSON.parse(readFileSync(path, "utf8"));+ } catch (e) {+ throw new LongMemEvalParseError(+ `LongMemEval dataset not readable JSON at ${path}: ${e instanceof Error ? e.message : String(e)}`,+ );+ }+ return longMemEvalToBenchFixture(parseLongMemEvalDataset(raw));+}++/** One persisted retrieval result the strict metric reads. */+export interface RecallAllRetrieved {+ readonly id: string;+ /** Result paths in rank order. */+ readonly paths?: ReadonlyArray<string>;+}++export interface RecallAllScore {+ /** Questions scored: the non-abstention, retrieval-category ones. */+ readonly scored: number;+ /** Questions with EVERY gold session note inside the cutoff. */+ readonly passed: number;+}++/**+ * Strict recall_all@{@link LONGMEMEVAL_RECALL_CUTOFF}: the count of+ * scored questions whose EVERY gold session note ranks inside the+ * cutoff, over the PERSISTED retrieval results. This is the aggregate+ * roll-off of the same containment rule `evaluateQuestion` applies per+ * question - not a second scorer - kept as a named metric because the+ * field reports recall_all@5, the number the memory field compares.+ */+export function scoreLongMemEvalRecall(+ questions: ReadonlyArray<BenchQuestion>,+ retrieved: ReadonlyArray<RecallAllRetrieved>,+): RecallAllScore {+ const byId = new Map(retrieved.map((result) => [result.id, result]));+ let scored = 0;+ let passed = 0;+ for (const question of questions) {+ if (!RETRIEVAL_CATEGORIES.has(question.category)) continue;+ scored += 1;+ const top = new Set((byId.get(question.id)?.paths ?? []).slice(0, LONGMEMEVAL_RECALL_CUTOFF));+ if ((question.expected_paths ?? []).every((path) => top.has(path))) passed += 1;+ }+ return { scored, passed };+}diff --git a/src/core/bench/phases.ts b/src/core/bench/phases.tsindex d97a66a9..e2c5e193 100644--- a/src/core/bench/phases.ts+++ b/src/core/bench/phases.ts@@ -27,6 +27,12 @@ import {type RecallInjectDecision,} from "../brain/recall-inject.ts";import { resolveSearchConfig, search } from "../search/index.ts";+import { evaluateSurfacingGate } from "../search/surfacing-gate.ts";+import {+ BENCH_EMBEDDING_RECEIPT_FILENAME,+ embedBenchVaultIndex,+ readBenchEmbeddingReceipt,+} from "./embedding-cache.ts";import {benchRecallRetriever,classifyRecallDecision,@@ -37,6 +43,7 @@ import {} from "./failure-modes.ts";import { fixtureHash, materializeBenchVault } from "./fixture.ts";import { runJudge } from "./judge.ts";+import { LONGMEMEVAL_SUITE_NAME, scoreLongMemEvalRecall } from "./longmemeval.ts";import {benchResultsDir,benchVaultDir,@@ -48,11 +55,17 @@ import {} from "./run-store.ts";import {BENCH_REPORT_SCHEMA,+ DEFAULT_BENCH_KNOB_PIN,RETRIEVAL_CATEGORIES,type BenchFixture,+ type BenchEmbeddingReceipt,+ type BenchLongMemEvalFamily,+ type BenchPinnedKnobs,type BenchQuestion,type BenchQuestionResult,type BenchReport,+ type BenchSuiteCapabilities,+ type BenchSuiteReceipt,} from "./types.ts";/**@@ -67,10 +80,43 @@ const BENCH_REACH = TRANSPORT_REACH.local;export interface BenchRunOptions {readonly fixture: BenchFixture;readonly runsDir: string;+ /** Registered suite name, when the run goes through a named suite. */+ readonly suite?: string;+ /**+ * What the run's suite may do, set by the CLI verb from the suite+ * registry. Inert on its own: a capability is exercised only when the+ * run's knob pin enables the feature too.+ */+ readonly capabilities?: BenchSuiteCapabilities;+ /**+ * Search-configuration knobs pinned for this run, applied last via+ * `resolveSearchConfig` and folded into the run identity (the+ * checkpoint hash). Absent means {@link DEFAULT_BENCH_KNOB_PIN}.+ */+ readonly pinnedKnobs?: BenchPinnedKnobs;/** Resume an existing run id; validates the fixture hash first. */readonly resume?: string;+ /**+ * Optional admission floor override for the proactive-recall decisions,+ * passed to the decision core's `confidenceFloor` option, which routes+ * through the shared surfacing calculator. Absent keeps the shipped+ * default (`RECALL_INJECT_CONFIDENCE_FLOOR`). The surfacing-replay+ * suite sweeps this to measure gate calibration.+ *+ * Part of the run identity: a resumed run whose floor changed fails+ * the identity guard instead of deciding the remaining questions under+ * a new floor while the persisted ones keep the old. A floor change+ * takes effect in a fresh run id.+ */+ readonly recallFloor?: number;/** Optional external judge command (config bench_judge_cmd). */readonly judgeCmd?: string;+ /**+ * The suite loader's conversion receipt, threaded through to the+ * report family - for LongMemEval, how many abstention questions the+ * conversion excluded from scoring.+ */+ readonly suiteReceipt?: BenchSuiteReceipt;readonly now?: Date;}@@ -121,17 +167,87 @@ interface RetrievedQuestion {* provider it does not recognise makes this throw. That is a loud, named* failure rather than a silently different bench.*/-export function benchSearchConfig(vault: string): ReturnType<typeof resolveSearchConfig> {- return resolveSearchConfig({ vault, overrides: { semantic: { enabled: false } } });+/**+ * The search configuration every phase uses, driven by the run's knob+ * pin.+ *+ * `resolveSearchConfig` still reads `process.env`, and overrides are+ * applied last and win, so the pin is what makes the harness's network-+ * freedom an invariant instead of an inherited accident. The default pin+ * ({@link DEFAULT_BENCH_KNOB_PIN}) is the hardcoded semantic-off override+ * this function always applied - a named value now, so the default run+ * identity is deterministic and locomo report numbers stay identical. A+ * suite that declares the embeddings capability may pin the semantic+ * lane on (the deterministic local provider keeps the run network-free).+ *+ * Exported so the invariant is assertable directly. It has to be: a test+ * that sets the env vars and compares two reports passes whether or not+ * the override is there, because reaching the embedding lane also needs+ * an index built with embeddings, which the default harness does not+ * build. The resolved config is where the difference is real, so that is+ * what the test reads.+ *+ * One residual, named rather than implied: `resolveSearchConfig` parses+ * the provider name BEFORE merging overrides, so an env var naming a+ * provider it does not recognise makes this throw. That is a loud, named+ * failure rather than a silently different bench.+ */+export function benchSearchConfig(+ vault: string,+ pinnedKnobs: BenchPinnedKnobs = DEFAULT_BENCH_KNOB_PIN,+): ReturnType<typeof resolveSearchConfig> {+ return resolveSearchConfig({ vault, overrides: pinnedKnobs });}+/** Char budget per evidence excerpt a judged question carries. */+const JUDGE_EVIDENCE_EXCERPT_CHARS = 800;+export async function runMemoryBench(opts: BenchRunOptions): Promise<BenchReport> {+ // Refused BEFORE any run state exists (pr-250 review, L9): the floor+ // routes into the shared surfacing calculator, whose own contract+ // refuses out-of-range values per question - so an out-of-range floor+ // used to buy a full run whose every proactive decision was a+ // retrievalError, paid after ingest and index, instead of this one+ // named error. The bound is the calculator's own: a finite number in+ // [0, 1]. Zero stays legal - the replay suite's permissive sweep arm+ // uses it as the maximally permissive calibration point.+ if (+ opts.recallFloor !== undefined &&+ !(Number.isFinite(opts.recallFloor) && opts.recallFloor >= 0 && opts.recallFloor <= 1)+ ) {+ throw new Error(+ `bench run refused: recallFloor ${opts.recallFloor} is outside [0, 1]; the admission floor must be a finite number in the unit interval`,+ );+ }+ const pinnedKnobs = opts.pinnedKnobs ?? DEFAULT_BENCH_KNOB_PIN;const run: BenchRunHandle =opts.resume !== undefined- ? loadBenchRun(opts.runsDir, opts.resume, { expectFixture: opts.fixture })- : createBenchRun(opts.runsDir, opts.fixture, opts.now ? { now: opts.now } : {});+ ? loadBenchRun(opts.runsDir, opts.resume, {+ expectFixture: opts.fixture,+ pinnedKnobs,+ ...(opts.recallFloor !== undefined ? { recallFloor: opts.recallFloor } : {}),+ })+ : createBenchRun(opts.runsDir, opts.fixture, {+ ...(opts.now !== undefined ? { now: opts.now } : {}),+ pinnedKnobs,+ ...(opts.recallFloor !== undefined ? { recallFloor: opts.recallFloor } : {}),+ });let checkpoint = run.checkpoint;const vault = benchVaultDir(run.runDir);+ // One resolved config for every phase: the pin cannot drift between+ // the index warmup and the timed retrievals.+ const config = benchSearchConfig(vault, pinnedKnobs);+ // The capability gate: the semantic lane is reachable only when the+ // run's suite declared the embeddings capability, so a pin can never+ // silently arm a lane the suite never asked for.+ if (config.semantic.enabled && opts.capabilities?.embeddings !== true) {+ throw new Error(+ "bench run pins the semantic lane on without the embeddings capability - declare { embeddings: true } for the suite or keep the semantic lane pinned off",+ );+ }+ // Present when this invocation ran the embedding index phase; read+ // back from the run artifact on a resumed run.+ let embeddings: BenchEmbeddingReceipt | undefined;// Phase: ingest - materialize the disposable vault.if (!phaseDone(checkpoint, "ingest")) {@@ -140,23 +256,36 @@ export async function runMemoryBench(opts: BenchRunOptions): Promise<BenchReport}// Phase: index - one warmup search triggers the store self-heal so- // the FTS index exists before any timed retrieval.+ // the FTS index exists before any timed retrieval. A suite that both+ // declares the embeddings capability and pins the semantic lane on+ // builds real vectors instead, through the apply-gated indexer path+ // and the shared runs-dir vector cache.if (!phaseDone(checkpoint, "index")) {- const config = benchSearchConfig(vault);- await search(config, { query: "warmup", limit: 1, transportReach: BENCH_REACH });+ if (config.semantic.enabled) {+ embeddings = await embedBenchVaultIndex({ config, runsDir: opts.runsDir });+ writeFileSync(+ join(run.runDir, BENCH_EMBEDDING_RECEIPT_FILENAME),+ `${JSON.stringify(embeddings, null, 2)}\n`,+ "utf8",+ );+ } else {+ await search(config, { query: "warmup", limit: 1, transportReach: BENCH_REACH });+ }checkpoint = completeBenchPhase(run.runDir, checkpoint, "index");}+ if (embeddings === undefined && config.semantic.enabled) {+ embeddings = readBenchEmbeddingReceipt(run.runDir);+ }// Phase: retrieve - run every question once, persist raw results.if (!phaseDone(checkpoint, "retrieve")) {- const config = benchSearchConfig(vault);mkdirSync(benchResultsDir(run.runDir), { recursive: true });// Deliberately sequential: per-question latency_ms must not include// contention from sibling searches running on the same store.// oxlint-disable-next-line no-await-in-loopfor (const question of opts.fixture.questions) {// oxlint-disable-next-line no-await-in-loop- const retrieved = await retrieveQuestion(vault, config, question);+ const retrieved = await retrieveQuestion(vault, config, question, opts.recallFloor);writeFileSync(join(benchResultsDir(run.runDir), `${question.id}.json`),`${JSON.stringify(retrieved, null, 2)}\n`,@@ -167,16 +296,57 @@ export async function runMemoryBench(opts: BenchRunOptions): Promise<BenchReport}// Phase: evaluate - pure over the persisted results; no vault access.+ // Each persisted record is read once and shared by the evaluator and+ // the suite metric families.+ const retrievedById = new Map(+ opts.fixture.questions.map((question) => [question.id, readRetrieved(run.runDir, question.id)]),+ );const results = opts.fixture.questions- .map((question) => evaluateQuestion(question, readRetrieved(run.runDir, question.id)))+ .map((question) => evaluateQuestion(question, retrievedById.get(question.id)!)).toSorted((a, b) => (a.id < b.id ? -1 : a.id > b.id ? 1 : 0));if (!phaseDone(checkpoint, "evaluate")) {checkpoint = completeBenchPhase(run.runDir, checkpoint, "evaluate");}- // Optional judge (advisory, fail-open), then report.- const judge = runJudge(opts.judgeCmd, results);- const report = buildReport(run, opts.fixture, results, judge);+ // The LongMemEval suite's named metric family: strict recall_all@5+ // rolled off the same persisted results the evaluator read. The+ // exclusion count comes only from a real conversion receipt - without+ // one it reports null, never a manufactured 0.+ let longmemeval: BenchLongMemEvalFamily | undefined;+ if (opts.suite === LONGMEMEVAL_SUITE_NAME) {+ const scored = scoreLongMemEvalRecall(opts.fixture.questions, [...retrievedById.values()]);+ longmemeval = Object.freeze({+ recall_all_at_5: scored.scored > 0 ? round3(scored.passed / scored.scored) : 0,+ abstention_excluded: opts.suiteReceipt?.abstention_excluded ?? null,+ });+ }++ // Optional judge (advisory, fail-open), then report. Questions whose+ // suite provides official-prompt judge input carry it on the stdin+ // payload; suites without it keep the payload unchanged.+ // Judged questions carry the retrieved evidence (path plus a bounded+ // excerpt, in rank order) beside the reference answer, so a judge can+ // evaluate against what the system actually showed.+ const bodiesByPath = new Map(opts.fixture.notes.map((n) => [n.path, n.body]));+ const excerpt = (body: string): string =>+ body.length > JUDGE_EVIDENCE_EXCERPT_CHARS+ ? `${body.slice(0, JUDGE_EVIDENCE_EXCERPT_CHARS)}...`+ : body;+ const judgeInputs = new Map(+ opts.fixture.questions.flatMap((question) => {+ if (question.judge_input === undefined) return [];+ const retrieved = retrievedById.get(question.id);+ const evidence = (retrieved?.paths ?? []).flatMap((path) => {+ const body = bodiesByPath.get(path);+ return body === undefined ? [] : [{ path, text: excerpt(body) }];+ });+ const input =+ evidence.length > 0 ? { ...question.judge_input, evidence } : question.judge_input;+ return [[question.id, input] as const];+ }),+ );+ const judge = runJudge(opts.judgeCmd, results, judgeInputs);+ const report = buildReport(run, opts.fixture, results, judge, embeddings, longmemeval);writeFileSync(join(run.runDir, "report.json"), `${JSON.stringify(report, null, 2)}\n`, "utf8");if (!phaseDone(checkpoint, "report")) {completeBenchPhase(run.runDir, checkpoint, "report");@@ -188,6 +358,7 @@ async function retrieveQuestion(vault: string,config: ReturnType<typeof resolveSearchConfig>,question: BenchQuestion,+ recallFloor?: number,): Promise<RetrievedQuestion> {const startedAt = Date.now();if (RETRIEVAL_CATEGORIES.has(question.category)) {@@ -216,12 +387,42 @@ async function retrieveQuestion(};}if (question.category === "proactive_recall") {+ // The structural pre-tier (pr-250 review, M9): the transports run+ // `evaluateSurfacingGate` ahead of the decision core, so a duplicate,+ // slash-command, shell-command or empty prompt never reaches+ // retrieval. The bench reproduces that composition exactly whenever+ // the fixture records the prompt this question follows: a structural+ // refusal is persisted as an honest abstention - the gate's own+ // reason, nothing measured, zero injected cost - and the decision+ // core never runs for it.+ const previousPrompt = question.previous_prompt;+ if (previousPrompt !== undefined && previousPrompt.length > 0) {+ const gate = evaluateSurfacingGate({ prompt: question.prompt ?? "", previousPrompt });+ if (!gate.retrieve) {+ return {+ id: question.id,+ latency_ms: Date.now() - startedAt,+ recall_decision: Object.freeze({+ kind: "abstain",+ reason: "structural",+ structuralReason: gate.reason,+ topScore: 0,+ matchQuality: null,+ }),+ context_chars: 0,+ injected_tokens: injectedTokens(""),+ };+ }+ }// The shipped decision core, driven directly over the fixture vault.// The retriever is a PARAMETER of that function, which is the only- // reason this is measurable offline at all.+ // reason this is measurable offline at all. The admission floor is a+ // parameter too (t_107a3249): the replay suite sweeps it to measure+ // gate calibration; absent keeps the shipped default.const decision = await decideRecallInject(question.prompt ?? "",benchRecallRetriever(config, question.top_k ?? RECALL_INJECT_MAX_NOTES),+ recallFloor === undefined ? {} : { confidenceFloor: recallFloor },);// An abstain injects nothing, and zero is the honest cost of nothing -// not an absent measurement.@@ -439,7 +640,11 @@ function evaluateProactiveRecall(/** One decision as a diffable one-liner. Classifications only, no prose. */function describeDecision(decision: RecallInjectDecision): string {- if (decision.kind === "abstain") return `abstain(${decision.reason})`;+ if (decision.kind === "abstain") {+ return decision.structuralReason !== undefined+ ? `abstain(${decision.reason}:${decision.structuralReason})`+ : `abstain(${decision.reason})`;+ }if (decision.kind === "error") return `error(${decision.fault})`;return `inject(${decision.noteCount} notes)`;}@@ -512,6 +717,8 @@ function buildReport(fixture: BenchFixture,results: ReadonlyArray<BenchQuestionResult>,judge: ReturnType<typeof runJudge>,+ embeddings?: BenchEmbeddingReceipt,+ longmemeval?: BenchLongMemEvalFamily,): BenchReport {const byCategory: Record<string, { passed: number; total: number }> = {};let passed = 0;@@ -569,6 +776,8 @@ function buildReport(false_fire_rate: proactive.false_fire_rate,source_isolation_violations: isolationTotal,}),+ ...(embeddings !== undefined ? { embeddings: Object.freeze({ ...embeddings }) } : {}),+ ...(longmemeval !== undefined ? { longmemeval } : {}),judge: Object.freeze({status: judge.status,...(judge.detail !== undefined ? { detail: judge.detail } : {}),diff --git a/src/core/bench/replay-fixture.ts b/src/core/bench/replay-fixture.tsnew file mode 100644index 00000000..d88db900--- /dev/null+++ b/src/core/bench/replay-fixture.ts@@ -0,0 +1,290 @@+/**+ * Surfacing-replay fixture loader (t_107a3249, lane C).+ *+ * The replay bench replays a RECORDED prompt sequence through the+ * decision core and judges each surfacing decision. Recorded+ * `gate_telemetry` decisions are never re-executed - that record+ * deliberately stores only a prompt hash, so replay always re-decides+ * from source prompts. This module owns the two ways source prompts+ * enter the suite, both PURE and deterministic:+ *+ * 1. a committed session-shaped JSON fixture (the locomo pattern:+ * deterministic, network-free, reviewable in the diff), and+ * 2. a vault's own `session_turn` records converted into the same+ * shape, giving regression proof against real sessions without+ * committing raw prompts into the repository.+ *+ * Only (1) is wired to the suite's CLI entry this wave:+ * `--suite surfacing-replay` accepts a committed fixture file, and (2)+ * ships as the pure conversion (`sessionTurnsToReplayFixture`) with no+ * flag behind it yet - a recorded-session adapter, not a live vault+ * reader.+ *+ * The expected-outcome vocabulary is CLOSED (`inject` | `abstain`): the+ * scorer denominates false fires and silent misses in exactly that+ * boolean, and an expectation the vocabulary cannot name is a named+ * rejection - never a defaulted expectation, which would silently+ * manufacture the number being measured.+ */++import { readFileSync } from "node:fs";++import type { ContinuityRecord } from "../brain/continuity/types.ts";++/** What memory SHOULD do for one recorded prompt. Closed on purpose. */+export const REPLAY_EXPECTATION = Object.freeze({+ /** Memory should speak up for this prompt. */+ inject: "inject",+ /** Memory should stay quiet - weak match, nothing to add, or a non-prompt. */+ abstain: "abstain",+} as const);++/** Closed union over {@link REPLAY_EXPECTATION}. */+export type ReplayExpectation = (typeof REPLAY_EXPECTATION)[keyof typeof REPLAY_EXPECTATION];++/** Membership list; every surface renders its vocabulary from this array. */+export const REPLAY_EXPECTATIONS: ReadonlyArray<ReplayExpectation> = Object.freeze([+ REPLAY_EXPECTATION.inject,+ REPLAY_EXPECTATION.abstain,+]);++/** Narrow a value read back off disk or across a tool boundary. */+export function isReplayExpectation(value: unknown): value is ReplayExpectation {+ return (+ typeof value === "string" && (REPLAY_EXPECTATIONS as ReadonlyArray<string>).includes(value)+ );+}++/** One recorded prompt, in session order, with its expected outcome. */+export interface ReplayPrompt {+ readonly id: string;+ /** The recorded prompt text, verbatim. */+ readonly text: string;+ /**+ * The immediately preceding prompt's text in the sequence, or null for+ * the first turn - the input duplicate detection reads.+ */+ readonly previousText: string | null;+ /** The expectation, loaded into the boolean the scorer denominates in. */+ readonly expectInject: boolean;+}++/** An ordered replay session: corpus notes plus the prompt sequence. */+export interface ReplayFixture {+ readonly name: string;+ readonly description?: string;+ /**+ * The memory content the prompts are judged against. Empty is valid: a+ * session of purely structural prompts has nothing to say about them.+ */+ readonly notes: ReadonlyArray<{ readonly path: string; readonly body: string }>;+ readonly prompts: ReadonlyArray<ReplayPrompt>;+}++/** Typed rejection for a malformed replay fixture or record conversion. */+export class ReplayFixtureError extends Error {+ constructor(message: string) {+ super(message);+ this.name = "ReplayFixtureError";+ }+}++function asString(value: unknown, field: string): string {+ if (typeof value !== "string" || value.trim() === "") {+ throw new ReplayFixtureError(`replay fixture: ${field} must be a non-empty string`);+ }+ return value;+}++function parseTurn(raw: unknown, where: string, previousText: string | null): ReplayPrompt {+ if (raw === null || typeof raw !== "object") {+ throw new ReplayFixtureError(`replay fixture: ${where} must be an object`);+ }+ const t = raw as Record<string, unknown>;+ const id = asString(t["id"], `${where}.id`);+ if (typeof t["text"] !== "string") {+ throw new ReplayFixtureError(`replay fixture: turn '${id}'.text must be a string`);+ }+ if (!isReplayExpectation(t["expect"])) {+ throw new ReplayFixtureError(+ `replay fixture: turn '${id}'.expect must be one of ${REPLAY_EXPECTATIONS.join(", ")}` ++ (t["expect"] === undefined ? "" : `; got '${String(t["expect"])}'`),+ );+ }+ return {+ id,+ text: t["text"],+ previousText,+ expectInject: t["expect"] === REPLAY_EXPECTATION.inject,+ };+}++/**+ * Parse and validate a raw session-shaped replay fixture.+ *+ * The suite-qualified name is applied HERE, at the one entry point raw+ * input flows through, so every downstream consumer (the bench converter,+ * the loader) reports the same `surfacing-replay-` prefixed name without+ * each having to remember the prefix - and without a conversion path ever+ * emitting a bare name that the run store would file under the wrong+ * suite.+ */+export function parseReplayFixture(raw: unknown): ReplayFixture {+ if (raw === null || typeof raw !== "object") {+ throw new ReplayFixtureError("replay fixture must be an object");+ }+ const r = raw as Record<string, unknown>;+ const name = asString(r["name"], "name");+ if (!Array.isArray(r["turns"]) || r["turns"].length === 0) {+ throw new ReplayFixtureError(`replay fixture '${name}' needs a non-empty \`turns\` array`);+ }+ if (r["notes"] !== undefined && !Array.isArray(r["notes"])) {+ throw new ReplayFixtureError(`replay fixture '${name}'.notes must be an array when present`);+ }+ const notes = (r["notes"] ?? []).map((n, i) => {+ if (n === null || typeof n !== "object") {+ throw new ReplayFixtureError(`replay fixture: notes[${i}] must be an object`);+ }+ const nd = n as Record<string, unknown>;+ return {+ path: asString(nd["path"], `notes[${i}].path`),+ body: asString(nd["body"], `notes[${i}].body`),+ };+ });+ const prompts: ReplayPrompt[] = [];+ const seen = new Set<string>();+ for (const [i, rawTurn] of r["turns"].entries()) {+ const previous = prompts.length > 0 ? (prompts[prompts.length - 1]?.text ?? null) : null;+ const turn = parseTurn(rawTurn, `turns[${i}]`, previous);+ if (seen.has(turn.id)) {+ throw new ReplayFixtureError(`replay fixture '${name}': duplicate turn id '${turn.id}'`);+ }+ seen.add(turn.id);+ prompts.push(turn);+ }+ return withSuiteName({+ name,+ ...(typeof r["description"] === "string" ? { description: r["description"] } : {}),+ notes,+ prompts,+ });+}++/** Load a committed replay fixture file, named `surfacing-replay-<name>`. */+export function loadReplayFixture(path: string): ReplayFixture {+ let raw: unknown;+ try {+ raw = JSON.parse(readFileSync(path, "utf8"));+ } catch (e) {+ throw new ReplayFixtureError(+ `replay fixture not readable JSON at ${path}: ${e instanceof Error ? e.message : String(e)}`,+ );+ }+ // `parseReplayFixture` applies the suite-qualified name; loading adds+ // nothing but the file read.+ return parseReplayFixture(raw);+}++/** The suite-qualified fixture name every replay entry point reports. */+function withSuiteName(fixture: ReplayFixture): ReplayFixture {+ return { ...fixture, name: `surfacing-replay-${fixture.name}` };+}++/** Input to the vault-record conversion. */+export interface SessionTurnsToReplayInput {+ readonly name: string;+ /** `session_turn` records, in any order; the conversion orders them. */+ readonly records: ReadonlyArray<ContinuityRecord>;+ /**+ * Expected outcome per turn, keyed by record id. Every replayed turn+ * (every `role === "user"` record) needs one - a turn without a+ * declared expectation is a rejection, because a defaulted expectation+ * would silently manufacture the score. Assistant turns are not+ * replayed and declare none.+ */+ readonly expectations: Readonly<Record<string, unknown>>;+}++/**+ * The role whose turns are prompts. Only `role === "user"` turns are+ * replayed: an assistant turn is not something memory is asked to speak+ * on, and replaying it as a prompt would score a decision nobody makes.+ */+const USER_TURN_ROLE = "user";++/**+ * The conversation instant a turn is ordered by: the turn's+ * `payload.timestamp` when the record carries one, else the record+ * `createdAt` - the same precedence the shipped session-recall reader+ * orders by (`compareRecords`, `src/core/brain/session-recall.ts`).+ * `createdAt` is import time; one import writes a whole session at once,+ * so ordering by it alone can name the wrong turn as "the prompt before".+ */+function turnInstant(record: ContinuityRecord): string {+ return String(record.payload["timestamp"] ?? record.createdAt);+}++/**+ * Convert a vault's `session_turn` records into the committed fixture's+ * shape. Two normalizations make the replay follow the conversation+ * rather than the import:+ *+ * - ORDER is the conversation's: {@link turnInstant} - the turn's+ * `payload.timestamp`, falling back to `createdAt` - then record id,+ * then the caller's array order, all three stable and recomputable.+ * - ROLE: only {@link USER_TURN_ROLE} turns become prompts, so the+ * previous-prompt chain (what duplicate detection reads) is a chain+ * of user prompts.+ *+ * Expectations are required exactly for the turns that are replayed; an+ * assistant turn declares none and silently drops out of the sequence.+ */+export function sessionTurnsToReplayFixture(input: SessionTurnsToReplayInput): ReplayFixture {+ const ordered = input.records+ .map((record, index) => ({ record, index }))+ .toSorted(+ (a, b) =>+ turnInstant(a.record).localeCompare(turnInstant(b.record)) ||+ a.record.id.localeCompare(b.record.id) ||+ a.index - b.index,+ );+ const prompts: ReplayPrompt[] = [];+ for (const { record } of ordered) {+ if (record.kind !== "session_turn") {+ throw new ReplayFixtureError(+ `replay fixture '${input.name}': turn '${record.id}' has kind '${record.kind}', expected session_turn`,+ );+ }+ if (record.payload["role"] !== USER_TURN_ROLE) continue;+ const rawExpectation = input.expectations[record.id];+ if (!isReplayExpectation(rawExpectation)) {+ throw new ReplayFixtureError(+ `replay fixture '${input.name}': turn '${record.id}' needs an expectation from ` ++ `${REPLAY_EXPECTATIONS.join(", ")}` ++ (rawExpectation === undefined ? "" : `; got '${String(rawExpectation)}'`),+ );+ }+ const text = record.payload["text"];+ if (typeof text !== "string") {+ throw new ReplayFixtureError(+ `replay fixture '${input.name}': turn '${record.id}' has no text payload to replay`,+ );+ }+ prompts.push({+ id: record.id,+ text,+ previousText: prompts.length > 0 ? (prompts[prompts.length - 1]?.text ?? null) : null,+ expectInject: rawExpectation === REPLAY_EXPECTATION.inject,+ });+ }+ if (prompts.length === 0) {+ throw new ReplayFixtureError(+ `replay fixture '${input.name}': no user session_turn records to replay`,+ );+ }+ return withSuiteName({+ name: input.name,+ notes: [],+ prompts,+ });+}diff --git a/src/core/bench/replay.ts b/src/core/bench/replay.tsnew file mode 100644index 00000000..656d003b--- /dev/null+++ b/src/core/bench/replay.ts@@ -0,0 +1,78 @@+/**+ * Surfacing-replay bench suite (t_107a3249, lane C).+ *+ * Replays a recorded prompt sequence (a committed session fixture or a+ * vault's own `session_turn` records, both via `replay-fixture.ts`)+ * through the SHIPPED decision core over the disposable fixture vault,+ * and scores every decision with the same+ * {@link scoreProactiveRecall} denominations the proactive-recall suite+ * uses: a silent miss is `know_to_ask`, a spoke-when-nothing-to-say is+ * `false_fire`, and the two rates share one denominator so an+ * always-inject gate can never hide.+ *+ * Scope, stated plainly: this is a FLOOR-CALIBRATION suite. It drives+ * the shipped decision core directly, so the bound it measures is the+ * graded admission key (`surfacing-key.ts`) - sweeping the shipped+ * calibration against a permissive one, via the run's `recallFloor`, is+ * what shows whether that bound discriminates. The gate's STRUCTURAL+ * short-circuits (`duplicate`, `slash_command`, `shell_command`,+ * `empty`) are exercised for recorded prompts: conversion carries each+ * prompt's recorded previous prompt as `previous_prompt`, and the+ * proactive-recall arm runs `evaluateSurfacingGate` ahead of the+ * decision core, exactly as the transports do. See `failure-modes.ts`+ * for what the scorer denominates.+ *+ * Rides the suite registry and the existing phase pipeline unchanged:+ * conversion is a pure ReplayFixture -> BenchFixture whose questions are+ * `proactive_recall`, so checkpoint, resume, per-turn `injected_tokens`+ * and the abstain-costs-zero invariant all come from the one harness.+ */++import { parseBenchFixture } from "./fixture.ts";+import type { BenchFixture, BenchQuestion } from "./types.ts";+import { loadReplayFixture, type ReplayFixture } from "./replay-fixture.ts";++/**+ * Convert a replay fixture into the canonical bench fixture the unchanged+ * `runMemoryBench` consumes: every prompt becomes one `proactive_recall`+ * question carrying its expectation, and the session's notes become the+ * disposable vault the decisions retrieve against. No new category: the+ * pipeline's existing proactive-recall arm drives and scores the run.+ *+ * Empty notes survive conversion, matching the loader's own stance: a+ * recorded session with no ingested notes has nothing to materialize, so+ * its fixture carries the questions alone and the run judges them+ * against an empty vault. Each question carries the recorded previous+ * prompt as `previous_prompt`, so the run's structural gate sees the+ * same context the live hook saw.+ */+export function replayToBenchFixture(replay: ReplayFixture): BenchFixture {+ const questions: BenchQuestion[] = replay.prompts.map((prompt) => ({+ id: prompt.id,+ category: "proactive_recall",+ prompt: prompt.text,+ expect_inject: prompt.expectInject,+ ...(prompt.previousText !== null ? { previous_prompt: prompt.previousText } : {}),+ }));+ // Validate through the canonical parser so a converted fixture is+ // guaranteed to be exactly what runMemoryBench accepts. The empty-notes+ // relaxation is named at the parser, not smuggled past it: a session+ // with no ingested notes is questions-only by construction, and every+ // replay entry point (`parseReplayFixture`, the vault-record+ // conversion) may legitimately produce one.+ return parseBenchFixture(+ {+ name: replay.name,+ ...(replay.description !== undefined ? { description: replay.description } : {}),+ notes: replay.notes.map((note) => ({ path: note.path, body: note.body })),+ continuity: [],+ questions,+ },+ { allowEmptyNotes: true },+ );+}++/** The registry loader: a committed replay fixture file to a BenchFixture. */+export function loadReplayBenchFixture(path: string): BenchFixture {+ return replayToBenchFixture(loadReplayFixture(path));+}diff --git a/src/core/bench/run-store.ts b/src/core/bench/run-store.tsindex ee3b3a3e..d5783c4b 100644--- a/src/core/bench/run-store.ts+++ b/src/core/bench/run-store.ts@@ -5,15 +5,26 @@* `<runsDir>/<run-id>/checkpoint.json` plus per-question results and* the final report. Resume validates the fixture hash before skipping* phases - a changed fixture invalidates the checkpoint rather than- * silently mixing two runs. A path guard refuses run ids that resolve- * outside the runs directory.+ * silently mixing two runs. The run identity covers the pinned search+ * knobs too ({@link benchRunIdentityHash}), so a resumed run whose pin+ * changed fails the guard loudly; checkpoints written before knob+ * pinning existed are refused for the same reason. A path guard refuses+ * run ids that resolve outside the runs directory.*/import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";import { join, resolve, sep } from "node:path";+import { canonicalJson, sha256Hex } from "../integrity/digest.ts";import { fixtureHash } from "./fixture.ts";-import { BENCH_PHASES, type BenchCheckpoint, type BenchFixture, type BenchPhase } from "./types.ts";+import {+ BENCH_PHASES,+ DEFAULT_BENCH_KNOB_PIN,+ type BenchCheckpoint,+ type BenchFixture,+ type BenchPhase,+ type BenchPinnedKnobs,+} from "./types.ts";export interface BenchRunHandle {readonly runId: string;@@ -23,6 +34,32 @@ export interface BenchRunHandle {const CHECKPOINT_FILE = "checkpoint.json";+/** Hex characters kept from the run-identity digest (fixture + knob pin). */+const RUN_IDENTITY_HEX_CHARS = 16;++/**+ * The run-identity hash: the fixture hash AND the pinned knob record+ * AND the recall admission floor (null when unset), canonically hashed+ * together. Two runs that differ only in their pin or floor therefore+ * get different run ids, and a resumed run whose pin or floor changed+ * fails the identity guard instead of silently comparing two pipelines+ * - or worse, deciding the remaining questions under a new floor while+ * the persisted ones keep the old.+ */+export function benchRunIdentityHash(+ fixture: BenchFixture,+ pinnedKnobs: BenchPinnedKnobs,+ recallFloor?: number,+): string {+ return sha256Hex(+ canonicalJson({+ fixture: fixtureHash(fixture),+ knobs: pinnedKnobs,+ recall_floor: recallFloor ?? null,+ }),+ ).slice(0, RUN_IDENTITY_HEX_CHARS);+}+/** Disposable fixture vault location inside one run. */export function benchVaultDir(runDir: string): string {return join(runDir, "vault");@@ -36,21 +73,25 @@ export function benchResultsDir(runDir: string): string {export function createBenchRun(runsDir: string,fixture: BenchFixture,- opts: { now?: Date } = {},+ opts: { now?: Date; pinnedKnobs?: BenchPinnedKnobs; recallFloor?: number } = {},): BenchRunHandle {const now = opts.now ?? new Date();+ const knobs = opts.pinnedKnobs ?? DEFAULT_BENCH_KNOB_PIN;const hash = fixtureHash(fixture);+ const identity = benchRunIdentityHash(fixture, knobs, opts.recallFloor);const stamp = now.toISOString().replace(/[^0-9]/g, "").slice(0, 14);- const runId = `run-${stamp}-${hash.slice(0, 6)}`;+ const runId = `run-${stamp}-${identity.slice(0, 6)}`;const runDir = guardedRunDir(runsDir, runId);mkdirSync(runDir, { recursive: true });const checkpoint: BenchCheckpoint = Object.freeze({run_id: runId,fixture_name: fixture.name,fixture_hash: hash,+ pinned_knobs: knobs,+ knobs_hash: identity,created_at: now.toISOString(),completed_phases: Object.freeze([]),});@@ -61,7 +102,11 @@ export function createBenchRun(export function loadBenchRun(runsDir: string,runId: string,- opts: { expectFixture?: BenchFixture } = {},+ opts: {+ expectFixture?: BenchFixture;+ pinnedKnobs?: BenchPinnedKnobs;+ recallFloor?: number;+ } = {},): BenchRunHandle {const runDir = guardedRunDir(runsDir, runId);const path = join(runDir, CHECKPOINT_FILE);@@ -76,6 +121,18 @@ export function loadBenchRun(`bench run ${runId}: fixture hash mismatch (checkpoint ${checkpoint.fixture_hash}, current ${expected}) - the fixture changed since this run started`,);}+ const knobs = opts.pinnedKnobs ?? DEFAULT_BENCH_KNOB_PIN;+ if (checkpoint.knobs_hash === undefined) {+ throw new Error(+ `bench run ${runId}: checkpoint predates knob pinning - the run identity cannot be verified, restart the run`,+ );+ }+ const expectedIdentity = benchRunIdentityHash(opts.expectFixture, knobs, opts.recallFloor);+ if (expectedIdentity !== checkpoint.knobs_hash) {+ throw new Error(+ `bench run ${runId}: run identity mismatch (checkpoint ${checkpoint.knobs_hash}, current ${expectedIdentity}) - the pinned knobs or the recall floor changed since this run started`,+ );+ }}return Object.freeze({ runId, runDir, checkpoint });}@@ -113,6 +170,8 @@ function parseCheckpoint(raw: unknown): BenchCheckpoint {const hash = record["fixture_hash"];const createdAt = record["created_at"];const phases = record["completed_phases"];+ const knobsHash = record["knobs_hash"];+ const pinnedKnobs = record["pinned_knobs"];if (typeof runId !== "string" ||typeof fixtureName !== "string" ||@@ -122,6 +181,15 @@ function parseCheckpoint(raw: unknown): BenchCheckpoint {) {throw new Error("bench checkpoint: missing required fields");}+ if (knobsHash !== undefined && typeof knobsHash !== "string") {+ throw new Error("bench checkpoint: knobs_hash must be a string");+ }+ if (+ pinnedKnobs !== undefined &&+ (pinnedKnobs === null || typeof pinnedKnobs !== "object" || Array.isArray(pinnedKnobs))+ ) {+ throw new Error("bench checkpoint: pinned_knobs must be an object");+ }const completed = phases.filter((phase): phase is BenchPhase =>typeof phase === "string" && (BENCH_PHASES as ReadonlyArray<string>).includes(phase),@@ -130,6 +198,13 @@ function parseCheckpoint(raw: unknown): BenchCheckpoint {run_id: runId,fixture_name: fixtureName,fixture_hash: hash,+ ...(typeof knobsHash === "string" ? { knobs_hash: knobsHash } : {}),+ ...(pinnedKnobs !== undefined &&+ pinnedKnobs !== null &&+ typeof pinnedKnobs === "object" &&+ !Array.isArray(pinnedKnobs)+ ? { pinned_knobs: Object.freeze({ ...(pinnedKnobs as BenchPinnedKnobs) }) }+ : {}),created_at: createdAt,completed_phases: Object.freeze(completed),});@@ -140,6 +215,12 @@ function guardedRunDir(runsDir: string, runId: string): string {if (!/^[A-Za-z0-9._-]+$/.test(runId)) {throw new Error(`bench run id contains unsafe characters: ${runId}`);}+ // "." and ".." pass the charset and resolve inside the root: a run id+ // of dots would write the checkpoint, the report and the vault beside+ // the shared vector cache instead of into its own directory.+ if (runId.split(".").every((part) => part === "")) {+ throw new Error(`bench run id must not be all dots: ${runId}`);+ }const root = resolve(runsDir);const dir = resolve(root, runId);if (dir !== root && !dir.startsWith(`${root}${sep}`)) {diff --git a/src/core/bench/types.ts b/src/core/bench/types.tsindex ef83b34c..66ebd88e 100644--- a/src/core/bench/types.ts+++ b/src/core/bench/types.ts@@ -19,6 +19,13 @@* report be read under the wrong rule.*/import type { RecallFailure } from "./failure-modes.ts";+import type { EmbeddingGateVerdict } from "../search/embedding-spend.ts";+import type {+ ResolvedEmbeddingConfig,+ ResolvedRerankConfig,+ ResolvedSearchConfig,+} from "../search/types.ts";+import type { VaultScopeRules } from "../vault-scope/defaults.ts";export const BENCH_REPORT_SCHEMA = "o2b.bench.v2";@@ -60,6 +67,28 @@ export interface BenchFixtureContinuity {readonly payload: Readonly<Record<string, unknown>>;}+/**+ * What a suite provides for the official-prompt judge: the question as+ * the dataset asked it, the reference answer when it states one, and the+ * gold evidence ids. Rides the judge stdin payload verbatim; it is+ * NEVER scoring input - `evaluateQuestion` ignores it, and the converter+ * never sets `expected_text` (that field is ignored for retrieval+ * categories, so a gold answer pinned there would silently score+ * nothing).+ */+export interface BenchJudgeInput {+ readonly question: string;+ readonly answer?: string;+ readonly gold: ReadonlyArray<string>;+ /**+ * The retrieved evidence the run actually injected, path plus a+ * bounded text excerpt in rank order, so a judge can evaluate an+ * answer against what the system showed rather than the whole vault.+ * Present when the run records retrieved texts for a judged question.+ */+ readonly evidence?: ReadonlyArray<{ readonly path: string; readonly text: string }>;+}+export interface BenchQuestion {readonly id: string;readonly category: BenchCategory;@@ -76,12 +105,25 @@ export interface BenchQuestion {readonly session_id?: string;readonly expected_turns?: number;readonly expected_text?: string;+ /**+ * Official-prompt judge glue (longmemeval), absent for suites that+ * provide none - their judge payload stays unchanged.+ */+ readonly judge_input?: BenchJudgeInput;/** budget / source_isolation: pack item ids that must be delivered. */readonly expected_ids?: ReadonlyArray<string>;readonly max_tokens?: number;readonly max_total_chars?: number;/** proactive_recall: the user prompt the decision core sees. */readonly prompt?: string;+ /**+ * proactive_recall: the previous prompt in the replayed sequence, when+ * the suite records one. The structural gate (`evaluateSurfacingGate`)+ * consumes it ahead of the decision core, exactly as the transports+ * run it; absent means the gate is not reproduced for this question+ * and it is judged on retrieval alone.+ */+ readonly previous_prompt?: string;/*** proactive_recall: whether memory SHOULD speak up for this prompt.* `false` is the anti-gaming half of the fixture - a prompt the vault@@ -108,6 +150,137 @@ export interface BenchFixture {readonly questions: ReadonlyArray<BenchQuestion>;}+/**+ * What a registered suite may do inside one bench run.+ *+ * Declared at suite registration and carried on {@link BenchRunOptions}+ * by the CLI verb from the suite registry, so "what a suite may do" is a+ * property of the suite in code - never of a flag a caller forgot.+ * A capability declaration alone is inert: the feature also has to be+ * enabled through the run's knob pin.+ */+export interface BenchSuiteCapabilities {+ /**+ * Whether the suite may build the disposable vault index with+ * embeddings (through the apply-gated indexer options) and run the+ * semantic lane.+ */+ readonly embeddings: boolean;+}++/**+ * What a suite loader returns: the converted fixture plus a typed+ * receipt of what conversion decided (for LongMemEval, how many+ * abstention questions it dropped).+ */+export interface BenchSuiteLoad {+ readonly fixture: BenchFixture;+ readonly receipt?: BenchSuiteReceipt;+}++/** Suite-level conversion receipt, surfaced through the report family. */+export interface BenchSuiteReceipt {+ /** LongMemEval-style abstention questions dropped at conversion time. */+ readonly abstention_excluded?: number;+}++/**+ * One registered suite: how a dataset file becomes a {@link BenchFixture}+ * and what the suite may do inside a run. Suites register through the+ * registry map in the bench verb - an appendable registration point, not+ * a hard-coded branch chain.+ */+export interface BenchSuiteRegistration {+ readonly loader: (fixturePath: string) => BenchSuiteLoad;+ readonly capabilities: BenchSuiteCapabilities;+}++/**+ * Search-configuration knobs pinned for one bench run. Shaped exactly+ * like `resolveSearchConfig`'s overrides - applied last and win - so a+ * pin can express every search, rerank and embedding knob the resolver+ * knows. The pin is part of the RUN IDENTITY: it is folded into the+ * checkpoint hash, so a resumed run that would mix two configurations+ * fails the guard loudly instead of silently comparing them.+ */+export type BenchPinnedKnobs = Partial<+ Omit<ResolvedSearchConfig, "scopeRules" | "semantic" | "rerank">+> & {+ readonly scopeRules?: VaultScopeRules;+ readonly semantic?: Partial<ResolvedEmbeddingConfig>;+ readonly rerank?: Partial<ResolvedRerankConfig>;+};++/**+ * The default knob pin: the hardcoded semantic-off override the harness+ * has always applied, made an explicit named value so the default run+ * identity is deterministic and locomo report numbers stay identical.+ */+export const DEFAULT_BENCH_KNOB_PIN: BenchPinnedKnobs = Object.freeze({+ semantic: Object.freeze({ enabled: false }),+});++/**+ * The embedding spend receipt a capability-declaring suite surfaces.+ *+ * It records the ONE spend plan the suite's index phase computed through+ * the apply-gated path (`planEmbeddingSpend`, the indexer's own gate) and+ * how the shared vector cache split it: `cache_hits` vectors came off the+ * runs-dir cache with zero provider contact, `cache_misses` were embedded+ * through the indexer's embedding phase - which re-prices and re-gates+ * that census itself, so the verdict acted on is never a caller's. A+ * blocked gate is a named refusal, never a silent bypass.+ */+export interface BenchEmbeddingReceipt {+ readonly provider: string;+ /** The model the vectors are stored under. */+ readonly model: string | null;+ /**+ * Canonical embedding identity: the `<provider>:<model>:<dimension>`+ * triple plus the query/passage prefixes, rendered by+ * `benchEmbeddingSignature`.+ */+ readonly signature: string;+ /** Chunks the spend plan found pending when the phase opened. */+ readonly planned: number;+ /** Pending chunks served from the shared cache (no provider contact). */+ readonly cache_hits: number;+ /** Pending chunks embedded through the apply-gated embedding phase. */+ readonly cache_misses: number;+ /** Tokens the full pending census estimated. */+ readonly tokens: number;+ /** Estimated spend of the full pending census; null when unpriced. */+ readonly estimated_usd: number | null;+ /** Who stated the price the estimate used. */+ readonly price_source: string;+ /** The plan's own gate verdict, verbatim. */+ readonly gate: EmbeddingGateVerdict;+ /**+ * True only when the embedding phase's receipt records a forced pass+ * over a gate that would have refused. The bench itself never forces;+ * the field exists so a receipt can never hide a bypass.+ */+ readonly forced?: boolean;+}++/**+ * The LongMemEval report family (the MemScore rule: metric families stay+ * separate and named). The strict recall_all@5 aggregate is never folded+ * into `quality.pass_rate`, and the abstention exclusion count is+ * surfaced beside it rather than hidden - a reader can see what the+ * number does and does not cover.+ */+export interface BenchLongMemEvalFamily {+ /** Share of scored questions with every gold note inside the cutoff. */+ readonly recall_all_at_5: number;+ /**+ * Abstention questions the conversion excluded from scoring, taken+ * from the run's conversion receipt. Null when the run carries no+ * receipt - the count is then unknown, never a manufactured 0.+ */+ readonly abstention_excluded: number | null;+}+export interface BenchQuestionResult {readonly id: string;readonly category: BenchCategory;@@ -123,6 +296,12 @@ export interface BenchQuestionResult {readonly recall_failure?: RecallFailure;/** source_isolation: forbidden ids the pack actually delivered. */readonly isolation_violations?: number;+ /**+ * The external judge's verdict for this question, present only when a+ * judge ran and answered for it; deterministic evaluation stays+ * canonical either way.+ */+ readonly judge_pass?: boolean;}export interface BenchReport {@@ -160,6 +339,20 @@ export interface BenchReport {readonly false_fire_rate: number;readonly source_isolation_violations: number;};+ /**+ * The embedding spend receipt, present only when the run's suite+ * declares the embeddings capability AND the knob pin enables the+ * semantic lane - so the default (and locomo) report serializes+ * byte-identically without it. Carries the provider+model signature so+ * numbers are never compared across embedding identities.+ */+ readonly embeddings?: BenchEmbeddingReceipt;+ /**+ * The LongMemEval suite's named metric family, present only on runs+ * through the longmemeval suite - so the default (and locomo) report+ * serializes byte-identically without it.+ */+ readonly longmemeval?: BenchLongMemEvalFamily;readonly judge: { readonly status: "skipped" | "ran" | "error"; readonly detail?: string };readonly questions: ReadonlyArray<BenchQuestionResult>;}@@ -168,6 +361,14 @@ export interface BenchCheckpoint {readonly run_id: string;readonly fixture_name: string;readonly fixture_hash: string;+ /**+ * The knob pin this run was created under, and the run-identity hash+ * covering fixture plus pin. Both absent on checkpoints written before+ * knob pinning existed; resume refuses such a checkpoint loudly rather+ * than mixing configurations.+ */+ readonly pinned_knobs?: BenchPinnedKnobs;+ readonly knobs_hash?: string;readonly created_at: string;readonly completed_phases: ReadonlyArray<BenchPhase>;}diff --git a/src/core/brain/gate-telemetry.ts b/src/core/brain/gate-telemetry.tsindex 0baa7881..ed8d1552 100644--- a/src/core/brain/gate-telemetry.ts+++ b/src/core/brain/gate-telemetry.ts@@ -21,9 +21,11 @@import { createHash } from "node:crypto";+import { isSurfacingTier, type SurfacingTier } from "../search/surfacing-key.ts";import { appendContinuityRecord, listContinuityRecords } from "./continuity/store.ts";import { CONTINUITY_TURN_ID_KEY, type ContinuityRecord } from "./continuity/types.ts";import type { NegativeRecallVerdict } from "./negative-recall.ts";+import type { RecallChannel } from "./recall-telemetry.ts";export interface GateTelemetryInput {readonly host: string;@@ -34,6 +36,26 @@ export interface GateTelemetryInput {/** The caller's turn correlation id, recorded under {@link CONTINUITY_TURN_ID_KEY}. */readonly turnId?: string;readonly createdAt?: string;+ /**+ * The graded surfacing key (t_107a3249), recorded only when the call+ * carried a measured quality - an unmeasured structural verdict is+ * already described by `decision` and `reason`. Numbers and closed+ * values only; `key` is null exactly where the graded admission key is+ * null: where nothing was measurable, or where a structural outcome+ * (`suppressed`, `explicit`) decided the call without grading the+ * carried measurement.+ */+ readonly surfacing?: {+ readonly key: number | null;+ readonly tier: SurfacingTier;+ };+ /**+ * The transport the decision arrived over, recorded only on MEASURED+ * decisions: the channel calibrates the measured admission, and an+ * unmeasured structural verdict is already described by `decision` and+ * `reason`.+ */+ readonly channel?: RecallChannel;/*** The adequacy verdict and the caller's advisory decision-model* probability, recorded only when the call carried `decision_answerable`@@ -59,6 +81,8 @@ export interface GateTelemetrySummary {readonly retrieved: number;readonly skipped: number;readonly by_reason: Record<string, number>;+ /** Counts by graded admission tier (t_107a3249); measured calls only. */+ readonly by_tier: Record<string, number>;}export function hashPrompt(prompt: string): string {@@ -79,6 +103,10 @@ export function emitGateTelemetry(vault: string, input: GateTelemetryInput): Conreason: input.reason,prompt_hash: hashPrompt(input.prompt),prompt_chars: input.prompt.length,+ ...(input.channel !== undefined ? { channel: input.channel } : {}),+ ...(input.surfacing !== undefined+ ? { key: input.surfacing.key, tier: input.surfacing.tier }+ : {}),...(input.decisionAnswerable !== undefined? {adequacy_level: input.decisionAnswerable.level,@@ -162,7 +190,7 @@ export function listGateTelemetry(return Object.freeze(records);}-/** Aggregate decisions by outcome and reason. */+/** Aggregate decisions by outcome, reason and graded tier. */export function summarizeGateTelemetry(vault: string,filter: GateTelemetryFilter = {},@@ -170,17 +198,23 @@ export function summarizeGateTelemetry(const records = listGateTelemetry(vault, filter);let retrieved = 0;const byReason: Record<string, number> = {};+ const byTier: Record<string, number> = {};for (const record of records) {if (record.payload["decision"] === "retrieve") retrieved += 1;const reason = record.payload["reason"];if (typeof reason === "string" && reason !== "") {byReason[reason] = (byReason[reason] ?? 0) + 1;}+ const tier = record.payload["tier"];+ if (isSurfacingTier(tier)) {+ byTier[tier] = (byTier[tier] ?? 0) + 1;+ }}return Object.freeze({total: records.length,retrieved,skipped: records.length - retrieved,by_reason: Object.freeze(byReason),+ by_tier: Object.freeze(byTier),});}diff --git a/src/core/brain/marginal-value-stop.ts b/src/core/brain/marginal-value-stop.tsnew file mode 100644index 00000000..30b95f67--- /dev/null+++ b/src/core/brain/marginal-value-stop.ts@@ -0,0 +1,83 @@+/**+ * The marginal-value stop, as a pure leaf (recall-quality wave, lane A).+ *+ * A page (or a retrieval round) is worth taking only while its value is+ * at least a floor fraction of the best sample's value; the floor rises+ * with observed latency, so a slow route demands denser pages. The+ * formula is the advisor's, extracted verbatim (t_3ffb021c) so the+ * consumers reusing it - the advisor's own allocation and the search-side+ * iterative loop, which feeds per-round candidate yields and elapsed time+ * instead of a pack curve - share one tuning rather than re-deriving+ * their own.+ *+ * This module is a LEAF by construction: it imports nothing, so a+ * consumer in the search pipeline can read the exact advisor formula+ * without dragging the advisor's dependency graph (plan, pack, doctor)+ * behind it - a graph whose load order a pipeline import once flipped+ * into a module-init cycle, which is why the extraction sits here rather+ * than beside its original.+ */++/**+ * Marginal-value stop: a page is worth including only while its density is at+ * least this fraction of the top page's density. The fraction is the base+ * plus a p95-scaled surcharge, so a slow route demands denser pages.+ */+export const STOP_BASE_FRACTION = 0.25;+/** p95 latency (ms) that adds the full {@link STOP_MAX_EXTRA_FRACTION} surcharge. */+export const STOP_P95_SCALE_MS = 4000;+/** Cap on the p95-driven surcharge added to {@link STOP_BASE_FRACTION}. */+export const STOP_MAX_EXTRA_FRACTION = 0.5;++/** The stop verdict over one density curve. */+export interface RetrievalPlanMarginalStop {+ /** Include this many leading pages; beyond it marginal value < cost. */+ readonly stopRank: number;+ /** Cumulative tokens of the leading pages up to the stop. */+ readonly stopTokens: number;+ readonly reason: string;+}++/**+ * Where to stop allocating along a density curve given observed latency.+ * Samples are read in order; the walk keeps pages whose density meets the+ * latency-scaled floor (always at least the first), and the token counts+ * ride along so the caller knows what the kept pages cost.+ *+ * Extracted verbatim from the advisor's private stop so other lanes can+ * reuse the exact formula rather than re-tuning their own: the advisor feeds+ * it the context-pack density curve and the route's p95, and its+ * `buildRetrievalPlan` output stays byte-identical to the pre-extraction+ * fixtures by construction. The search-side iterative loop feeds it+ * per-round candidate yields and elapsed time instead — samples, not pages.+ */+export function marginalValueStop(+ densityCurve: ReadonlyArray<number>,+ tokens: ReadonlyArray<number>,+ p95LatencyMs: number | null,+): RetrievalPlanMarginalStop {+ if (densityCurve.length === 0) {+ return Object.freeze({ stopRank: 0, stopTokens: 0, reason: "no candidates to allocate" });+ }+ const top = densityCurve[0]!;+ const surcharge = Math.min(+ STOP_MAX_EXTRA_FRACTION,+ (Math.max(0, p95LatencyMs ?? 0) / STOP_P95_SCALE_MS) * STOP_MAX_EXTRA_FRACTION,+ );+ const fraction = STOP_BASE_FRACTION + surcharge;+ const floor = top * fraction;+ let stopRank = 0;+ let stopTokens = 0;+ for (let i = 0; i < densityCurve.length; i++) {+ if (densityCurve[i]! < floor && stopRank >= 1) break;+ stopRank += 1;+ stopTokens += tokens[i] ?? 0;+ }+ return Object.freeze({+ stopRank,+ stopTokens,+ reason:+ `stop after ${stopRank} page(s): density floor ${floor.toFixed(4)} ` ++ `(${(fraction * 100).toFixed(0)}% of top) given p95 ${p95LatencyMs ?? 0}ms`,+ });+}diff --git a/src/core/brain/recall-inject.ts b/src/core/brain/recall-inject.tsindex 3a345032..8bbf725c 100644--- a/src/core/brain/recall-inject.ts+++ b/src/core/brain/recall-inject.ts@@ -20,6 +20,13 @@import { deriveRecallHint, type RecallHintInput } from "../search/recall-hint.ts";import { searchAcrossVaults } from "../search/cross-vault.ts";+import type { SurfacingGateReason } from "../search/surfacing-gate.ts";+import {+ computeSurfacingKey,+ SURFACING_ADMISSION_FLOORS,+ type SurfacingKeyDecision,+} from "../search/surfacing-key.ts";+import { RECALL_CHANNEL } from "./recall-telemetry.ts";import type { RetrievalDegradationCode } from "../search/retrieval-trail.ts";import type { RecallSource } from "./portability/recall-sources.ts";import { LOCAL_ORIGIN } from "./portability/origins.ts";@@ -62,8 +69,13 @@ export const RECALL_INJECT_TIME_BUDGET_MS = 2_500;* about a third of what was asked, which sits below* `COMPLETENESS_PARTIAL_THRESHOLD` (0.4) - this gate filters noise, it* does not demand a complete retrieval.+ *+ * Owned by `SURFACING_ADMISSION_FLOORS.hook` (`surfacing-key.ts`), the+ * shared calculator's hook member, so the gate's diagnostic grading and+ * this floor cannot drift apart; this export keeps the name and value+ * every caller and config test pins.*/-export const RECALL_INJECT_CONFIDENCE_FLOOR = 0.35;+export const RECALL_INJECT_CONFIDENCE_FLOOR = SURFACING_ADMISSION_FLOORS.hook;/** One relevance-matched note, narrowed to exactly what the brief needs. */export interface RecallCandidate {@@ -268,7 +280,18 @@ export type RecallAbstainReason =*/| "all_already_injected"/** Slices were declared and none of them placed a note in the brief. */- | "all_slices_abstained";+ | "all_slices_abstained"+ /**+ * The structural gate (`evaluateSurfacingGate`) refused before any+ * retrieval ran - the prompt is a verbatim repeat of its predecessor, a+ * slash command, a shell command, or empty, and the gate's own reason+ * rides `structuralReason`. `decideRecallInject` itself never returns+ * this: in production the transports run the gate AHEAD of this core,+ * and a caller that reproduces that composition (the bench's+ * proactive-recall arm) persists the refusal as this member, so an+ * abstention always names the layer that refused it.+ */+ | "structural";/*** Why an attempt failed, as a closed vocabulary rather than as prose.@@ -321,8 +344,13 @@ export type RecallInjectDecision =readonly brief: string;readonly noteCount: number;readonly topScore: number;- /** The quantity the floor was compared against; see the floor's docblock. */- readonly matchQuality: number;+ /**+ * The quantity the floor was compared against; see the floor's+ * docblock. Null on an inject admitted without a comparable+ * measurement (an explicit request or an unmeasurable report):+ * the graded admission carried it as a null key.+ */+ readonly matchQuality: number | null;/*** Exactly the notes rendered into {@link brief}, in brief order:* after the char-budget fit and after the decision-model filter. The@@ -340,6 +368,13 @@ export type RecallInjectDecision =| {readonly kind: "abstain";readonly reason: RecallAbstainReason;+ /**+ * Present only on a `structural` abstain: the gate's own closed+ * reason (`duplicate`, `slash_command`, `shell_command`, `empty`),+ * carried beside the carrier member so the abstention says both+ * which layer refused and why.+ */+ readonly structuralReason?: SurfacingGateReason;readonly topScore: number;/*** The quantity the floor was compared against; see the floor's@@ -520,21 +555,32 @@ async function decideOverRetrieval(// what the brief's bullets show and what the audit line records - it is// simply no longer allowed to decide anything.//+ // Admission is the SHARED calculator (`surfacing-key.ts`), not a+ // private floor comparison: the gate channel grades the same quality+ // against the same bound, so a boundary decision is identical on every+ // channel. The floor override rides the calculator's `floor` parameter.+ //// No quality means no comparison. Abstaining is the explicit choice- // this branch makes rather than a fallback: the alternative was the- // producer's old `1`, which put every unweighable prompt above every- // floor and injected on it.- if (matchQuality === null) {+ // the `unmeasurable_quality` tier makes rather than a fallback: the+ // alternative was the producer's old `1`, which put every unweighable+ // prompt above every floor and injected on it.+ let admission: SurfacingKeyDecision;+ try {+ admission = computeSurfacingKey({ matchQuality, channel: RECALL_CHANNEL.hook, floor });+ } catch (exc) {+ // A retriever that reports NaN where the contract says a [0,1] number+ // or `null` has broken its report contract - an explicit error+ // decision, never a silent admit.+ return retrievalError(exc);+ }+ if (!admission.admit) {return Object.freeze({kind: "abstain",- reason: "unmeasurable_quality",+ reason: admission.reason,topScore,matchQuality,});}- if (matchQuality < floor) {- return Object.freeze({ kind: "abstain", reason: "below_floor", topScore, matchQuality });- }// Dedupe sits after the floor, which read the unfiltered retrieval, and// before the cap. There is no over-fetch: the coverage the floor read is@@ -617,8 +663,13 @@ function judgeSlice(spec: RecallSliceSpec, set: RecallResultSet, floor: number):const topScore = ranked[0]?.score ?? 0;const base = { spec, ranked, total: set.total, topScore, matchQuality };if (ranked.length === 0) return { ...base, outcome: "no_matches" };- if (matchQuality === null) return { ...base, outcome: "unmeasurable_quality" };- if (matchQuality < floor) return { ...base, outcome: "below_floor" };+ // The same shared admission calculator the single-pool path uses, so a+ // slice and a whole-pool verdict agree at the tier boundaries. A+ // malformed quality report throws the calculator's named refusal, which+ // the caller catches into the same explicit error decision a broken+ // retrieval gets.+ const admission = computeSurfacingKey({ matchQuality, channel: RECALL_CHANNEL.hook, floor });+ if (!admission.admit) return { ...base, outcome: admission.reason };return { ...base, outcome: "inject" };}@@ -651,7 +702,16 @@ async function decideSliced(} catch (exc) {return retrievalError(exc);}- const verdicts = slices.map((spec, i) => judgeSlice(spec, sets[i]!, caps.floor));+ let verdicts: ReadonlyArray<SliceVerdict>;+ try {+ verdicts = slices.map((spec, i) => judgeSlice(spec, sets[i]!, caps.floor));+ } catch (exc) {+ // A slice's coverage report broke the calculator's contract (a+ // non-finite or out-of-range `idfWeightedCoverage`): the same explicit+ // error decision a broken or slow retrieval gets, never a throw out of+ // the exported decision core.+ return retrievalError(exc);+ }const total = sets.reduce((sum, set) => sum + set.total, 0);const groups = verdicts.map((v) =>v.outcome === "inject" ? withoutDelivered(v.ranked, options) : [],@@ -1075,6 +1135,12 @@ export function recallInjectTelemetryMetadata(return Object.freeze({decision: "abstain",reason: decision.reason,+ // The gate's own reason is a closed classification like the abstain+ // reason itself, so it satisfies the same names-nothing-sensitive+ // rule; dropping it would leave an unexplainable `structural`.+ ...(decision.structuralReason !== undefined+ ? { structural_reason: decision.structuralReason }+ : {}),top_score: decision.topScore,match_quality: decision.matchQuality,...decisionModelTelemetry(decision.decisionModel),diff --git a/src/core/brain/retrieval-plan.ts b/src/core/brain/retrieval-plan.tsindex 57f90222..f9b333ec 100644--- a/src/core/brain/retrieval-plan.ts+++ b/src/core/brain/retrieval-plan.ts@@ -32,6 +32,7 @@ import { packContext, type ContextPackReport } from "./context-pack.ts";import { summarizeTokenImpact, type TokenImpactSummary } from "./token-impact.ts";import { summarizeMcpRouteLatency, type McpRouteLatencySummary } from "./mcp-route-metrics.ts";import { loadSchemaPack } from "./schema-pack.ts";+import { marginalValueStop, type RetrievalPlanMarginalStop } from "./marginal-value-stop.ts";// ----- Tunables -------------------------------------------------------------@@ -39,16 +40,16 @@ import { loadSchemaPack } from "./schema-pack.ts";export const DEFAULT_PLAN_TOKEN_BUDGET = 2000;/** The MCP route whose observed latency drives the reliability read. */export const RETRIEVAL_PLAN_ROUTE = "brain_search";-/**- * Marginal-value stop: a page is worth including only while its density is at- * least this fraction of the top page's density. The fraction is the base- * plus a p95-scaled surcharge, so a slow route demands denser pages.- */-export const STOP_BASE_FRACTION = 0.25;-/** p95 latency (ms) that adds the full {@link STOP_MAX_EXTRA_FRACTION} surcharge. */-export const STOP_P95_SCALE_MS = 4000;-/** Cap on the p95-driven surcharge added to {@link STOP_BASE_FRACTION}. */-export const STOP_MAX_EXTRA_FRACTION = 0.5;+// The stop predicate is a pure leaf (see ./marginal-value-stop.ts); its+// tunables, verdict type and function are re-exported here unchanged, so+// the advisor's public surface and every existing consumer are untouched.+export {+ STOP_BASE_FRACTION,+ STOP_MAX_EXTRA_FRACTION,+ STOP_P95_SCALE_MS,+ marginalValueStop,+ type RetrievalPlanMarginalStop,+} from "./marginal-value-stop.ts";/** Graph-expansion hop suggestions per structural intent. */const HOPS_BY_INTENT: Readonly<Record<QueryIntent, number>> = Object.freeze({broad: 2,@@ -89,14 +90,6 @@ export interface RetrievalPlanReliability {readonly firstPassRate: number | null;}-export interface RetrievalPlanMarginalStop {- /** Include this many leading pages; beyond it marginal value < cost. */- readonly stopRank: number;- /** Cumulative tokens of the leading pages up to the stop. */- readonly stopTokens: number;- readonly reason: string;-}-export interface RetrievalPlanAdvice {readonly question: string;readonly strategy: RetrievalPlanStrategy;@@ -186,43 +179,6 @@ function reliabilityFrom(});}-/**- * The marginal-value stop over the density curve. A page is worth its tokens- * while its density is at least `effectiveFraction * topDensity`, where the- * fraction climbs with p95 latency. At least one page is always included when- * any exist. A flat (zero-density) curve keeps the whole allocation.- */-function marginalStop(- densityCurve: ReadonlyArray<number>,- tokens: ReadonlyArray<number>,- p95LatencyMs: number | null,-): RetrievalPlanMarginalStop {- if (densityCurve.length === 0) {- return Object.freeze({ stopRank: 0, stopTokens: 0, reason: "no candidates to allocate" });- }- const top = densityCurve[0]!;- const surcharge = Math.min(- STOP_MAX_EXTRA_FRACTION,- (Math.max(0, p95LatencyMs ?? 0) / STOP_P95_SCALE_MS) * STOP_MAX_EXTRA_FRACTION,- );- const fraction = STOP_BASE_FRACTION + surcharge;- const floor = top * fraction;- let stopRank = 0;- let stopTokens = 0;- for (let i = 0; i < densityCurve.length; i++) {- if (densityCurve[i]! < floor && stopRank >= 1) break;- stopRank += 1;- stopTokens += tokens[i] ?? 0;- }- return Object.freeze({- stopRank,- stopTokens,- reason:- `stop after ${stopRank} page(s): density floor ${floor.toFixed(4)} ` +- `(${(fraction * 100).toFixed(0)}% of top) given p95 ${p95LatencyMs ?? 0}ms`,- });-}-/*** Build the read-only retrieval plan for one question. Pure with respect to* the vault: it composes existing signals and writes nothing.@@ -260,7 +216,7 @@ export function buildRetrievalPlan(}),graphExpansion: graphExpansionFor(queryPlan.intent),reliability,- marginalStop: marginalStop(densityCurve, tokens, reliability.p95LatencyMs),+ marginalStop: marginalValueStop(densityCurve, tokens, reliability.p95LatencyMs),});}diff --git a/src/core/brain/session-recall.ts b/src/core/brain/session-recall.tsindex ed1c8d2d..abf4ef4c 100644--- a/src/core/brain/session-recall.ts+++ b/src/core/brain/session-recall.ts@@ -18,6 +18,15 @@ import {import { readLineageLedger } from "./lineage/ledger.ts";import type { SessionLineage } from "./lineage/types.ts";import { PayloadRegistry, withPayloadStoreLock } from "./payload-registry.ts";+import { applyCharBudget } from "./recall-budget.ts";+import {+ TOPIC_BUDGET_FLOOR,+ detectThreadFacets,+ resolveTopicBudget,+ type ThreadFacet,+ type ThreadFacetMention,+ type ThreadFacetOrigin,+} from "./thread-topics.ts";import {BRAIN_SESSION_PAYLOAD_DEFAULTS,loadBrainConfigDetailed,@@ -137,6 +146,13 @@ export interface DescribeSessionRecallInput {* row, the local behaviour.*/readonly withholdPrivate?: boolean;+ /**+ * Include the coverage topic report (t_2c2a883c): the facets the+ * coverage operation would detect over this session's lineage scope+ * and the adaptive topic budget they clamp to. Omitted keeps the+ * result byte-identical to the pre-topic shape.+ */+ readonly topics?: boolean;}export interface SessionLineageSegment {@@ -144,6 +160,18 @@ export interface SessionLineageSegment {readonly parent_session_id: string | null;}+/**+ * The coverage topic budget over one scope: what+ * {@link coverageSessionRecall} would fan out over, without running the+ * selection.+ */+export interface SessionCoverageTopicReport {+ readonly facets_detected: number;+ readonly topics_requested: number;+ readonly topics_realized: number;+ readonly topics: ReadonlyArray<SessionCoverageTopic>;+}+export interface DescribeSessionRecallResult {readonly session_id: string;readonly raw_turns: number;@@ -156,6 +184,11 @@ export interface DescribeSessionRecallResult {*/readonly lineage_root?: string;readonly segments?: ReadonlyArray<SessionLineageSegment>;+ /**+ * Present only under `topics` (t_2c2a883c): the adaptive topic budget+ * this session's thread clamps to and the facets it detected.+ */+ readonly topic_report?: SessionCoverageTopicReport;}export interface ExpandSessionRecallInput {@@ -326,10 +359,36 @@ export function describeSessionRecall(raw_turns: rawTurns.length,summary_nodes: summaries.length,depths: Object.freeze(depths),+ ...(input.topics === true ? { topic_report: coverageTopicReport(vault, records) } : {}),...lineageDescription(vault, records, input.sessionId),});}+/**+ * The adaptive topic budget over one scope's record set, without running+ * the selection: the facets {@link coverageSessionRecall} would detect+ * and what they clamp to between the exported floor and cap.+ */+function coverageTopicReport(+ vault: string,+ records: ReadonlyArray<ContinuityRecord>,+): SessionCoverageTopicReport {+ const facets = detectCoverageFacets(vault, records);+ const { budget, realized } = resolveTopicBudget(facets.length);+ return Object.freeze({+ facets_detected: facets.length,+ topics_requested: budget,+ topics_realized: realized,+ topics: Object.freeze(+ facets+ .slice(0, budget)+ .map((facet) =>+ Object.freeze({ key: facet.key, origin: facet.origin, turn_count: facet.turnIds.length }),+ ),+ ),+ });+}+/*** Lineage fields for `describeSessionRecall`: present only when the* conversation spans more than one segment. Segments are listed in@@ -425,6 +484,624 @@ function lineagePayloadFields(lineage: SessionLineage | undefined): Record<strin};}+// ----- Coverage-first selection (recall-quality wave, Lane B / t_2c2a883c) ---++export interface SessionCoverageInput {+ readonly sessionId?: string;+ /**+ * Seed the coverage call from a mined entity key (t_2c2a883c, design+ * decision 13, read-side only): the key resolves through its existing+ * `session_entity_mention` rows ({@link resolveEntityMentionRows}) to+ * the sessions that name it, the selection runs over their lineage+ * scopes, and the key's own facets lead the fan-out. A key with no+ * rows - or whose establishing turns no imported record carries -+ * raises the typed {@link SessionCoverageEntityUnknownError}, never an+ * empty silent result.+ */+ readonly entityKey?: string;+ /**+ * Leave out continuity rows flagged `private` and the summary nodes+ * built from them, exactly as {@link searchSessionRecall} does.+ */+ readonly withholdPrivate?: boolean;+ /**+ * Total character budget for the selected evidence, measured over the+ * serialized turns the operation emits. The floor-weighted selection+ * must fit or the typed infeasibility error is raised (never a silent+ * drop below the floor).+ */+ readonly charBudget: number;+}++/** One realized fan-out topic, as the diagnostics report it. */+export interface SessionCoverageTopic {+ readonly key: string;+ readonly origin: ThreadFacetOrigin;+ /** In-scope turns establishing this topic. */+ readonly turn_count: number;+}++export interface SessionCoverageDiagnostics {+ /** Distinct facets detected over the scoped record set. */+ readonly facets_detected: number;+ /** Topics the fan-out was budgeted for (the adaptive topic budget). */+ readonly topics_requested: number;+ /** Topics actually fanned out (never silently fewer than requested). */+ readonly topics_realized: number;+ /** The realized topics, in fan-out order. */+ readonly topics: ReadonlyArray<SessionCoverageTopic>;+ /** Characters of serialized evidence the selection kept. */+ readonly chars_used: number;+ /** Turns the character budget dropped, in rank order (never silent). */+ readonly dropped_turn_ids: ReadonlyArray<string>;+}++export interface SessionCoverageResult {+ /** Selected raw turns, re-emitted in `compareRecords` chronological order. */+ readonly turns: ReadonlyArray<ExpandedRawTurn>;+ readonly diagnostics: SessionCoverageDiagnostics;+}++/**+ * Coverage-first selection over a conversation thread+ * (recall-quality wave, Lane B / t_2c2a883c).+ *+ * Retrieve wide, then compress: facets are detected from the thread's+ * own records (depth-1 summary clusters and mined entity keys, through+ * {@link detectThreadFacets}), the pass fans out over the adaptive topic+ * budget ({@link resolveTopicBudget}: clamp of the facet count between+ * the exported floor and cap), and the union of matching turns is ranked+ * by relevance, selected under the caller's character budget through the+ * shared {@link applyCharBudget} primitive (wrapped, never forked), and+ * re-emitted in {@link compareRecords} chronological order. Every drop+ * is named in the diagnostics; nothing degrades silently.+ *+ * An `entityKey` seed (t_2c2a883c design decision 13) resolves read-side+ * through its `session_entity_mention` rows: absent `sessionId`, the+ * scope is the union of the mentioned sessions' lineage scopes, and the+ * key's own facets lead the fan-out so the topic budget cannot cut the+ * facet the call was seeded for. A seed that cannot reach an imported+ * establishing turn raises {@link SessionCoverageEntityUnknownError}.+ */+export function coverageSessionRecall(+ vault: string,+ input: SessionCoverageInput,+): SessionCoverageResult {+ if (+ typeof input.charBudget !== "number" ||+ !Number.isFinite(input.charBudget) ||+ input.charBudget <= 0+ ) {+ throw new Error("session recall coverage: charBudget must be a positive finite number");+ }+ const seed =+ input.entityKey !== undefined ? resolveEntityMentionRows(vault, input.entityKey) : undefined;+ const records =+ seed === undefined+ ? sessionRecallRecords(vault, input.sessionId, input.withholdPrivate)+ : entitySeededRecords(vault, input, seed);+ assertEntitySeedReachesScope(input.entityKey, seed, records, input.withholdPrivate === true);+ const facets = detectCoverageFacets(vault, records);+ const { budget } = resolveTopicBudget(facets.length);+ const topics =+ seed === undefined+ ? facets.slice(0, budget)+ : seededFacetsFirst(facets, input.entityKey!).slice(0, budget);+ const matches = rankTopicMatches(records, topics);+ const serialized = matches.map((match) => JSON.stringify(expandedRawTurn(match.record)));+ const budgeted = applyCharBudget(+ matches.map((match, index) => ({ item: match, text: serialized[index]! })),+ { maxTotalChars: input.charBudget },+ );+ // Floor enforcement verifies what the real selection kept, never what+ // an arithmetic prediction claimed about it.+ assertFloorSelectionRealized(+ topics,+ matches,+ serialized,+ input.charBudget,+ budgeted.kept.map((entry) => entry.item),+ );+ const kept = budgeted.kept+ .map((entry) => entry.item)+ .toSorted((left, right) => compareRecords(left.record, right.record));+ return Object.freeze({+ turns: Object.freeze(kept.map((match) => expandedRawTurn(match.record))),+ diagnostics: Object.freeze({+ facets_detected: facets.length,+ topics_requested: budget,+ topics_realized: topics.length,+ topics: Object.freeze(+ topics.map((facet) =>+ Object.freeze({ key: facet.key, origin: facet.origin, turn_count: facet.turnIds.length }),+ ),+ ),+ chars_used: budgeted.totalChars,+ dropped_turn_ids: Object.freeze(budgeted.dropped.map((match) => turnIdOf(match.record))),+ }),+ });+}++/**+ * One resolved `session_entity_mention` row: the payload spine the+ * ledger writes per (family, key, session), provenance-grade and already+ * on disk - the entity-thread dimension reads it, never re-mines it.+ */+export interface SessionEntityMentionRow {+ readonly family: string;+ readonly key: string;+ readonly session_ref: string;+ readonly turn_id: string;+}++/**+ * Resolve a mined entity key to its `session_entity_mention` rows+ * (t_2c2a883c design decision 13, read-side only): every ledger row+ * whose payload names the key, private rows withheld. A key no row+ * names raises the typed {@link SessionCoverageEntityUnknownError} -+ * resolution never answers an unknown key with an empty silent list.+ */+export function resolveEntityMentionRows(+ vault: string,+ entityKey: string,+): ReadonlyArray<SessionEntityMentionRow> {+ const rows: SessionEntityMentionRow[] = [];+ for (const record of listContinuityRecords(vault, { kind: "session_entity_mention" })) {+ if (record.private) continue;+ const family = record.payload["family"];+ const key = record.payload["key"];+ const sessionRef = record.payload["session_ref"];+ const turnId = record.payload["turn_id"];+ if (+ typeof family !== "string" ||+ typeof key !== "string" ||+ typeof sessionRef !== "string" ||+ typeof turnId !== "string"+ ) {+ continue;+ }+ if (key === entityKey) rows.push({ family, key, session_ref: sessionRef, turn_id: turnId });+ }+ if (rows.length === 0) {+ throw new SessionCoverageEntityUnknownError({+ entityKey,+ reason: "no_mention_rows",+ mentionRows: 0,+ });+ }+ return rows;+}++/**+ * The record set an entity-seeded coverage call selects over: an+ * explicit `sessionId` keeps its own lineage scope (the seed must hold+ * inside it - see {@link assertEntitySeedReachesScope}); otherwise the+ * union of the mentioned sessions' lineage scopes, deduped by record id+ * (lineage links overlap across sessions) and re-sorted into the shared+ * {@link compareRecords} order - concatenating per session would let the+ * mention rows' order decide facet order, and with it which facets+ * survive the topic budget.+ */+function entitySeededRecords(+ vault: string,+ input: SessionCoverageInput,+ rows: ReadonlyArray<SessionEntityMentionRow>,+): ContinuityRecord[] {+ if (input.sessionId !== undefined) {+ return sessionRecallRecords(vault, input.sessionId, input.withholdPrivate);+ }+ const deduped = new Map<string, ContinuityRecord>();+ for (const sessionRef of new Set(rows.map((row) => row.session_ref))) {+ for (const record of sessionRecallRecords(vault, sessionRef, input.withholdPrivate)) {+ if (!deduped.has(record.id)) deduped.set(record.id, record);+ }+ }+ return [...deduped.values()].sort(compareRecords);+}++/**+ * An entity seed must reach imported evidence: at least one establishing+ * turn of the key has to be a raw turn of the scoped record set. A key+ * whose rows all name sessions or turns the recall DAG never imported+ * raises the typed {@link SessionCoverageEntityUnknownError} - never a+ * silently generic result over an empty scope. At remote reach+ * (`withholdPrivate`) the refusal uses the no-rows wording for both+ * reasons: which keys still have mention rows behind the withheld turns+ * is itself withheld.+ */+function assertEntitySeedReachesScope(+ entityKey: string | undefined,+ rows: ReadonlyArray<SessionEntityMentionRow> | undefined,+ records: ReadonlyArray<ContinuityRecord>,+ withholdPrivate: boolean,+): void {+ if (entityKey === undefined || rows === undefined) return;+ const scopedTurns = new Set<string>();+ for (const record of records) {+ if (record.kind !== "session_turn") continue;+ const sessionId = sessionIdOf(record.payload);+ const turnId = turnIdOf(record);+ if (sessionId !== undefined && turnId.length > 0) {+ scopedTurns.add(qualifiedTurnId(sessionId, turnId));+ }+ }+ // The pair, not the bare turn id: in a multi-session scope a row for+ // one session's turn must never be satisfied by another session's+ // same-named turn.+ if (rows.some((row) => scopedTurns.has(qualifiedTurnId(row.session_ref, row.turn_id)))) return;+ throw new SessionCoverageEntityUnknownError({+ entityKey,+ reason: "no_imported_turns",+ mentionRows: rows.length,+ ...(withholdPrivate ? { withholdPrivate: true } : {}),+ });+}++/**+ * Fan-out order for an entity-seeded call: the key's own mined facets+ * lead (stable otherwise), so the adaptive budget's cut can never drop+ * the facet the call was seeded for. The establishing-turn guard above+ * has already proven at least one such facet exists.+ */+function seededFacetsFirst(facets: ReadonlyArray<ThreadFacet>, entityKey: string): ThreadFacet[] {+ const pinned = facets.filter((facet) => facet.origin === "mined" && facet.needle === entityKey);+ if (pinned.length === 0) return [...facets];+ const pinnedKeys = new Set(pinned);+ return [...pinned, ...facets.filter((facet) => !pinnedKeys.has(facet))];+}++/**+ * The floor-violation guard (t_2c2a883c, design decision 10): after the+ * real {@link applyCharBudget} selection, every floor topic must have+ * realized its minimum - ANY of its turns kept. A mined facet's top-ranked+ * turn is usually its largest (the score is 2 + occurrences, so a pasted+ * log outranks its own topic's short mentions), and a budget the greedy+ * pass spends on that log while keeping the topic's smaller evidence is a+ * satisfied floor, not an infeasible one. Only the outcome of the actual+ * selection is authoritative: it spends code points (not UTF-16 units) and+ * skips entries a prefix-sum arithmetic would have charged. A floor topic+ * whose every matching turn was crowded out raises the typed+ * {@link SessionCoverageInfeasibleError} - never a silent zero-evidence+ * topic.+ */+function assertFloorSelectionRealized(+ topics: ReadonlyArray<ThreadFacet>,+ matches: ReadonlyArray<TopicMatch>,+ serialized: ReadonlyArray<string>,+ charBudget: number,+ kept: ReadonlyArray<TopicMatch>,+): void {+ const { requiredTopics, realizedTopics, requiredChars } = floorRequirement(+ topics,+ matches,+ serialized,+ kept,+ );+ if (requiredTopics.length === 0) return;+ if (realizedTopics.length === requiredTopics.length) return;+ throw new SessionCoverageInfeasibleError({+ topicFloor: TOPIC_BUDGET_FLOOR,+ requestedTopics: topics.length,+ keptTopics: realizedTopics.length,+ requiredChars,+ charBudget,+ });+}++interface FloorRequirement {+ /**+ * The floor topics that have at least one matching turn - the only ones+ * that can contribute to the floor.+ */+ readonly requiredTopics: ReadonlyArray<ThreadFacet>;+ /** The required topics the real selection kept at least one turn of. */+ readonly realizedTopics: ReadonlyArray<ThreadFacet>;+ /**+ * Code points of the cheapest matching turn per required topic, each+ * distinct turn charged once - the honest retry bound: the smallest+ * per-topic evidence the floor asks the selection to hold, in the unit+ * {@link applyCharBudget} spends. The rank-prefix sum this replaces+ * compounded every rank up to the deepest floor turn and could name a+ * bound many times larger than what the floor actually needs.+ */+ readonly requiredChars: number;+}++/** The priced requirement behind the floor guard's retry bound. */+function floorRequirement(+ topics: ReadonlyArray<ThreadFacet>,+ matches: ReadonlyArray<TopicMatch>,+ serialized: ReadonlyArray<string>,+ kept: ReadonlyArray<TopicMatch>,+): FloorRequirement {+ const floorTopics = topics.slice(0, Math.min(topics.length, TOPIC_BUDGET_FLOOR));+ const floorKeys = new Set(floorTopics.map((topic) => topic.key));+ // Per required topic: whether any of its turns was kept, and its+ // cheapest matching turn (rank order breaks length ties).+ const keptIds = new Set(kept.map((match) => match.record.id));+ const realized = new Set<string>();+ const cheapest = new Map<string, { turnId: string; chars: number }>();+ matches.forEach((match, index) => {+ const keptThis = keptIds.has(match.record.id);+ const chars = [...serialized[index]!].length;+ for (const key of match.topics) {+ if (!floorKeys.has(key)) continue;+ if (keptThis) realized.add(key);+ const incumbent = cheapest.get(key);+ if (incumbent === undefined || chars < incumbent.chars) {+ cheapest.set(key, { turnId: match.record.id, chars });+ }+ }+ });+ const requiredTopics = floorTopics.filter((topic) => cheapest.has(topic.key));+ const realizedTopics = requiredTopics.filter((topic) => realized.has(topic.key));+ // The cheapest turn per required topic, each distinct turn charged once:+ // topics can share their cheapest turn, and charging it twice would+ // overstate the floor's own requirement.+ const priced = new Set<string>();+ let requiredChars = 0;+ for (const topic of requiredTopics) {+ const entry = cheapest.get(topic.key)!;+ if (priced.has(entry.turnId)) continue;+ priced.add(entry.turnId);+ requiredChars += entry.chars;+ }+ return { requiredTopics, realizedTopics, requiredChars };+}++/**+ * The typed error family of the coverage operation (t_2c2a883c): every+ * refusal the selection can produce - a budget below the floor-weighted+ * selection, an entity seed with no reachable evidence - is a named+ * subclass of this one, so callers (and the MCP INVALID_PARAMS mapping)+ * can catch the family without catching unrelated failures.+ */+export class SessionCoverageError extends Error {+ constructor(message: string) {+ super(message);+ this.name = "SessionCoverageError";+ }+}++/**+ * The floor of the adaptive topic budget cannot be honored within the+ * caller's character budget (t_2c2a883c). Carries the recomputable+ * diagnostics so the caller can retry with a larger budget: which floor+ * was violated, the topics requested and representable, and the+ * characters the floor-weighted selection needs. Over MCP this maps to+ * INVALID_PARAMS.+ */+export class SessionCoverageInfeasibleError extends SessionCoverageError {+ readonly topicFloor: number;+ readonly requestedTopics: number;+ readonly keptTopics: number;+ readonly requiredChars: number;+ readonly charBudget: number;++ constructor(details: {+ topicFloor: number;+ requestedTopics: number;+ keptTopics: number;+ requiredChars: number;+ charBudget: number;+ }) {+ super(+ `session recall coverage: character budget ${details.charBudget} cannot hold the ` ++ `floor-weighted selection of floor ${details.topicFloor} - requested topics ` ++ `${details.requestedTopics}, kept topics ${details.keptTopics}, required chars ` ++ `${details.requiredChars}; retry with a larger charBudget`,+ );+ this.name = "SessionCoverageInfeasibleError";+ this.topicFloor = details.topicFloor;+ this.requestedTopics = details.requestedTopics;+ this.keptTopics = details.keptTopics;+ this.requiredChars = details.requiredChars;+ this.charBudget = details.charBudget;+ }+}++/** Why an entity key could not seed a coverage call. */+export type SessionCoverageEntitySeedFailure = "no_mention_rows" | "no_imported_turns";++/**+ * An entity key cannot seed a coverage call with evidence (t_2c2a883c+ * design decision 13): no `session_entity_mention` row names the key, or+ * every row that does names a session or turn the recall DAG never+ * imported. Carries the key, the failure reason and the resolved row+ * count so the caller can retry with a key the ledger actually holds -+ * never an empty silent result. Same typed family as the infeasibility+ * error; over MCP both map to INVALID_PARAMS.+ *+ * With `withholdPrivate` (remote reach) both reasons answer with the+ * no-rows MESSAGE: whether mention rows still exist for a key whose+ * turns are withheld is itself withheld, and two distinguishable+ * refusals would leak exactly that. The typed `reason` stays truthful+ * for local diagnostics.+ */+export class SessionCoverageEntityUnknownError extends SessionCoverageError {+ readonly entityKey: string;+ readonly reason: SessionCoverageEntitySeedFailure;+ readonly mentionRows: number;++ constructor(details: {+ entityKey: string;+ reason: SessionCoverageEntitySeedFailure;+ mentionRows: number;+ withholdPrivate?: boolean;+ }) {+ super(+ details.withholdPrivate === true || details.reason === "no_mention_rows"+ ? `session recall coverage: no session_entity_mention row names the entity key ${details.entityKey}`+ : `session recall coverage: no imported turn establishes the entity key ` ++ `${details.entityKey} (${details.mentionRows} mention row(s) name it, none joins ` ++ `the recall DAG scope)`,+ );+ this.name = "SessionCoverageEntityUnknownError";+ this.entityKey = details.entityKey;+ this.reason = details.reason;+ this.mentionRows = details.mentionRows;+ }+}++/** The `turn_id` payload key of a raw-turn record ("" when absent). */+function turnIdOf(record: ContinuityRecord): string {+ return String(record.payload["turn_id"] ?? "");+}++/**+ * Session-qualified turn identity: `SessionTurn.turnId` can repeat across+ * sessions, and a multi-session scope (entity seeding) mixes lineages, so+ * a bare `turn_id` is not a turn identity wherever the coverage path+ * matches mentions, cluster source lists and turn records against each+ * other. The public output keeps the bare turn ids; this qualifies only+ * that internal plumbing.+ */+function qualifiedTurnId(sessionId: string, turnId: string): string {+ return `${sessionId}\u0000${turnId}`;+}++/**+ * The scoped record set's coverage facets: depth-1 summary clusters (the+ * thread's own topic skeleton - a depth-1 node's source turn list+ * partitions the segment's turns) plus the mined entity keys whose+ * mention rows name a session of the scope. Detection itself is the pure+ * {@link detectThreadFacets}; this is the record-set projection into its+ * input. A cluster with no in-scope turns, and a mention naming a+ * session outside the scope or a turn the recall DAG never imported,+ * cannot contribute coverage and is not detected as a facet - nothing+ * selectable is dropped silently, and the ledger rows remain for every+ * other reader. Turn identity is session-qualified+ * ({@link qualifiedTurnId}), so {@link detectThreadFacets} orders and+ * counts turns per session even when the transcripts reuse turn ids.+ */+function detectCoverageFacets(+ vault: string,+ records: ReadonlyArray<ContinuityRecord>,+): ReadonlyArray<ThreadFacet> {+ const turns: string[] = [];+ const clusters: Array<{ id: string; turnIds: ReadonlyArray<string> }> = [];+ for (const record of records) {+ if (record.kind === "session_turn") {+ const sessionId = sessionIdOf(record.payload);+ const turnId = turnIdOf(record);+ if (sessionId !== undefined && turnId.length > 0) {+ turns.push(qualifiedTurnId(sessionId, turnId));+ }+ continue;+ }+ if (record.kind !== "session_summary_node") continue;+ if (numberValue(record.payload["depth"]) !== 1) continue;+ const sessionId = sessionIdOf(record.payload);+ if (sessionId === undefined) continue;+ clusters.push({+ id: record.id,+ turnIds: collectTurnIds([record]).map((turnId) => qualifiedTurnId(sessionId, turnId)),+ });+ }+ return detectThreadFacets({ turns, mentions: scopedMentions(vault, records), clusters });+}++/**+ * The vault's mined-mention rows that name a session of the scope: the+ * payload spine ({@link ThreadFacetMention}) of every+ * `session_entity_mention` record whose `session_ref` joins the scope.+ * The ledger keys provenance by the same portable session identity the+ * recall DAG uses, so the join is direct.+ */+function scopedMentions(+ vault: string,+ records: ReadonlyArray<ContinuityRecord>,+): ReadonlyArray<ThreadFacetMention> {+ const scope = new Set<string>();+ for (const record of records) {+ const sid = sessionIdOf(record.payload);+ if (sid !== undefined) scope.add(sid);+ }+ const mentions: ThreadFacetMention[] = [];+ for (const record of listContinuityRecords(vault, { kind: "session_entity_mention" })) {+ // The same private-row rule the entity-seed reader applies: a+ // `<private>` mention never seeds a facet, so its key string cannot+ // surface through the diagnostics or the topic report.+ if (record.private) continue;+ const family = record.payload["family"];+ const key = record.payload["key"];+ const sessionRef = record.payload["session_ref"];+ const turnId = record.payload["turn_id"];+ if (+ typeof family !== "string" ||+ typeof key !== "string" ||+ typeof sessionRef !== "string" ||+ typeof turnId !== "string"+ ) {+ continue;+ }+ if (scope.has(sessionRef)) {+ mentions.push({ family, key, turnId: qualifiedTurnId(sessionRef, turnId) });+ }+ }+ return mentions;+}++/** One turn's accumulation of topic matches: score and the topics that hit it. */+interface TopicMatch {+ readonly record: ContinuityRecord;+ readonly topics: Set<string>;+ score: number;+}++/**+ * The wide pass: per topic, gather the in-scope turns it touches. Mined+ * facets match turn text through {@link hitFor} (the same keyword+ * machinery grep uses, so the two cannot drift); membership facets reach+ * their turns directly. A turn touched by several topics accumulates+ * their scores, which is what ranks multi-topic turns first.+ */+function rankTopicMatches(+ records: ReadonlyArray<ContinuityRecord>,+ topics: ReadonlyArray<ThreadFacet>,+): TopicMatch[] {+ const turnRecords = records.filter((record) => record.kind === "session_turn");+ // Membership facets name their turns by the same session-qualified+ // identity detectCoverageFacets built, so a cluster of one session can+ // never resolve to another session's same-named turn in a multi-session+ // scope.+ const byTurnId = new Map<string, ContinuityRecord>();+ for (const record of turnRecords) {+ const sessionId = sessionIdOf(record.payload);+ const turnId = turnIdOf(record);+ if (sessionId === undefined || turnId.length === 0) continue;+ const key = qualifiedTurnId(sessionId, turnId);+ if (!byTurnId.has(key)) byTurnId.set(key, record);+ }+ const matches = new Map<string, TopicMatch>();+ const add = (record: ContinuityRecord, score: number, topicKey: string): void => {+ const existing = matches.get(record.id);+ if (existing === undefined) {+ matches.set(record.id, { record, topics: new Set([topicKey]), score });+ return;+ }+ existing.topics.add(topicKey);+ existing.score += score;+ };+ for (const facet of topics) {+ if (facet.origin === "mined" && facet.needle !== null) {+ const needle = facet.needle.toLowerCase();+ for (const record of turnRecords) {+ const hit = hitFor(record, needle, 1);+ if (hit !== null) add(record, hit.score, facet.key);+ }+ continue;+ }+ for (const turnId of facet.turnIds) {+ const record = byTurnId.get(turnId);+ if (record !== undefined) add(record, 1, facet.key);+ }+ }+ return [...matches.values()].toSorted(+ (left, right) => right.score - left.score || compareRecords(left.record, right.record),+ );+}+/*** The vault's payload thresholds, or the defaults when `_brain.yaml`* cannot be read. Falling back rather than throwing keeps a broken config@@ -848,10 +1525,20 @@ function recordInTimeRange(return true;}+/**+ * Code-unit string order: the same order on every host, where+ * `localeCompare` varies with the host locale and would make record and+ * facet order - and with it what survives a budget cut - depend on where+ * the process runs.+ */+function compareCodeUnits(left: string, right: string): number {+ return left < right ? -1 : left > right ? 1 : 0;+}+function compareRecords(left: ContinuityRecord, right: ContinuityRecord): number {const leftTimestamp = String(left.payload["timestamp"] ?? left.createdAt);const rightTimestamp = String(right.payload["timestamp"] ?? right.createdAt);- return leftTimestamp.localeCompare(rightTimestamp) || left.id.localeCompare(right.id);+ return compareCodeUnits(leftTimestamp, rightTimestamp) || compareCodeUnits(left.id, right.id);}function numberValue(value: unknown): number | null {diff --git a/src/core/brain/thread-topics.ts b/src/core/brain/thread-topics.tsnew file mode 100644index 00000000..3d2db770--- /dev/null+++ b/src/core/brain/thread-topics.ts@@ -0,0 +1,157 @@+/**+ * Thread topics - pure facet detection and the adaptive topic budget+ * (recall-quality wave, Lane B / t_2c2a883c).+ *+ * Facets are derived from the thread itself, never from a word list:+ * distinct mined entity keys (`session_entity_mention` ledger rows) and+ * depth-1 summary clusters (the summary nodes whose source lists+ * partition a segment's turns). The topic budget is the corpus-shaped+ * clamp the wave design pins: budget = clamp(distinct facets, floor 12,+ * cap 16). "Adaptive" means the thread's own facet count decides where+ * between floor and cap the fan-out lands; the realized count is+ * reported honestly - a 3-facet thread floors at 12 and says 3 were+ * realized. The exported constants leave room for operator config to+ * layer later, exactly like `DEFAULT_GROUP_SIZE`.+ *+ * Pure and deterministic: no I/O, no clock, no randomness; the same+ * input yields the same facets in the same order across calls. Facet+ * order follows each facet's chronologically first establishing turn+ * (input turn order), so a budget cut spreads across the thread instead+ * of clustering at its head.+ */++/** Lower bound of the adaptive topic budget. */+export const TOPIC_BUDGET_FLOOR = 12;+/** Upper bound of the adaptive topic budget. */+export const TOPIC_BUDGET_CAP = 16;++/** Where one detected thread facet came from. */+export type ThreadFacetOrigin = "mined" | "cluster";++/**+ * One facet of a conversation thread: a distinct sub-topic the coverage+ * pass fans out over. A facet carries its in-scope establishing turns+ * and either a text needle (`mined` facets match turn text through the+ * same keyword machinery as grep) or cluster membership (`cluster`+ * facets reach their turns through the summary node's source list).+ */+export interface ThreadFacet {+ /** Stable facet id: `cluster:<record id>` or `mined:<family>:<key>`. */+ readonly key: string;+ readonly origin: ThreadFacetOrigin;+ /** Text needle for the keyword pass; `null` for membership facets. */+ readonly needle: string | null;+ /** In-scope establishing turns, in the input turn order. */+ readonly turnIds: ReadonlyArray<string>;+}++/** One mined-mention row scoped to the thread: the ledger's payload spine. */+export interface ThreadFacetMention {+ readonly family: string;+ readonly key: string;+ readonly turnId: string;+}++/** One depth-1 summary cluster scoped to the thread. */+export interface ThreadFacetCluster {+ readonly id: string;+ readonly turnIds: ReadonlyArray<string>;+}++export interface ThreadFacetInput {+ /** The thread's turn ids, in chronological order (the ordering axis). */+ readonly turns: ReadonlyArray<string>;+ readonly mentions: ReadonlyArray<ThreadFacetMention>;+ readonly clusters: ReadonlyArray<ThreadFacetCluster>;+}++/**+ * The clamped topic budget for a thread holding `distinctFacets`+ * distinct facets, plus the honest realized count: the fan-out can only+ * ever span the facets that exist.+ */+export function resolveTopicBudget(distinctFacets: number): {+ budget: number;+ realized: number;+} {+ const budget = clampTopicBudget(distinctFacets);+ return { budget, realized: Math.min(distinctFacets, budget) };+}++/** clamp(distinctFacets, TOPIC_BUDGET_FLOOR, TOPIC_BUDGET_CAP). */+export function clampTopicBudget(distinctFacets: number): number {+ return Math.min(Math.max(distinctFacets, TOPIC_BUDGET_FLOOR), TOPIC_BUDGET_CAP);+}++/**+ * Detect a thread's coverage facets from its own records. Mined mentions+ * group into family-scoped facets (the ledger's keys are case-sensitive,+ * so `SessionStore` and `sessionstore` stay distinct); clusters become+ * membership facets. A facet whose establishing turns all fall outside+ * the thread cannot contribute coverage and is not detected - nothing+ * selectable is dropped, and the ledger rows remain for every other+ * reader.+ */+export function detectThreadFacets(input: ThreadFacetInput): ReadonlyArray<ThreadFacet> {+ const order = new Map<string, number>();+ input.turns.forEach((turnId, index) => {+ if (!order.has(turnId)) order.set(turnId, index);+ });+ const facets: ThreadFacet[] = [];+ interface MinedGroup {+ readonly family: string;+ readonly key: string;+ readonly turnIds: string[];+ }+ const mined = new Map<string, MinedGroup>();+ for (const mention of input.mentions) {+ if (!order.has(mention.turnId)) continue;+ const facetKey = `mined:${mention.family}:${mention.key}`;+ const group = mined.get(facetKey);+ if (group === undefined) {+ mined.set(facetKey, { family: mention.family, key: mention.key, turnIds: [mention.turnId] });+ } else if (!group.turnIds.includes(mention.turnId)) {+ group.turnIds.push(mention.turnId);+ }+ }+ for (const [facetKey, group] of mined) {+ facets.push({+ key: facetKey,+ origin: "mined",+ needle: group.key,+ turnIds: group.turnIds,+ });+ }+ for (const cluster of input.clusters) {+ const turnIds: string[] = [];+ for (const turnId of cluster.turnIds) {+ if (order.has(turnId) && !turnIds.includes(turnId)) turnIds.push(turnId);+ }+ if (turnIds.length === 0) continue;+ facets.push({ key: `cluster:${cluster.id}`, origin: "cluster", needle: null, turnIds });+ }+ return facets.toSorted(+ (left, right) =>+ firstTurnIndex(left, order) - firstTurnIndex(right, order) ||+ compareCodeUnits(left.key, right.key),+ );+}++/**+ * Code-unit string order: the same order on every host, where+ * `localeCompare` varies with the host locale and would make the facet+ * tie-break - and with it what survives the topic budget - depend on+ * where the process runs.+ */+function compareCodeUnits(left: string, right: string): number {+ return left < right ? -1 : left > right ? 1 : 0;+}++function firstTurnIndex(facet: ThreadFacet, order: ReadonlyMap<string, number>): number {+ let best = Number.MAX_SAFE_INTEGER;+ for (const turnId of facet.turnIds) {+ const index = order.get(turnId);+ if (index !== undefined && index < best) best = index;+ }+ return best;+}diff --git a/src/core/search/coverage.ts b/src/core/search/coverage.tsindex 3ca56403..d2aae039 100644--- a/src/core/search/coverage.ts+++ b/src/core/search/coverage.ts@@ -220,6 +220,105 @@ export function planTargetedRetry(coverage: CoverageReport): TargetedRetryPlan {});}+/**+ * One follow-up sub-query: the terms to fetch in a single pull, and the+ * group's significance (the summed IDF of its terms) — the ordering key+ * that decides which gaps are worth a dedicated pull first.+ */+export interface SubQueryGroup {+ readonly terms: ReadonlyArray<string>;+ readonly significance: number;+}++/** The k-group generalized gap signal's verdict. `groups` is empty iff `fire` is false. */+export interface SubQueryGroupPlan {+ readonly fire: boolean;+ readonly groups: ReadonlyArray<SubQueryGroup>;+}++/** Most sub-query groups one gap-proposal round may emit. */+export const SUB_QUERY_GROUPS_MAX = 4;++/**+ * The k-group generalization of {@link planTargetedRetry} (recall-quality+ * wave): the same fire gate — measurable coverage below the completeness+ * threshold with rare significant terms still uncovered — but the gaps+ * become up to `maxGroups` follow-up sub-queries instead of one merged+ * term list. The most significant uncovered term (highest IDF, query+ * order breaking ties) earns a dedicated singleton group; any residual+ * terms merge into one final group in query order, which is exactly the+ * shape the round-two retry has always fetched. Groups are returned+ * ordered by significance, descending, so a caller that can afford fewer+ * pulls drops the tail, never the head.+ *+ * `maxGroups` below one is clamped to one (the single merged group), and+ * an unmeasurable coverage yields zero groups for the same reason+ * {@link planTargetedRetry} states above. A non-finite coverage fails+ * closed the same way (fire false, no groups): a broken measurement+ * proposes nothing. Pure and deterministic.+ */+export function planSubQueryGroups(coverage: CoverageReport, maxGroups: number): SubQueryGroupPlan {+ // Refuse a non-finite report explicitly rather than let comparison+ // semantics decide: NaN misses the `<` gate by accident, but -Infinity+ // passes it and would fire on a measurement that never happened.+ if (coverage.idfWeightedCoverage !== null && !Number.isFinite(coverage.idfWeightedCoverage)) {+ return Object.freeze({ fire: false, groups: Object.freeze([]) });+ }+ const legacy = planTargetedRetry(coverage);+ if (!legacy.fire) return Object.freeze({ fire: false, groups: Object.freeze([]) });+ const idfByTerm = new Map(coverage.terms.map((t) => [t.term, t.idf]));+ const uncovered = coverage.uncoveredRareTerms;+ const bounded = Math.max(1, Math.floor(maxGroups));+ // Query order preserved: `uncoveredRareTerms` follows the query's term+ // order, and the stable sort below only re-orders groups, never members.+ const ranked = uncovered+ .map((term, index) => ({ term, idf: idfByTerm.get(term) ?? 0, index }))+ .toSorted((a, b) => (a.idf !== b.idf ? b.idf - a.idf : a.index - b.index));+ const groups: SubQueryGroup[] =+ bounded === 1+ ? // The historical round-two shape byte-identically: ONE merged+ // group carrying every uncovered rare term in query order.+ [residualGroup(uncovered, uncovered, idfByTerm)]+ : uncovered.length <= bounded+ ? ranked.map((entry) => ({+ terms: Object.freeze([entry.term]),+ significance: entry.idf,+ }))+ : [+ ...ranked.slice(0, bounded - 1).map((entry) => ({+ terms: Object.freeze([entry.term]),+ significance: entry.idf,+ })),+ residualGroup(+ uncovered,+ ranked.slice(bounded - 1).map((entry) => entry.term),+ idfByTerm,+ ),+ ];+ groups.sort(+ (a, b) =>+ b.significance - a.significance || rankOf(a.terms[0]!, ranked) - rankOf(b.terms[0]!, ranked),+ );+ return Object.freeze({ fire: true, groups: Object.freeze(groups) });+}++/** Summed-IDF group over the residual terms, kept in query order. */+function residualGroup(+ queryOrder: ReadonlyArray<string>,+ residual: ReadonlyArray<string>,+ idfByTerm: ReadonlyMap<string, number>,+): SubQueryGroup {+ const residualSet = new Set(residual);+ const terms = queryOrder.filter((term) => residualSet.has(term));+ let significance = 0;+ for (const term of terms) significance += idfByTerm.get(term) ?? 0;+ return { terms: Object.freeze(terms), significance };+}++function rankOf(term: string, ranked: ReadonlyArray<{ term: string }>): number {+ return ranked.findIndex((entry) => entry.term === term);+}+/*** The report, and the one condition under which there is no number.*diff --git a/src/core/search/decider-step.ts b/src/core/search/decider-step.tsnew file mode 100644index 00000000..0fa6b013--- /dev/null+++ b/src/core/search/decider-step.ts@@ -0,0 +1,463 @@+/**+ * The caller-executed decider step (recall-quality wave, t_6b943fc7+ * lane A): the one model round the iterative recall loop may spend.+ *+ * The kernel never awaits a model. When the deterministic rounds stop+ * with measurable coverage gaps remaining, the loop pauses and hands the+ * caller a needs-llm-step envelope (built on the shared+ * {@link NeedsLlmStep} spine) describing the remaining gaps and the+ * candidate pool; the caller answers with a payload whose evidence+ * selection binds the answer to the round's candidate pool and whose+ * follow-up sub-queries drive the round's pulls, and the commit phase+ * validates that answer before the loop advances - the exact two-phase+ * discipline `commitExtractedSignals` established for model-authored+ * payloads: a shape assert, then registered semantic checks, then the+ * context rules the payload alone cannot carry.+ *+ * Three context rules live here rather than in the response-check+ * registry because they read per-request state the registry's+ * payload-only contract cannot see:+ * - the round token must be one minted for THIS query, round and pool:+ * either the plan's registry-backed nonce mint (the stored pause+ * digest must match the replayed state) or the deterministic+ * fallback mint ({@link makeRoundToken});+ * - the token must not have been spent already (single use - a nonce+ * token is spent by its own plan call's commit; the deterministic+ * fallback is spent per pool, the pre-nonce semantics);+ * - every selected evidence id must exist in the round's pool.+ * Each refusal is named from {@link DeciderStepError} codes, so callers+ * route on `code`, never on prose.+ *+ * An accepted commit does not write the vault: it drives one further+ * retrieval round whose pulls come only from the payload's sub-queries+ * (see `pipeline/iterative-recall.ts`). A declined or absent commit+ * finalizes the loop honestly instead of blocking it.+ */++import {+ SUB_QUERY_GROUPS_MAX,+ planSubQueryGroups,+ significantTerms,+ type CoverageReport,+} from "./coverage.ts";+import { NEEDS_LLM_STEP, buildNeedsLlmStep, type NeedsLlmStep } from "../brain/llm-step.ts";+import { assertResponseShape, type ShapeDescriptor } from "../brain/response-shape.ts";+import {+ assertResponseCheck,+ registerResponseCheck,+ semanticViolation,+ SEMANTIC_VIOLATION_CODES,+ type SemanticViolation,+} from "../brain/response-checks.ts";+import { sha256Hex } from "../integrity/digest.ts";+import { randomBytes } from "node:crypto";++/** Surface name the envelope's payload is validated under. */+export const DECIDER_STEP_SURFACE = "iterative_recall_decider";+/** Step name the answering agent is answering. */+export const DECIDER_STEP_NAME = "iterative-recall-decider";+/**+ * No artifact is written by this lane; the spine's required destination+ * names the surface the answered payload returns to, which is the only+ * target a recall round has.+ */+export const DECIDER_STEP_RESUME_TARGET = "brain_search";++/**+ * Most sub-queries one decider payload may spend pulls on: the same+ * per-round pull budget the deterministic floor obeys+ * ({@link SUB_QUERY_GROUPS_MAX}).+ */+export const DECIDER_SUB_QUERIES_MAX = SUB_QUERY_GROUPS_MAX;+/** Longest one decider sub-query may be, so one payload cannot balloon a pull. */+export const DECIDER_SUB_QUERY_LENGTH_MAX = 200;++/** Longest hex prefix of the token digest kept; a token is opaque, not secret. */+const ROUND_TOKEN_DIGEST_CHARS = 24;+/** Token prefix, so a round token is recognizable in a payload log at a glance. */+const ROUND_TOKEN_PREFIX = "drt";++/**+ * Why a decider step or its commit was refused. The set is closed:+ * callers route on these codes, and a new refusal must name itself here.+ */+export const DECIDER_STEP_ERROR_CODES = [+ /** The pool has no measurable coverage gap for a model round to close. */+ "no_gaps",+ /** The pool has no candidates to select evidence from. */+ "empty_pool",+ /** The submitted token was not minted for this query, round and pool. */+ "token_mismatch",+ /** The submitted token was already spent; a round token is single use. */+ "token_used",+ /** A selected evidence id does not exist in the round's pool. */+ "unknown_evidence",+ /** More evidence ids than the round's pool holds candidates. */+ "evidence_over_pool",+] as const;++export type DeciderStepErrorCode = (typeof DECIDER_STEP_ERROR_CODES)[number];++/**+ * A decider step was refused. Carries the closed code so a caller routes+ * on fields, never on message prose.+ */+export class DeciderStepError extends Error {+ readonly code: DeciderStepErrorCode;++ constructor(code: DeciderStepErrorCode, message: string) {+ super(message);+ this.name = "DeciderStepError";+ this.code = code;+ }+}++/**+ * The round token. Two mints exist:+ *+ * - the nonce mint ({@link nonceRoundToken} via a {@link buildDeciderStep}+ * mint hook): the plan phase draws fresh randomness, registers the+ * pause state under the token in the single-use registry+ * (`pipeline/cache-slot.ts`), and hands the nonce token out. The token+ * names THIS plan call, so a second plan for the same query mints a+ * fresh, unspent token, and "spent" means "this plan call".+ * - the deterministic mint ({@link makeRoundToken}): the digest of the+ * query, the round number and the pool. It is the fallback a plan+ * falls back to when the registry write fails (best-effort by+ * contract - the loop still works when the cache table is+ * unavailable), and it is what a commit re-derives when no registry+ * row stands behind the submitted token.+ *+ * Either way the token is opaque to callers and never secret.+ */+export function makeRoundToken(+ query: string,+ round: number,+ poolIds: ReadonlyArray<number>,+): string {+ return `${ROUND_TOKEN_PREFIX}-${round}-${pauseStateDigest(query, round, poolIds).slice(0, ROUND_TOKEN_DIGEST_CHARS)}`;+}++/**+ * The pause-state digest a plan mint registers under its nonce token: the+ * same material the deterministic token digests, kept whole. A commit+ * recomputes it over the replayed state and the registry row must agree,+ * so a replay that landed on another round or pool is refused as+ * `token_mismatch` even though the token itself was minted honestly.+ */+export function pauseStateDigest(+ query: string,+ round: number,+ poolIds: ReadonlyArray<number>,+): string {+ const material = `${query}\u0000${round}\u0000${[...poolIds].toSorted((a, b) => a - b).join(",")}`;+ return sha256Hex(material);+}++/** Hex chars of fresh randomness in a nonce round token (96 bits). */+const ROUND_TOKEN_NONCE_HEX_CHARS = 24;++/** Assemble the nonce mint: round-stamped, opaque, registry-backed. */+export function nonceRoundToken(round: number, nonceHex: string): string {+ return `${ROUND_TOKEN_PREFIX}-${round}-${nonceHex}`;+}++/** Fresh nonce hex for one plan-phase mint. */+export function randomRoundNonce(): string {+ return randomBytes(ROUND_TOKEN_NONCE_HEX_CHARS / 2).toString("hex");+}++/** The pause the loop hands its caller: the envelope plus its token. */+export interface DeciderPause {+ /** The round a committed payload will run (the loop's next number). */+ readonly round: number;+ readonly token: string;+ readonly llmStep: NeedsLlmStep;+ /** The sorted candidate chunk ids the envelope names. */+ readonly poolIds: ReadonlyArray<number>;+}++export interface DeciderStepInput {+ /** Residual query text the gaps were measured against. */+ readonly query: string;+ /** The round a committed payload will run. */+ readonly round: number;+ /** The last coverage measured over the pool. */+ readonly coverage: CoverageReport;+ /** The pool's candidate chunk ids (any order; emitted sorted). */+ readonly poolIds: ReadonlyArray<number>;+ /**+ * Plan-phase mint hook: register the pause state in the single-use+ * registry and return the nonce token to hand out, or null when the+ * registry could not take the write. Null (and the hook's absence)+ * falls back to the deterministic token, so a plan never fails because+ * the registry table is unavailable - the fallback is best-effort by+ * contract and documented at the call site that supplies the hook.+ */+ readonly mintRoundToken?: (input: {+ readonly round: number;+ readonly pauseDigest: string;+ }) => string | null;+}++/**+ * Build the needs-llm-step envelope for the remaining gaps. Refuses with+ * `no_gaps` unless the coverage is MEASURABLE and below the completeness+ * threshold with rare terms still uncovered - the same fire gate the+ * deterministic floor reads, so the model is asked exactly when a+ * gap-proposal round could pay and never on a complete or unmeasurable+ * pool - and with `empty_pool` when there are no candidates to select+ * evidence from. Pure except for the optional mint hook, whose registry+ * write is the plan phase's own business; without a hook (or when it+ * returns null) the pause carries the deterministic fallback token.+ */+export function buildDeciderStep(input: DeciderStepInput): DeciderPause {+ if (!planSubQueryGroups(input.coverage, 1).fire) {+ throw new DeciderStepError(+ "no_gaps",+ `no decider step for query ${JSON.stringify(input.query)}: coverage has no measurable gap to close`,+ );+ }+ const poolIds = [...input.poolIds].toSorted((a, b) => a - b);+ if (poolIds.length === 0) {+ throw new DeciderStepError(+ "empty_pool",+ `no decider step for query ${JSON.stringify(input.query)}: the pool has no candidates`,+ );+ }+ const gaps = input.coverage.uncoveredRareTerms;+ const pauseDigest = pauseStateDigest(input.query, input.round, poolIds);+ const minted = input.mintRoundToken?.({ round: input.round, pauseDigest }) ?? null;+ const llmStep = buildNeedsLlmStep({+ step: DECIDER_STEP_NAME,+ prompt:+ `The recall pool for query ${JSON.stringify(input.query)} still misses rare query terms ` ++ `after ${input.round - 1} deterministic retrieval round(s): ${gaps.join(", ")}. ` ++ `Bind this answer to the round's candidate pool by selecting its evidence from the ` ++ `chunk ids [${poolIds.join(",")}] and propose 1 to ${DECIDER_SUB_QUERIES_MAX} follow-up ` ++ `sub-queries, each at most ` ++ `${DECIDER_SUB_QUERY_LENGTH_MAX} characters, aimed at exactly the missed terms. ` ++ "Return the payload only; an invalid payload refuses the round.",+ schema_hints: [+ 'payload: { "evidence": [chunkId, ...], "subQueries": [subQuery, ...] }',+ `evidence: 1+ chunk ids chosen from [${poolIds.join(",")}] (binds the answer to this round's pool)`,+ `subQueries: 1 to ${DECIDER_SUB_QUERIES_MAX} strings, each at most ${DECIDER_SUB_QUERY_LENGTH_MAX} characters, unique`,+ ],+ target_path: DECIDER_STEP_RESUME_TARGET,+ });+ return Object.freeze({+ round: input.round,+ token: minted ?? makeRoundToken(input.query, input.round, poolIds),+ llmStep,+ poolIds: Object.freeze(poolIds),+ });+}++/** The payload shape: evidence ids and follow-up sub-queries, nothing else. */+const DECIDER_STEP_SHAPE: ShapeDescriptor = {+ type: "object",+ required: ["evidence", "subQueries"],+ additionalProperties: false,+ properties: {+ evidence: { type: "array", items: { type: "integer" } },+ subQueries: { type: "array", items: { type: "string", nonBlank: true } },+ },+};++/**+ * Cardinality, budget and uniqueness rules the descriptor language+ * cannot express, registered once at module scope in the shared+ * fail-closed registry: at least one piece of evidence and one+ * sub-query, at most {@link DECIDER_SUB_QUERIES_MAX} sub-queries, each+ * within {@link DECIDER_SUB_QUERY_LENGTH_MAX}, and no duplicates.+ */+registerResponseCheck(DECIDER_STEP_SURFACE, (payload) => {+ const violations: SemanticViolation[] = [];+ if (payload === null || typeof payload !== "object") return violations;+ const record = payload as { evidence?: unknown; subQueries?: unknown };+ const evidence = Array.isArray(record.evidence) ? record.evidence : null;+ const subQueries = Array.isArray(record.subQueries) ? record.subQueries : null;+ if (evidence !== null && evidence.length === 0) {+ violations.push(+ semanticViolation(+ SEMANTIC_VIOLATION_CODES.cardinality,+ "$.evidence",+ "at least one evidence id must be selected",+ ),+ );+ }+ // Duplicate evidence ids, mirroring the sub-query duplicate rule: a+ // selection that names one chunk twice pins nothing extra and reads as+ // two votes the pool cannot honor. (The evidence count itself is capped+ // at the pool size at commit time, where the pool is known - the+ // payload-only registry cannot see it.)+ evidence?.forEach((id, index) => {+ if (typeof id !== "number") return;+ const firstDuplicate = evidence.indexOf(id);+ if (firstDuplicate !== index) {+ violations.push(+ semanticViolation(+ SEMANTIC_VIOLATION_CODES.crossItem,+ `$.evidence[${index}]`,+ `duplicate evidence id; first seen at index ${firstDuplicate}`,+ ),+ );+ }+ });+ if (subQueries === null) return violations;+ if (subQueries.length === 0) {+ violations.push(+ semanticViolation(+ SEMANTIC_VIOLATION_CODES.cardinality,+ "$.subQueries",+ "at least one sub-query is required to drive the round",+ ),+ );+ }+ if (subQueries.length > DECIDER_SUB_QUERIES_MAX) {+ violations.push(+ semanticViolation(+ SEMANTIC_VIOLATION_CODES.threshold,+ "$.subQueries",+ `at most ${DECIDER_SUB_QUERIES_MAX} sub-queries per round; got ${subQueries.length}`,+ ),+ );+ }+ subQueries.forEach((subQuery, index) => {+ if (typeof subQuery !== "string") return;+ if (subQuery.length > DECIDER_SUB_QUERY_LENGTH_MAX) {+ violations.push(+ semanticViolation(+ SEMANTIC_VIOLATION_CODES.threshold,+ `$.subQueries[${index}]`,+ `sub-query must be at most ${DECIDER_SUB_QUERY_LENGTH_MAX} characters; got ${subQuery.length}`,+ ),+ );+ }+ if (significantTerms(subQuery).length === 0) {+ violations.push(+ semanticViolation(+ SEMANTIC_VIOLATION_CODES.threshold,+ `$.subQueries[${index}]`,+ "sub-query carries no significant terms, so it can never drive a retrieval pull",+ ),+ );+ }+ const firstDuplicate = subQueries.indexOf(subQuery);+ if (firstDuplicate !== index) {+ violations.push(+ semanticViolation(+ SEMANTIC_VIOLATION_CODES.crossItem,+ `$.subQueries[${index}]`,+ `duplicate sub-query; first seen at index ${firstDuplicate}`,+ ),+ );+ }+ });+ return violations;+});++export interface DeciderCommitScope {+ /** Residual query text the token was minted over. */+ readonly query: string;+ /** The round the committed payload will run. */+ readonly round: number;+ /** The pool the token was minted over (any order). */+ readonly poolIds: ReadonlyArray<number>;+ /** Round tokens already spent; a token here refuses as `token_used`. */+ readonly usedTokens: ReadonlySet<string>;+ /**+ * The pause-state digest the registry stored when the plan phase minted+ * the submitted token, read by the caller from the token's registry row.+ * Present only for a nonce mint: the commit recomputes the digest over+ * the replayed state and refuses as `token_mismatch` unless the two+ * agree, so a replay that landed on another round or pool never runs.+ * Absent (deterministic fallback token, or no registry row) the token+ * validates by re-derivation alone.+ */+ readonly mintedPauseDigest?: string;+}++/**+ * A validated decider payload: the pool binding and the sub-queries the+ * next round spends its pulls on.+ */+export interface DeciderCommit {+ /**+ * Pool-validated ids that bind the commit to THIS round's state; the+ * committed round's pulls read `subQueries` only.+ */+ readonly evidenceIds: ReadonlyArray<number>;+ /** The sub-queries the committed round pulls. */+ readonly subQueries: ReadonlyArray<string>;+ /** The spent token, echoed so the caller can record its single use. */+ readonly token: string;+}++/**+ * Validate the caller's answer. Order is the commitExtractedSignals+ * discipline - structure first, then the registered semantic rules,+ * then the context rules - and nothing is returned until every gate+ * passes, so a refused payload never advances the loop.+ */+export function commitDeciderStep(+ token: string,+ payload: unknown,+ scope: DeciderCommitScope,+): DeciderCommit {+ assertResponseShape(DECIDER_STEP_SURFACE, DECIDER_STEP_SHAPE, payload);+ assertResponseCheck(DECIDER_STEP_SURFACE, payload);++ const deterministic = makeRoundToken(scope.query, scope.round, scope.poolIds);+ if (token !== deterministic) {+ // Not the fallback mint: the token must be a nonce mint whose+ // registry row stored exactly this state's pause digest. A digest+ // mismatch means the replayed commit reached a different round or+ // pool than the plan call that handed the token out - genuine+ // divergence, refused by name.+ if (scope.mintedPauseDigest !== pauseStateDigest(scope.query, scope.round, scope.poolIds)) {+ throw new DeciderStepError(+ "token_mismatch",+ `round token was not minted for query ${JSON.stringify(scope.query)} round ${scope.round}: got ${JSON.stringify(token)}, expected a ${ROUND_TOKEN_PREFIX}-prefixed token minted for this state`,+ );+ }+ }+ if (scope.usedTokens.has(token)) {+ throw new DeciderStepError(+ "token_used",+ `round token ${JSON.stringify(token)} was already spent; a round token is single use`,+ );+ }++ const { evidence, subQueries } = payload as {+ evidence: ReadonlyArray<number>;+ subQueries: ReadonlyArray<string>;+ };+ // The evidence budget is the pool itself: a selection longer than the+ // pool of candidates it must come from cannot be honest - every extra+ // id is either a duplicate in disguise or an id that can only miss.+ // (Duplicates per se are refused by the registered payload check; the+ // pool is per-request state only the context rules can see.)+ if (evidence.length > scope.poolIds.length) {+ throw new DeciderStepError(+ "evidence_over_pool",+ `evidence selects ${evidence.length} id(s) but the round ${scope.round} pool holds ${scope.poolIds.length} candidate(s)`,+ );+ }+ const pool = new Set(scope.poolIds);+ const unknown = evidence.filter((id) => !pool.has(id));+ if (unknown.length > 0) {+ throw new DeciderStepError(+ "unknown_evidence",+ `evidence ids not in the round ${scope.round} pool: ${unknown.join(", ")}`,+ );+ }+ return Object.freeze({+ evidenceIds: Object.freeze([...evidence]),+ subQueries: Object.freeze([...subQueries]),+ token,+ });+}++/** The `needs-llm-step` status literal, re-exported for the loop's callers. */+export { NEEDS_LLM_STEP };diff --git a/src/core/search/index.ts b/src/core/search/index.tsindex 1eb3fa26..f7172064 100644--- a/src/core/search/index.ts+++ b/src/core/search/index.ts@@ -53,6 +53,7 @@ import type {ResolvedSearchConfig,VaultScopeRules,} from "./types.ts";+import { ITERATIVE_RECALL_MAX_ROUNDS_CAP, ITERATIVE_RECALL_MAX_ROUNDS_DEFAULT } from "./types.ts";type SearchConfigOverrides = Partial<Omit<ResolvedSearchConfig, "scopeRules" | "semantic" | "rerank">@@ -1326,6 +1327,27 @@ export function resolveSearchConfig(opts: {true,"search_two_pass_enabled",);+ const iterativeRecallEnabled = parseBool(+ envOrConfig(+ env,+ config,+ "OPEN_SECOND_BRAIN_SEARCH_ITERATIVE",+ "search_iterative_recall_enabled",+ ),+ false,+ "search_iterative_recall_enabled",+ );+ const iterativeRecallMaxRounds = parseInteger(+ envOrConfig(+ env,+ config,+ "OPEN_SECOND_BRAIN_SEARCH_ITERATIVE_MAX_ROUNDS",+ "search_iterative_recall_max_rounds",+ ),+ ITERATIVE_RECALL_MAX_ROUNDS_DEFAULT,+ "search_iterative_recall_max_rounds",+ { min: 1, max: ITERATIVE_RECALL_MAX_ROUNDS_CAP },+ );const poolMultiplier = parseInteger(envOrConfig(env, config, "OPEN_SECOND_BRAIN_SEARCH_POOL_MULTIPLIER", "search_pool_multiplier"),3,@@ -1434,6 +1456,8 @@ export function resolveSearchConfig(opts: {learnedWeightsEnabled,activationEnabled,twoPassEnabled,+ iterativeRecallEnabled,+ iterativeRecallMaxRounds,poolMultiplier,selfTuningEnabled,chainStopEnabled,diff --git a/src/core/search/pipeline/cache-slot.ts b/src/core/search/pipeline/cache-slot.tsindex 752e4687..e64f5242 100644--- a/src/core/search/pipeline/cache-slot.ts+++ b/src/core/search/pipeline/cache-slot.ts@@ -8,17 +8,20 @@*/import { canonicalSourceSetKey } from "../../scope-key.ts";+import { sha256Hex, canonicalJson } from "../../integrity/digest.ts";import { activationStateFingerprint } from "../activation/store.ts";import { effectiveInputWindowTokens, queryPrefixSentByProvider } from "../embeddings/presets.ts";import { learnedWeightsFingerprint } from "../feedback.ts";import { buildCacheKey, getCachedOutcome, putCachedOutcome } from "../query-cache.ts";import { reinforceFingerprint } from "../reinforce.ts";import { RERANK_SUNSET_SURVEY } from "../rerank/sunset.ts";+import { resolveIterativeMaxRounds } from "./iterative-recall.ts";import type { Store } from "../store.ts";import type { SemanticPolicy } from "../semantic-phase.ts";import type { TemporalIntent } from "../temporal-intent.ts";import type { ResolvedTimeRange } from "../time-range.ts";import type {+ IterativeStopReason,ResolvedSearchConfig,SearchOptions,SearchOutcome,@@ -28,6 +31,234 @@ import type {const MILLISECONDS_PER_SECOND = 1000;+/**+ * Cache-key suffix segments for the iterative recall round-trip+ * (recall-quality wave). Appended to the config fingerprint ONLY when+ * the iterative mode is actually on - the request flag AND the operator+ * knob - so plain rows keep their pre-wave keys byte-identical and only+ * mode-on rows (new by definition) use the extended layout. The plan+ * leg and the commit leg get distinct segments so a plan response can+ * never be served for a commit request or the reverse; the plan segment+ * also names the resolved round cap, because a plan row records the+ * round count it ran under and a raised cap must re-key, not replay.+ */+const ITERATIVE_KEY_PLAN = "itv:plan";+const ITERATIVE_KEY_COMMIT_PREFIX = "itv:commit:";+/** Hex chars of the payload digest kept in a commit key; a fingerprint, not an id. */+const ITERATIVE_PAYLOAD_DIGEST_CHARS = 16;+/**+ * Key prefix of the single-use round-token registry's mint rows (the+ * plan-phase record a commit validates against). The registry rides the+ * query-cache table BY DESIGN - one store, one generation gate - and it+ * deliberately borrows `search_cache_ttl_seconds` for its row expiry+ * even when `search_cache_enabled` is off: the knob gates the outcome+ * rows, not the table, and a token must die exactly when its plan-phase+ * outcome row dies, so the two legs can never disagree about how long a+ * plan's claim on a round survives.+ */+const ITERATIVE_TOKEN_KEY_PREFIX = "itv-token:";+/**+ * Key prefix of the claim rows: a commit's atomic single-use marker,+ * kept apart from the mint row so a failed round's release can restore+ * the retry state (the mint row - and the pause digest the retry+ * validates against - survives the release).+ */+const ITERATIVE_CLAIM_KEY_PREFIX = "itv-claim:";++/**+ * What a plan-phase mint persisted under the token's registry row: the+ * digest of the pause state (query, round, pool) the token was minted+ * over, plus the deterministic round count (and stop) the plan leg ran.+ * A commit recomputes the digest over its replayed state and refuses+ * unless the two agree, and it replays EXACTLY the recorded round count -+ * the replay's own marginal-value verdict and deadline read wall-clock+ * time and would retire rounds the plan ran, landing on a different+ * pause. `rounds`/`stopReason` are optional so a row written by a+ * just-deployed predecessor (no recording yet) still validates by digest.+ */+export interface IterativeTokenRecord {+ readonly pauseDigest: string;+ readonly rounds?: number;+ readonly stopReason?: IterativeStopReason;+}++/**+ * Whether the single-use round token has a spent claim in the query+ * cache. The registry rides the same table the outcome rows use - one+ * store, one generation gate, one TTL - so a token dies when its+ * plan-phase row dies, and a replayed commit is refused before any+ * cached commit response could be served. Only the claim row means+ * spent: a fresh mint row is a live, commitable token.+ */+export function iterativeTokenSpent(+ store: Store,+ config: ResolvedSearchConfig,+ token: string,+ nowMs: number = Date.now(),+): boolean {+ const row = store.queryCacheGet(`${ITERATIVE_CLAIM_KEY_PREFIX}${token}`);+ if (row === null) return false;+ if (row.generation !== store.corpusGeneration()) return false;+ return nowMs - row.createdAt <= config.recall.cacheTtlSeconds * MILLISECONDS_PER_SECOND;+}++/**+ * Register a plan-phase mint: file the pause digest and the recorded+ * deterministic round count under the nonce token so the commit can+ * validate its replayed state against the row and replay exactly that+ * many rounds. Insert-once - the token is fresh randomness, so a+ * conflict means a colliding mint, refused here. False (and a failed+ * write) tells the plan phase to fall back to the deterministic token:+ * the registry is best-effort, and a plan whose registry row never+ * landed hands out the self-verifying digest token instead of failing+ * the search.+ */+export function mintIterativeToken(+ store: Store,+ config: ResolvedSearchConfig,+ token: string,+ record: IterativeTokenRecord,+ nowMs: number = Date.now(),+): boolean {+ try {+ const generation = store.corpusGeneration();+ const ttlMs = config.recall.cacheTtlSeconds * MILLISECONDS_PER_SECOND;+ store.queryCacheSweep(generation, nowMs - ttlMs);+ return store.queryCachePutIfAbsent(+ `${ITERATIVE_TOKEN_KEY_PREFIX}${token}`,+ generation,+ JSON.stringify({ state: "minted", ...record }),+ nowMs,+ );+ } catch {+ // Registry persistence is best-effort; the plan falls back instead.+ return false;+ }+}++/**+ * Read what a fresh plan-phase mint stored for this token. Null when no+ * row stands behind the token - never minted, expired with its TTL, aged+ * out by a corpus generation change, or written under a payload this+ * binary cannot read - which sends the commit down the deterministic+ * re-derivation check. Best-effort by the same contract as the mint: a+ * registry read failure reads as no row.+ */+export function readIterativeTokenRecord(+ store: Store,+ config: ResolvedSearchConfig,+ token: string,+ nowMs: number = Date.now(),+): IterativeTokenRecord | null {+ try {+ const row = store.queryCacheGet(`${ITERATIVE_TOKEN_KEY_PREFIX}${token}`);+ if (row === null) return null;+ if (row.generation !== store.corpusGeneration()) return null;+ if (nowMs - row.createdAt > config.recall.cacheTtlSeconds * MILLISECONDS_PER_SECOND) {+ return null;+ }+ const parsed = JSON.parse(row.payload) as {+ state?: string;+ pauseDigest?: unknown;+ rounds?: unknown;+ stopReason?: unknown;+ };+ if (parsed.state !== "minted" || typeof parsed.pauseDigest !== "string") return null;+ return {+ pauseDigest: parsed.pauseDigest,+ ...(typeof parsed.rounds === "number" ? { rounds: parsed.rounds } : {}),+ ...(typeof parsed.stopReason === "string"+ ? { stopReason: parsed.stopReason as IterativeStopReason }+ : {}),+ };+ } catch {+ return null;+ }+}++/**+ * Claim a round token as spent in one atomic insert: the claim, not a+ * later check, arbitrates single use, so two commits racing on the same+ * token cannot both pass. The claim row is keyed apart from the mint+ * row, so a release (a commit whose round failed) restores the retry+ * state without losing the pause digest the retry revalidates against.+ * False means the token is already claimed in this generation inside+ * its TTL - the call site refuses that commit by name. The TTL is the+ * search cache's (`search_cache_ttl_seconds`), borrowed deliberately+ * even when search caching is off: the registry rides the query-cache+ * table so one generation gate and one expiry govern both legs, and a+ * claim never outlives the plan row it answers. The registry is+ * best-effort, and its two honest failure modes are: a failed write+ * costs a deterministic re-run of the same commit on replay (the+ * validator re-checks the token against the state), and the expiry+ * sliver - the claim row ages out before the commit response row - lets+ * a replay serve the live commit row without re-validation. Both are+ * bounded: the commit is retrieval-only and deterministic, never a+ * wrong answer.+ */+export function claimIterativeToken(+ store: Store,+ config: ResolvedSearchConfig,+ token: string,+ nowMs: number = Date.now(),+): boolean {+ try {+ const generation = store.corpusGeneration();+ const ttlMs = config.recall.cacheTtlSeconds * MILLISECONDS_PER_SECOND;+ store.queryCacheSweep(generation, nowMs - ttlMs);+ return store.queryCachePutIfAbsent(+ `${ITERATIVE_CLAIM_KEY_PREFIX}${token}`,+ generation,+ JSON.stringify({ state: "spent" }),+ nowMs,+ );+ } catch {+ // Registry persistence is best-effort; never fail a committed search on it.+ return true;+ }+}++/**+ * Release a claim this call made and can no longer honor: a commit whose+ * round failed keeps the retry semantics the post-execution mark had -+ * the caller may re-commit the same token (its mint row, and the pause+ * digest the retry validates against, are untouched) - while racing+ * commits stay mutually exclusive, because a release only ever removes+ * the claim row the failing call itself wrote.+ */+export function releaseIterativeToken(store: Store, token: string): void {+ try {+ store.queryCacheDelete(`${ITERATIVE_CLAIM_KEY_PREFIX}${token}`);+ } catch {+ // Release is best-effort; a stuck claim costs a fresh plan phase.+ }+}++/**+ * The suffix for one iterative mode-on request: `itv:plan:r<maxRounds>`+ * for the flag alone - the round cap is part of the key because a cached+ * plan row carries the recorded round count, so raising the cap must+ * re-key plans instead of serving one recorded under the old budget -+ * and `itv:commit:<token>:<payload digest>` for the commit leg - the+ * plan and commit phases are deterministic functions of their inputs+ * (vault, query, token, payload), so caching stays sound per leg.+ */+function iterativeCacheSuffix(config: ResolvedSearchConfig, opts: SearchOptions): string {+ if (opts.iterative !== true) return "";+ if (opts.iterativeToken === undefined) {+ return `|${ITERATIVE_KEY_PLAN}:r${resolveIterativeMaxRounds(config)}`;+ }+ const payloadDigest = sha256Hex(canonicalJson(opts.iterativePayload ?? null)).slice(+ 0,+ ITERATIVE_PAYLOAD_DIGEST_CHARS,+ );+ return `|${ITERATIVE_KEY_COMMIT_PREFIX}${opts.iterativeToken}:${payloadDigest}`;+}++function iterativeModeOn(config: ResolvedSearchConfig, opts: SearchOptions): boolean {+ return opts.iterative === true && config.recall.iterativeRecallEnabled === true;+}+/*** What a decision-model rerank passage carries. Part of the decision-model* fingerprint only, so the keys of every other rerank kind are unchanged.@@ -214,7 +445,9 @@ export function probeQueryCache(input: CacheProbeInput): CacheProbe {const key = buildCacheKey(keyOpts,planHash,- `${configFingerprint(config)}|lw:${lwFp}|act:${actFp}|tune:${tuneFp}|reinf:${reinfFp}|src:${srcSet}`,+ // The iterative fields join the suffix only when the mode is on,+ // so off-mode keys (and every pre-wave row) stay byte-identical.+ `${configFingerprint(config)}|lw:${lwFp}|act:${actFp}|tune:${tuneFp}|reinf:${reinfFp}|src:${srcSet}${iterativeModeOn(config, opts) ? iterativeCacheSuffix(config, opts) : ""}`,);const hit = getCachedOutcome(store, key, generation, ttlMs, Date.now());return { slot: { key, generation, ttlMs }, hit };diff --git a/src/core/search/pipeline/iterative-recall.ts b/src/core/search/pipeline/iterative-recall.tsnew file mode 100644index 00000000..2b024141--- /dev/null+++ b/src/core/search/pipeline/iterative-recall.ts@@ -0,0 +1,561 @@+/**+ * Bounded iterative recall loop (recall-quality wave, t_6b943fc7 lane A).+ *+ * The self-correcting second pass rescues a first pass at most once; a+ * hard multi-hop query can still leave rare query terms uncovered after+ * that retry, and nothing ever closed them. This driver generalizes the+ * retry into a bounded N-round loop over the SAME pool-merging+ * discipline: each round re-measures the pool's coverage, emits up to k+ * follow-up sub-query groups (the generalized targeted-retry planner in+ * `../coverage.ts`), pulls each group through the same scoped FTS call+ * the round-two retry uses, and merges only the NEW candidates.+ *+ * The kernel stays deterministic and model-free: every sub-query the+ * deterministic rounds pull is coverage-derived. The caller-executed+ * decider step (the one model round the card asks for) layers on top of+ * these rounds via `../decider-step.ts`: the pause envelope hands the+ * caller the surviving gaps, and the committed payload's sub-queries+ * drive the next round's pulls ({@link runDeciderRound}).+ *+ * Four bounds close the loop, in the order they are checked:+ * 1. the composite hybrid deadline (the caller's clock, already+ * bounding every other un-budgeted phase);+ * 2. the round cap (`iterativeRecallMaxRounds`);+ * 3. coverage completeness - no measurable gap, no round;+ * 4. the extracted marginal-value stop+ * (`../../brain/retrieval-plan.ts`): fed per-round candidate yields+ * and per-round elapsed time instead of the advisor's pack curve,+ * it retires a round whose yield fell below the same 0.25 floor+ * fraction (tightening as the loop slows) - adaptation, not+ * verbatim reuse, of the advisor formula. A round that recovers+ * nothing stops the loop outright: re-running identical pulls+ * against an unchanged pool cannot progress.+ *+ * When measurable gaps survive those bounds and the clock still runs,+ * the outcome PAUSES: it carries the caller-executed decider step (the+ * one model round the card asks for, built by `../decider-step.ts`)+ * as a plan-phase envelope plus an opaque single-use round token. A+ * committed payload drives exactly one further round via+ * {@link runDeciderRound} - the decider round is additive to the cap,+ * which bounds the deterministic floor, and it is the call's last+ * gap-driven round; a declined or absent commit finalizes the loop+ * honestly instead of blocking it.+ */++import { planSubQueryGroups, significantTerms, type CoverageReport } from "../coverage.ts";+import { buildDeciderStep, commitDeciderStep, type DeciderPause } from "../decider-step.ts";+// The stop predicate is a pure leaf, so the pipeline reads the exact+// advisor formula without dragging the advisor's dependency graph in.+import { marginalValueStop } from "../../brain/marginal-value-stop.ts";+import type { PropertyPushdown } from "../property-pushdown.ts";+import { poolCoverageForRetry, runSubQueryPull } from "./second-pass.ts";+import type { ValidityWindow } from "../validity.ts";+import type { KeywordHit, Store } from "../store.ts";+import type { ResolvedTimeRange } from "../time-range.ts";+import type {+ IterativeRoundRecord,+ IterativeStopReason,+ ResolvedSearchConfig,+ SearchOptions,+} from "../types.ts";+import {+ ITERATIVE_RECALL_MAX_ROUNDS_CAP,+ ITERATIVE_RECALL_MAX_ROUNDS_DEFAULT,+ SearchError,+} from "../types.ts";++// The knob bounds live on the leaf config module (see its docblock);+// re-exported here so a driver consumer reads one namespace.+export { ITERATIVE_RECALL_MAX_ROUNDS_CAP, ITERATIVE_RECALL_MAX_ROUNDS_DEFAULT } from "../types.ts";+/** Most sub-query groups one round may spend pulls on. */+export const ITERATIVE_SUB_QUERY_GROUPS_PER_ROUND = 2;++// The stop vocabulary and the per-round record live on the leaf config+// module beside the outcome marker they project into; re-exported here so+// a driver consumer reads one namespace.+export type { IterativeRoundRecord, IterativeStopReason } from "../types.ts";++export interface IterativeLoopInput {+ readonly store: Store;+ /** Residual query text (time directives already stripped). */+ readonly query: string;+ readonly limit: number;+ readonly pathPrefix: string | undefined;+ /** Same pushdown the first-pass lanes ran (recall-quality, C4). */+ readonly kind?: "page" | "section";+ readonly pushdown?: PropertyPushdown;+ readonly timeRange: ResolvedTimeRange | null;+ readonly validityWindowFor: (path: string) => ValidityWindow | null;+ readonly keywordHits: KeywordHit[];+ /** The candidate id set; each round adds to it in place. */+ readonly chunkIds: Set<number>;+ /**+ * The caller's reach rule over the loop's working set: withheld+ * candidates never enter the pool, so the round accounting, the+ * coverage gaps and the decider pause envelope are all post-reach -+ * the existence and cardinality oracle FilteredPool.preVisibility+ * exists to close. Absent (local reach): byte-identical.+ */+ readonly filterReachableIds?: (ids: ReadonlyArray<number>) => ReadonlyArray<number>;+ readonly ids: ReadonlyArray<number>;+ readonly maxRounds: number;+ /** Round number the loop's first round takes (2, or 3 after a fired second pass). */+ readonly firstRoundNumber: number;+ /** The composite deadline's expiry, shared with every other phase. */+ readonly isExpired: () => boolean;+ /** The loop's clock; injectable so the stop verdict is testable. */+ readonly nowMs?: () => number;+ /**+ * Plan-phase mint hook, handed to the decider pause when one is built+ * (see {@link buildDeciderStep}): register the pause state under a+ * nonce token and return it, or return null to fall back to the+ * deterministic token. The input carries the executed round count and+ * stop reason beside the digest, so the row is a complete replay brief+ * for the commit leg. Absent on a commit leg's replay - the replay+ * rebuilds the pause only to validate the caller's token against it,+ * and must not file a registry row for a state the caller never+ * received.+ */+ readonly mintRoundToken?: (input: {+ readonly round: number;+ readonly pauseDigest: string;+ readonly deterministicRounds: number;+ readonly stopReason: IterativeStopReason;+ }) => string | null;+ /**+ * Replay brief for the commit leg: the plan's recorded deterministic+ * round count. The loop then runs EXACTLY that many rounds and skips+ * the two wall-clock stop inputs - the composite-deadline checks and+ * the marginal-value verdict (whose latency term is elapsed time) -+ * because a slower replay would otherwise retire rounds the plan ran+ * and arrive at a different pause than the one the caller answered.+ * The deterministic sub-queries are recomputed as usual; only the+ * clock-dependent stops are silenced. Undefined on a plan leg: every+ * stop, the deadline included, is live.+ */+ readonly replayRounds?: number;+}++export interface IterativeLoopOutcome {+ readonly keywordHits: KeywordHit[];+ readonly ids: number[];+ readonly rounds: ReadonlyArray<IterativeRoundRecord>;+ readonly stopReason: IterativeStopReason;+ /**+ * The last coverage measured over the final pool: the gap list a+ * caller-facing plan phase is built from, and `null` when no coverage+ * was ever measured (an expired clock before the first check).+ */+ readonly lastCoverage: CoverageReport | null;+ /**+ * The caller-executed decider step: present exactly when measurable+ * gaps survived the deterministic budget and the clock still runs, so+ * the caller may spend ONE further round by committing a payload. A+ * committed round is additive to the cap - the cap bounds the+ * deterministic floor, the decider round is the card's one additive+ * model round per call - and it is the call's LAST gap-driven round.+ */+ readonly pause: DeciderPause | null;+}++/**+ * Run the bounded loop over the current pool. Mutates `chunkIds` exactly+ * as the round-two retry does; the returned `keywordHits` and `ids`+ * replace the caller's for the rest of the pipeline.+ */+export function runIterativeRecall(input: IterativeLoopInput): IterativeLoopOutcome {+ const now = input.nowMs ?? Date.now;+ const startMs = now();+ // The replay brief (see IterativeLoopInput.replayRounds): a replay+ // runs the recorded count and answers to no clock of its own - the+ // digest check at commit time, not the stopwatch, decides whether it+ // landed where the plan did.+ const replaying = input.replayRounds !== undefined;+ const targetRounds = replaying ? input.replayRounds! : input.maxRounds;+ // The reach rule bounds the pool BEFORE the first coverage measurement:+ // the raw candidate set can carry withheld first-pass candidates, and a+ // withheld candidate covering a rare term would close that term's gap+ // and could flip the loop to coverage_complete over a term the caller+ // can never see a candidate for. The per-round keepReachable filtering+ // below stays - defense in depth at every later addition.+ if (input.filterReachableIds) {+ const reachable = new Set(input.filterReachableIds(Array.from(input.chunkIds)));+ for (const id of Array.from(input.chunkIds)) {+ if (!reachable.has(id)) input.chunkIds.delete(id);+ }+ }+ const rounds: IterativeRoundRecord[] = [];+ const yields: number[] = [];+ const costsMs: number[] = [];+ let keywordHits = input.keywordHits;+ let stop: IterativeStopReason | null = null;+ let lastCoverage: CoverageReport | null = null;++ while (rounds.length < targetRounds) {+ if (!replaying && input.isExpired()) {+ stop = "deadline";+ break;+ }+ const coverage = poolCoverageForRetry({+ store: input.store,+ query: input.query,+ ids: Array.from(input.chunkIds),+ timeRange: input.timeRange,+ validityWindowFor: input.validityWindowFor,+ });+ lastCoverage = coverage;+ const plan = planSubQueryGroups(coverage, ITERATIVE_SUB_QUERY_GROUPS_PER_ROUND);+ if (!plan.fire) {+ // The gap signal has nothing to fire at. Where the measurement+ // exists, the completeness threshold is the verdict the whole+ // coverage engine agrees on, so the pool is complete by+ // definition; only an unmeasurable coverage (no IDF mass to take+ // a share of) is a different state, named as its own.+ stop =+ coverage.idfWeightedCoverage === null || coverage.terms.length === 0+ ? "no_sub_query"+ : "coverage_complete";+ break;+ }+ // The marginal-value stop is retrospective: it certifies the rounds+ // already run, so the loop discovers a round was not worth it by+ // doing it - the cap bounds the discovery cost, the same trade the+ // advisor makes when it cuts a curve it has already priced. Its+ // latency term is wall-clock elapsed, so a replay (which must arrive+ // at the plan's pause, not at its own watch's verdict) skips it.+ if (rounds.length > 0 && !replaying) {+ const verdict = marginalValueStop(yields, costsMs, now() - startMs);+ if (verdict.stopRank < rounds.length) {+ stop = "marginal_value";+ break;+ }+ }+ const roundStartMs = now();+ const roundNumber = input.firstRoundNumber + rounds.length;+ const terms: string[] = [];+ const recovered: KeywordHit[] = [];+ for (const group of plan.groups) {+ terms.push(...group.terms);+ const pull = runSubQueryPull(input.store, group.terms, {+ limit: input.limit,+ pathPrefix: input.pathPrefix,+ ...(input.kind !== undefined ? { kind: input.kind } : {}),+ ...(input.pushdown !== undefined ? { pushdown: input.pushdown } : {}),+ });+ for (const hit of pull.hits) {+ if (input.chunkIds.has(hit.chunkId)) continue;+ input.chunkIds.add(hit.chunkId);+ recovered.push(hit);+ }+ }+ // The reach rule decides what a round "recovered": at non-local reach+ // a withheld candidate never enters the pool, the round accounting or+ // the trail, so the counts a remote caller reads are counts of+ // candidates it could actually be shown.+ if (input.filterReachableIds) {+ const survivors = keepReachable(recovered, input.filterReachableIds, input.chunkIds);+ recovered.length = 0;+ recovered.push(...survivors);+ }+ keywordHits = keywordHits.concat(...recovered);+ const added = recovered.length;+ rounds.push(+ Object.freeze({+ round: roundNumber,+ terms: Object.freeze(terms),+ groups: plan.groups.length,+ added,+ elapsedMs: now() - roundStartMs,+ author: "deterministic" as const,+ }),+ );+ yields.push(added);+ costsMs.push(now() - roundStartMs);+ if (added === 0) {+ // The pool did not move: the next round would propose the same+ // groups against the same coverage and recover the same nothing.+ stop = "no_progress";+ break;+ }+ }++ if (stop === null) stop = "round_cap";+ // The loop's last measurement was taken at the TOP of the final round -+ // before that round's pulls landed. Every decision about the FINAL pool+ // (the reported coverage, and whether gaps survived for a decider+ // round) reads a measurement over the pool AS IT IS NOW, so a budget+ // that just closed its gaps finalizes instead of pausing on stale+ // gaps. Zero-round loops already hold the final pool's measurement; an+ // expired clock keeps the last one it took; a replay re-measures+ // whatever its own clock is doing, because the state it must reach is+ // the plan's, not its watch's.+ if (rounds.length > 0 && (replaying || (stop !== "deadline" && !input.isExpired()))) {+ lastCoverage = poolCoverageForRetry({+ store: input.store,+ query: input.query,+ ids: Array.from(input.chunkIds),+ timeRange: input.timeRange,+ validityWindowFor: input.validityWindowFor,+ });+ }+ // The decider pause: measurable gaps survived the deterministic budget,+ // the clock still runs, and the pool has candidates to select evidence+ // from. Any other exit - coverage complete, nothing measurable to fire+ // at, an expired clock - finalizes without asking the caller for a+ // model round. buildDeciderStep re-checks the same fire gate the block+ // above reads, so the two can never drift apart silently. A replay is+ // clock-blind here too: its state is the plan's by construction, and+ // the plan already decided the clock was alive when it minted.+ let pause: DeciderPause | null = null;+ const reachablePoolIds = input.filterReachableIds+ ? input.filterReachableIds(Array.from(input.chunkIds))+ : Array.from(input.chunkIds);+ if (+ stop !== "coverage_complete" &&+ stop !== "no_sub_query" &&+ stop !== "deadline" &&+ (replaying || !input.isExpired()) &&+ lastCoverage !== null &&+ input.chunkIds.size > 0 &&+ reachablePoolIds.length > 0 &&+ planSubQueryGroups(lastCoverage, 1).fire+ ) {+ pause = buildDeciderStep({+ query: input.query,+ round: input.firstRoundNumber + rounds.length,+ coverage: lastCoverage,+ poolIds: reachablePoolIds,+ ...(input.mintRoundToken !== undefined+ ? {+ mintRoundToken: (mint) =>+ input.mintRoundToken?.({+ round: input.firstRoundNumber + rounds.length,+ pauseDigest: mint.pauseDigest,+ deterministicRounds: rounds.length,+ stopReason: stop!,+ }) ?? null,+ }+ : {}),+ });+ }+ return Object.freeze({+ keywordHits,+ ids: Array.from(input.chunkIds),+ rounds: Object.freeze(rounds),+ stopReason: stop,+ lastCoverage: lastCoverage === null ? null : lastCoverage,+ pause,+ });+}++export interface DeciderRoundInput {+ readonly store: Store;+ readonly query: string;+ readonly limit: number;+ readonly pathPrefix: string | undefined;+ readonly kind?: "page" | "section";+ readonly pushdown?: PropertyPushdown;+ readonly timeRange: ResolvedTimeRange | null;+ readonly validityWindowFor: (path: string) => ValidityWindow | null;+ /** The pause the plan phase emitted. */+ readonly pause: DeciderPause;+ /** The caller's round token and payload, validated before any pull. */+ readonly token: string;+ readonly payload: unknown;+ /** Round tokens already spent, including across resumed calls. */+ readonly usedTokens: ReadonlySet<string>;+ /**+ * The pause digest the registry stored for the submitted token, read by+ * the caller from the token's mint row (see+ * {@link DeciderCommitScope.mintedPauseDigest}). Undefined when no row+ * stands behind the token.+ */+ readonly mintedPauseDigest?: string;+ readonly keywordHits: KeywordHit[];+ /** The candidate id set; the round adds to it in place. */+ readonly chunkIds: Set<number>;+ /** Same rule as the driver's {@link IterativeLoopInput.filterReachableIds}. */+ readonly filterReachableIds?: (ids: ReadonlyArray<number>) => ReadonlyArray<number>;+ readonly priorRounds: ReadonlyArray<IterativeRoundRecord>;+ /** The loop's clock; injectable so the round record is testable. */+ readonly nowMs?: () => number;+}++export interface DeciderRoundOutcome {+ readonly keywordHits: KeywordHit[];+ readonly ids: number[];+ /** The committed round's own record (author "decider"). */+ readonly round: IterativeRoundRecord;+ /** Every round of the call: the deterministic rounds plus this one. */+ readonly rounds: ReadonlyArray<IterativeRoundRecord>;+ readonly stopReason: IterativeStopReason;+ /**+ * The pool-validated evidence ids the commit pinned: carried out so the+ * caller's selection can reach the final ranking instead of being+ * validated and discarded.+ */+ readonly evidenceIds: ReadonlyArray<number>;+ /** The spent token, echoed so the caller records its single use. */+ readonly token: string;+}++/**+ * Execute the committed decider round: validate the payload (shape,+ * registered semantic rules, token single use, evidence in the pool) and+ * run exactly the pulls its sub-queries name, merging only new+ * candidates into the pool. The pool grows by nothing else - no+ * coverage re-proposal runs here; the caller's sub-queries ARE the+ * round. A refused payload throws before any pull, so a bad commit+ * never advances the loop.+ */+/**+ * Keep only the hits whose chunk the reach rule shows the caller, and+ * evict the rest from the pool set they were already added to.+ */+function keepReachable(+ recovered: KeywordHit[],+ filterReachableIds: (ids: ReadonlyArray<number>) => ReadonlyArray<number>,+ chunkIds: Set<number>,+): KeywordHit[] {+ const survivors = new Set(filterReachableIds(recovered.map((hit) => hit.chunkId)));+ for (const hit of recovered) {+ if (!survivors.has(hit.chunkId)) chunkIds.delete(hit.chunkId);+ }+ return recovered.filter((hit) => survivors.has(hit.chunkId));+}++export function runDeciderRound(input: DeciderRoundInput): DeciderRoundOutcome {+ const now = input.nowMs ?? Date.now;+ const commit = commitDeciderStep(input.token, input.payload, {+ query: input.query,+ round: input.pause.round,+ poolIds: input.pause.poolIds,+ usedTokens: input.usedTokens,+ ...(input.mintedPauseDigest !== undefined+ ? { mintedPauseDigest: input.mintedPauseDigest }+ : {}),+ });+ const roundStartMs = now();+ const recovered: KeywordHit[] = [];+ for (const subQuery of commit.subQueries) {+ const pull = runSubQueryPull(input.store, significantTerms(subQuery), {+ limit: input.limit,+ pathPrefix: input.pathPrefix,+ ...(input.kind !== undefined ? { kind: input.kind } : {}),+ ...(input.pushdown !== undefined ? { pushdown: input.pushdown } : {}),+ });+ for (const hit of pull.hits) {+ if (input.chunkIds.has(hit.chunkId)) continue;+ input.chunkIds.add(hit.chunkId);+ recovered.push(hit);+ }+ }+ if (input.filterReachableIds) {+ const survivors = keepReachable(recovered, input.filterReachableIds, input.chunkIds);+ recovered.length = 0;+ recovered.push(...survivors);+ }+ const round: IterativeRoundRecord = Object.freeze({+ round: input.pause.round,+ terms: Object.freeze([] as string[]),+ groups: 0,+ added: recovered.length,+ elapsedMs: now() - roundStartMs,+ author: "decider" as const,+ subQueries: commit.subQueries,+ });+ return Object.freeze({+ keywordHits: input.keywordHits.concat(...recovered),+ ids: Array.from(input.chunkIds),+ round,+ rounds: Object.freeze([...input.priorRounds, round]),+ stopReason: "decider_round" as const,+ evidenceIds: commit.evidenceIds,+ token: commit.token,+ });+}++/**+ * The operator's resolved round cap: the configured value or the default,+ * clamped to the cap. The one resolution every consumer shares -+ * `resolveIterativeRequest` runs the loop under it, and the plan-leg cache+ * key suffix names it (`itv:plan:r<N>`), so raising the cap re-keys cached+ * plans instead of serving one recorded under the old round count.+ */+export function resolveIterativeMaxRounds(config: ResolvedSearchConfig): number {+ const maxRounds = config.recall.iterativeRecallMaxRounds ?? ITERATIVE_RECALL_MAX_ROUNDS_DEFAULT;+ return Math.min(maxRounds, ITERATIVE_RECALL_MAX_ROUNDS_CAP);+}++/**+ * Which leg of the round-trip this request is: the flag alone asks for+ * the plan phase (deterministic rounds, then pause with an envelope when+ * gaps survive); the token plus payload asks for the commit phase+ * (validate, then run the committed round).+ */+export type IterativePhase = "plan" | "commit";++/**+ * Resolve the caller's iterative request fields. The request flag is the+ * per-query opt-in; the resolved knob is the operator's master switch, so+ * a flag without the knob is inert (byte-identical), not an error. Any+ * stray iterative-only field without the flag is a named refusal rather+ * than a silently ignored argument, and so is a half-specified commit+ * (a token without its payload, a payload without a token, or a+ * blank token) - a request the caller thinks is one thing but the+ * kernel would execute as another is exactly the silent fallback this+ * pipeline refuses to guess at.+ */+export function resolveIterativeRequest(+ opts: Pick<SearchOptions, "iterative" | "iterativeToken" | "iterativePayload">,+ config: ResolvedSearchConfig,+): { readonly maxRounds: number; readonly phase: IterativePhase } | null {+ const tokenGiven = opts.iterativeToken !== undefined;+ const payloadGiven = opts.iterativePayload !== undefined;+ if (opts.iterative !== true) {+ if (tokenGiven || payloadGiven) {+ throw new SearchError(+ "INVALID_INPUT",+ "iterativeToken/iterativePayload require iterative: true; a commit without the flag is refused rather than ignored",+ );+ }+ return null;+ }+ if (tokenGiven !== payloadGiven) {+ throw new SearchError(+ "INVALID_INPUT",+ tokenGiven+ ? "iterativeToken requires iterativePayload: a commit is token plus payload"+ : "iterativePayload requires iterativeToken: a commit is token plus payload",+ );+ }+ if (tokenGiven && (typeof opts.iterativeToken !== "string" || opts.iterativeToken.length === 0)) {+ throw new SearchError("INVALID_INPUT", "iterativeToken must be a non-empty string");+ }+ if (config.recall.iterativeRecallEnabled !== true) {+ // The knob alone being inert is the designed master-switch: a flagged+ // plan call runs nothing. A fully-formed commit is different - every+ // field of a commit is present, so silently running it as a plain+ // search would drop its marker and spend nothing it named; it is+ // refused by name instead, so the caller learns the loop is off+ // rather than reading a plain answer as its commit's outcome.+ if (tokenGiven) {+ throw new SearchError(+ "INVALID_INPUT",+ "iterative commit refused: the iterative recall loop is disabled by operator config",+ );+ }+ return null;+ }+ const maxRounds = resolveIterativeMaxRounds(config);+ if (!Number.isInteger(maxRounds) || maxRounds < 1) {+ throw new SearchError(+ "INVALID_INPUT",+ `iterativeRecallMaxRounds must be an integer >= 1, got ${String(maxRounds)}`,+ );+ }+ return {+ maxRounds,+ phase: tokenGiven ? "commit" : "plan",+ };+}diff --git a/src/core/search/pipeline/outcome.ts b/src/core/search/pipeline/outcome.tsindex 516dc3b0..6c452715 100644--- a/src/core/search/pipeline/outcome.ts+++ b/src/core/search/pipeline/outcome.ts@@ -50,6 +50,7 @@ import type {ResolvedSearchConfig,SearchOptions,SearchOutcome,+ SearchOutcomeIterative,} from "../types.ts";const NO_RESULTS: ReadonlyArray<BrainSearchResult> = Object.freeze([]);@@ -94,6 +95,12 @@ export interface EmptyOutcomeInput {* where the probe is skipped.*/readonly corpus: RetrievalCorpusStatement | null;+ /**+ * The iterative recall marker (recall-quality wave), projected verbatim+ * onto the outcome when the opt-in mode ran. Absent - the mode off, or+ * an inert loop - keeps the outcome byte-identical.+ */+ readonly iterative?: SearchOutcomeIterative;}/** The zero-candidate outcome: no pool to rank, filter or attribute. */@@ -127,6 +134,7 @@ export function emptyOutcome(input: EmptyOutcomeInput): SearchOutcome {...(evidencePack !== undefined ? { evidencePack } : {}),...(input.routedSurface === "summary" ? { surface: input.routedSurface } : {}),...(retrievalTrail !== undefined ? { retrievalTrail } : {}),+ ...(input.iterative !== undefined ? { iterative: input.iterative } : {}),});}@@ -184,6 +192,12 @@ export interface OutcomeInput {* byte-identical to the pre-change shape.*/readonly relationalReach?: ReadonlyMap<number, RelationalReach>;+ /**+ * The iterative recall marker (recall-quality wave), projected verbatim+ * onto the outcome when the opt-in mode ran. Absent - the mode off, or+ * an inert loop - keeps the outcome byte-identical to the pre-wave one.+ */+ readonly iterative?: SearchOutcomeIterative;}export function buildSearchOutcome(input: OutcomeInput): SearchOutcome {@@ -265,6 +279,10 @@ export function buildSearchOutcome(input: OutcomeInput): SearchOutcome {...(input.routedSurface === "summary" ? { surface: input.routedSurface } : {}),...input.trustReceipts,...(input.decisionModel !== undefined ? { decisionModel: input.decisionModel } : {}),+ // The iterative marker is a sibling of `secondPass` (recall-quality+ // wave): absent whenever the mode did nothing, so every no-marker+ // outcome serializes exactly as before.+ ...(input.iterative !== undefined ? { iterative: input.iterative } : {}),};// Progressive disclosure (D3): layer 1. When the caller opts intodiff --git a/src/core/search/pipeline/second-pass.ts b/src/core/search/pipeline/second-pass.tsindex 498d95f8..558f63c1 100644--- a/src/core/search/pipeline/second-pass.ts+++ b/src/core/search/pipeline/second-pass.ts@@ -4,6 +4,13 @@* query - a zero-candidate pool gets a broadened OR retry (t_ef92dfdc),* a partially-covered pool gets a targeted retry on the specifically* uncovered rare terms (t_8eb5ca32). Both are deterministic and LLM-free.+ *+ * The gap-proposal half of the targeted retry is shared with the+ * iterative recall loop's rounds 3..N: the coverage over the surviving+ * pool ({@link poolCoverageForRetry}) and the FTS pull that turns one+ * group of terms into candidate hits ({@link runSubQueryPull}) are the+ * one gap-signal path both callers read, so the retry and the loop can+ * never disagree about where the gaps are or how a pull is scoped.*/import {@@ -14,6 +21,7 @@ import {import { coverageOverChunks } from "../evidence-verification.ts";import type { PropertyPushdown } from "../property-pushdown.ts";import { runFtsQueryDetailed } from "../fts.ts";+import type { SafeKeywordOutcome } from "../fts-safety.ts";import { semanticPoolSize } from "../semantic-phase.ts";import { eventTimeInRange, type ValidityWindow } from "../validity.ts";import type { KeywordHit, Store } from "../store.ts";@@ -70,6 +78,60 @@ export function runSecondPassRecall(input: SecondPassInput): SecondPassOutcome {return runTargetedRetry(input);}+/**+ * Coverage over the pool that will actually survive ranking: for a+ * time-scoped query, out-of-range candidates are excluded first, so a+ * rare term is not marked "covered" only because an out-of-range chunk+ * matched it (which would wrongly suppress a retry while the final+ * in-range result set still misses that term). Shared by the round-two+ * targeted retry and the iterative loop's rounds.+ */+export function poolCoverageForRetry(input: {+ readonly store: Store;+ readonly query: string;+ readonly ids: ReadonlyArray<number>;+ readonly timeRange: ResolvedTimeRange | null;+ readonly validityWindowFor: (path: string) => ValidityWindow | null;+}) {+ let coverageIds = input.ids;+ const timeRange = input.timeRange;+ if (timeRange !== null) {+ const hydratedForCoverage = input.store.hydrateChunks(input.ids);+ coverageIds = input.ids.filter((chunkId) => {+ const chunk = hydratedForCoverage.get(chunkId);+ if (chunk === undefined) return false;+ return eventTimeInRange(input.validityWindowFor(chunk.path), chunk.mtime, timeRange);+ });+ }+ return coverageOverChunks(input.store, input.query, coverageIds);+}++/**+ * One follow-up pull: fetch the candidates a group of gap terms recovers,+ * scoped exactly like a first-pass lane (pool width, path prefix, chunk+ * kind, property pushdown). The first term is the FTS base and the rest+ * OR onto it, which is the merge discipline the round-two retry+ * established. Shared by the targeted retry and the iterative loop.+ */+export function runSubQueryPull(+ store: Store,+ terms: ReadonlyArray<string>,+ scope: {+ readonly limit: number;+ readonly pathPrefix: string | undefined;+ readonly kind?: "page" | "section";+ readonly pushdown?: PropertyPushdown;+ },+): SafeKeywordOutcome {+ return runFtsQueryDetailed(store, terms[0]!, {+ expandedTerms: terms.slice(1),+ limit: semanticPoolSize(scope.limit),+ pathPrefix: scope.pathPrefix ?? null,+ ...(scope.kind !== undefined ? { kind: scope.kind } : {}),+ ...(scope.pushdown !== undefined ? { pushdown: scope.pushdown } : {}),+ });+}+/*** A zero-candidate first pass in evidence-pack mode means the implicit-AND* keyword match was too strict - the classic abstention dead end. Instead@@ -120,28 +182,19 @@ function runBroadenedRetry(input: SecondPassInput): SecondPassOutcome {* left uncovered after the retry.*/function runTargetedRetry(input: SecondPassInput): SecondPassOutcome {- const { store, query, limit, pathPrefix, timeRange, chunkIds, ids } = input;- // Judge coverage over the pool that will actually survive ranking:- // for a time-scoped query, exclude out-of-range candidates first, so- // a rare term is not marked "covered" only because an out-of-range- // chunk matched it (which would wrongly suppress the retry while the- // final in-range result set still misses that term).- let coverageIds = ids;- if (timeRange !== null) {- const hydratedForCoverage = store.hydrateChunks(ids);- coverageIds = ids.filter((chunkId) => {- const chunk = hydratedForCoverage.get(chunkId);- if (chunk === undefined) return false;- return eventTimeInRange(input.validityWindowFor(chunk.path), chunk.mtime, timeRange);- });- }- const poolCoverage = coverageOverChunks(store, query, coverageIds);+ const { store, limit, pathPrefix, timeRange, chunkIds, ids } = input;+ const poolCoverage = poolCoverageForRetry({+ store,+ query: input.query,+ ids,+ timeRange,+ validityWindowFor: input.validityWindowFor,+ });const retryPlan = planTargetedRetry(poolCoverage);if (!retryPlan.fire) return noSecondPass(input);- const targeted = runFtsQueryDetailed(store, retryPlan.terms[0]!, {- expandedTerms: retryPlan.terms.slice(1),- limit: semanticPoolSize(limit),- pathPrefix: pathPrefix ?? null,+ const targeted = runSubQueryPull(store, retryPlan.terms, {+ limit,+ pathPrefix,...(input.kind !== undefined ? { kind: input.kind } : {}),...(input.pushdown !== undefined ? { pushdown: input.pushdown } : {}),});diff --git a/src/core/search/search.ts b/src/core/search/search.tsindex 063a551d..65ccb622 100644--- a/src/core/search/search.ts+++ b/src/core/search/search.ts@@ -14,7 +14,16 @@import { assembleRankedResults } from "./pipeline/assemble.ts";import { decorateFinalResults } from "./pipeline/attribution.ts";-import { isCacheEligible, persistCachedOutcome, probeQueryCache } from "./pipeline/cache-slot.ts";+import {+ isCacheEligible,+ iterativeTokenSpent,+ mintIterativeToken,+ readIterativeTokenRecord,+ claimIterativeToken,+ releaseIterativeToken,+ persistCachedOutcome,+ probeQueryCache,+} from "./pipeline/cache-slot.ts";import { collectCandidateSignals } from "./pipeline/candidate-signals.ts";import { createEventTimeResolver, filterCandidatesInRange } from "./pipeline/event-time.ts";import { runKeywordLane } from "./pipeline/keyword-lane.ts";@@ -33,6 +42,14 @@ import {runRelationalArm,} from "./pipeline/relational-arm.ts";import { resolveSearchRequest } from "./pipeline/request.ts";+import {+ resolveIterativeRequest,+ runDeciderRound,+ runIterativeRecall,+} from "./pipeline/iterative-recall.ts";+import { DeciderStepError, nonceRoundToken, randomRoundNonce } from "./decider-step.ts";+import { ResponseCheckError } from "../brain/response-checks.ts";+import { ResponseShapeError } from "../brain/response-shape.ts";import { resolveKindFilter } from "./property-pushdown.ts";import { noSecondPass, runSecondPassRecall } from "./pipeline/second-pass.ts";import { runSemanticLane, type SemanticLaneOutcome } from "./pipeline/semantic-lane.ts";@@ -45,14 +62,48 @@ import type { RetrievalDegradationSink } from "./retrieval-trail.ts";import { RETRIEVAL_DEGRADATION, noteDegradation } from "./retrieval-trail.ts";import { indexAgeSeconds, maybeFreshenIndex } from "./freshen.ts";import { LAST_INDEXED_AT_STATE_KEY } from "./store/state.ts";-import type { FrontmatterCache } from "./result-filters.ts";+import { isPathReadableAtReach, type FrontmatterCache } from "./result-filters.ts";import { Store } from "./store.ts";-import type { ResolvedSearchConfig, SearchOptions, SearchOutcome } from "./types.ts";+import { SearchError } from "./types.ts";+import type { BrainSearchResult } from "./search-result.ts";+import type {+ IterativeStopReason,+ ResolvedSearchConfig,+ SearchOptions,+ SearchOutcome,+ SearchOutcomeIterative,+} from "./types.ts";export { SEARCH_LIMIT_MAX, SEARCH_LIMIT_MIN } from "./pipeline/request.ts";const CACHE_BYPASSED: CacheProbe = { slot: null, hit: null };+/**+ * The committed decider evidence's preference over the final window+ * (recall-quality wave, M3): the ranked prefix keeps its head, and the+ * pinned ids that ranked OUTSIDE the `limit` window displace the window's+ * tail - so a core-evidence chunk the ranking would have dropped still+ * reaches the answer, while every pinned id that never survived ranking+ * (a gate exclusion, a reach withdrawal) is silently not pinned: the+ * preference only ever promotes candidates the ranked pool actually+ * holds, in ranked order. Deterministic, and a no-op whenever the ranked+ * pool already covers the evidence.+ */+function pinCommittedEvidence(+ ranked: ReadonlyArray<BrainSearchResult>,+ limit: number,+ evidenceIds: ReadonlyArray<number>,+): ReadonlyArray<BrainSearchResult> {+ const window = ranked.slice(0, limit);+ if (evidenceIds.length === 0 || window.length === 0) return window;+ const inWindow = new Set(window.map((row) => row.chunkId));+ const pinned = new Set(evidenceIds);+ const missing = ranked.filter((row) => pinned.has(row.chunkId) && !inWindow.has(row.chunkId));+ if (missing.length === 0) return window;+ const keep = Math.max(0, limit - missing.length);+ return [...window.slice(0, keep), ...missing].slice(0, limit);+}+/** Lead of the warning that names an abandoned lane's late, non-abort failure. */const ABANDONED_LANE_FAILURE_PREFIX = "hybrid deadline: an abandoned lane failed after the answer:";@@ -293,6 +344,22 @@ export async function search(// the generic-surface response byte-identical to today.const routedSurface = shape.basePlan.surface;+ // Iterative recall request resolution (recall-quality wave): hoisted+ // ABOVE the cache probe because a commit call must refuse an+ // already-spent round token before any cached commit response could+ // be served - the refusal is the single-use contract, and a warm row+ // must not bypass it.+ const iterativeRequest = resolveIterativeRequest(opts, effectiveConfig);+ if (+ iterativeRequest?.phase === "commit" &&+ iterativeTokenSpent(store, effectiveConfig, opts.iterativeToken!, nowMs)+ ) {+ throw new SearchError(+ "INVALID_INPUT",+ `iterative commit refused (token_used): round token ${JSON.stringify(opts.iterativeToken)} was already spent; a round token is single use`,+ );+ }+// Persistent query cache (v0.20.0): opt-in. A hit returns the// previously computed outcome; generation changes (embedding change or// content reindex) and TTL expiry invalidate it. The write-back is@@ -309,7 +376,23 @@ export async function search(planHash: shape.basePlan.planHash,}): CACHE_BYPASSED;- if (cache.hit !== null) return served(cache.hit);+ if (cache.hit !== null) {+ // A cached PLAN row carries the round token its plan call minted.+ // When that token was already spent by a commit, the row is stale+ // for purpose - serving it would hand the caller a dead token and+ // lock the retry out until the TTL - so the hit is discarded and+ // the plan recomputes (and mints fresh). Every other hit serves as+ // usual; a commit row never carries a token, and the entry refusal+ // above already arbitrates replays.+ const cachedMarker = cache.hit.iterative;+ const cachedToken = cachedMarker?.phase === "needs-llm-step" ? cachedMarker.token : undefined;+ if (+ cachedToken === undefined ||+ !iterativeTokenSpent(store, effectiveConfig, cachedToken, nowMs)+ ) {+ return served(cache.hit);+ }+ }// A deadline-degraded answer is keyword-only under a key that promises// the hybrid one: serve it, but never cache it. A spend-gated one is// the same, and the key carries no gate or price either, so a cached@@ -453,7 +536,229 @@ export async function search(: noSecondPass({ keywordHits, ids: Array.from(allChunkIds) });keywordHits = retry.keywordHits;for (const w of retry.warnings) warnings.push(w);- const idsList = retry.ids;+ let idsList = retry.ids;++ // Bounded iterative recall (recall-quality wave): with the caller's+ // per-query flag and the operator's knob both on, gap-proposal rounds+ // run past the single second pass over the same pool-merging+ // discipline, bounded by the round cap and the composite deadline the+ // second pass itself answers to. The loop is deterministic and+ // model-free; the caller-executed decider round rides this seam too+ // (decider-step.ts). Flag absent, or knob off, this block is never+ // entered and the pipeline is byte-identical.+ const reachFilterFor = (reach: NonNullable<typeof opts.transportReach>) => {+ return (ids: ReadonlyArray<number>): ReadonlyArray<number> => {+ const hydrated = store.hydrateChunks(ids);+ const indexed = store.indexedVisibilityByPaths([...hydrated.values()].map((c) => c.path));+ return ids.filter((id) => {+ const chunk = hydrated.get(id);+ return (+ chunk !== undefined &&+ isPathReadableAtReach(+ effectiveConfig.vault,+ chunk.path,+ reach,+ frontmatterCache,+ indexed.get(chunk.path),+ )+ );+ });+ };+ };+ let iterativeMarker: SearchOutcomeIterative | null = null;+ // The committed decider evidence (recall-quality wave, M3): carried+ // out of the commit so the final window can prefer it and the marker+ // can name it. Empty on every other leg.+ let committedEvidenceIds: ReadonlyArray<number> = [];+ if (+ iterativeRequest !== null &&+ iterativeRequest.phase === "commit" &&+ deadlineExpired(deadline)+ ) {+ // A commit whose clock died before the block is refused by name,+ // exactly like a commit against moved state: silence here would+ // spend nothing it named and return a plain answer the caller+ // would read as its commit's outcome.+ throw new SearchError(+ "INVALID_INPUT",+ "iterative commit refused: no decider round is pending for this query state; run the plan phase again",+ );+ }+ if (iterativeRequest !== null && !deadlineExpired(deadline)) {+ // The plan phase mints the round token through the registry: a+ // nonce token registered with the pause state's digest, so "spent"+ // means "this plan call" and a second plan for the same query+ // mints a fresh token instead of handing out the already-claimed+ // one. When the registry cannot take the write, the mint reports+ // null and the pause falls back to the deterministic digest token+ // - best-effort by contract, so the loop still works with the+ // cache table unavailable (the fallback validates by re-derivation+ // at commit time instead). The commit leg's replay never mints: it+ // rebuilds the pause only to validate the caller's token against.+ const mintRoundToken =+ iterativeRequest.phase === "plan"+ ? ({+ round,+ pauseDigest,+ deterministicRounds,+ stopReason,+ }: {+ readonly round: number;+ readonly pauseDigest: string;+ readonly deterministicRounds: number;+ readonly stopReason: IterativeStopReason;+ }): string | null => {+ const token = nonceRoundToken(round, randomRoundNonce());+ // The row is the commit leg's replay brief: the digest to+ // validate the replayed state against, and the deterministic+ // round count the replay must run regardless of its own+ // clock.+ return mintIterativeToken(+ store,+ effectiveConfig,+ token,+ { pauseDigest, rounds: deterministicRounds, stopReason },+ nowMs,+ )+ ? token+ : null;+ }+ : undefined;+ // The commit leg reads the plan's mint row before the replay: the+ // digest for the validator, and the recorded round count the replay+ // must run. Null (deterministic fallback token, or a row that aged+ // out) downgrades to re-derivation and the live-clock replay.+ const tokenRecord =+ iterativeRequest.phase === "commit"+ ? readIterativeTokenRecord(store, effectiveConfig, opts.iterativeToken!, nowMs)+ : null;+ const loop = runIterativeRecall({+ store,+ query,+ limit,+ pathPrefix,+ ...(kind !== undefined ? { kind } : {}),+ ...(pushdown !== null ? { pushdown } : {}),+ timeRange,+ validityWindowFor: eventTime.validityWindowFor,+ keywordHits,+ chunkIds: allChunkIds,+ ids: idsList,+ maxRounds: iterativeRequest.maxRounds,+ firstRoundNumber: retry.secondPass !== undefined ? 3 : 2,+ isExpired: () => deadlineExpired(deadline),+ ...(mintRoundToken !== undefined ? { mintRoundToken } : {}),+ ...(tokenRecord?.rounds !== undefined ? { replayRounds: tokenRecord.rounds } : {}),+ ...(opts.transportReach !== undefined && opts.transportReach !== "local"+ ? { filterReachableIds: reachFilterFor(opts.transportReach) }+ : {}),+ });+ keywordHits = loop.keywordHits;+ idsList = loop.ids;+ if (iterativeRequest.phase === "commit") {+ // The pause digest the plan's mint stored for this token: the+ // validator compares it against the replayed state's digest, so+ // a commit whose replay landed on another round or pool is+ // refused as token_mismatch even though the token itself was+ // minted honestly. Undefined (deterministic fallback token, or a+ // row that aged out) downgrades to re-derivation alone.+ const mintedPauseDigest = tokenRecord?.pauseDigest;+ // The deterministic replay reached a state with no pending round+ // (the index moved under the caller between the two calls): the+ // commit is refused rather than executed against a pool its+ // token never named.+ if (loop.pause === null) {+ throw new SearchError(+ "INVALID_INPUT",+ "iterative commit refused: no decider round is pending for this query state; run the plan phase again",+ );+ }+ // The claim, not the entry check, arbitrates single use: two+ // commits racing the same token both pass the entry read, and+ // one atomic insert lets exactly one of them run the round.+ let claimed = false;+ try {+ if (!claimIterativeToken(store, effectiveConfig, opts.iterativeToken!, nowMs)) {+ throw new SearchError(+ "INVALID_INPUT",+ `iterative commit refused (token_used): round token ${JSON.stringify(opts.iterativeToken)} was already claimed; a round token is single use`,+ );+ }+ claimed = true;+ // One call commits at most once, so the in-call spent set the+ // validator sees stays empty; cross-call single use is the+ // claim above.+ const committed = runDeciderRound({+ store,+ query,+ limit,+ pathPrefix,+ ...(kind !== undefined ? { kind } : {}),+ ...(pushdown !== null ? { pushdown } : {}),+ timeRange,+ validityWindowFor: eventTime.validityWindowFor,+ keywordHits,+ chunkIds: allChunkIds,+ pause: loop.pause,+ token: opts.iterativeToken!,+ payload: opts.iterativePayload,+ usedTokens: new Set<string>(),+ ...(mintedPauseDigest !== undefined ? { mintedPauseDigest } : {}),+ priorRounds: loop.rounds,+ ...(opts.transportReach !== undefined && opts.transportReach !== "local"+ ? { filterReachableIds: reachFilterFor(opts.transportReach) }+ : {}),+ });+ keywordHits = committed.keywordHits;+ idsList = committed.ids;+ committedEvidenceIds = committed.evidenceIds;+ iterativeMarker = {+ phase: "final",+ rounds: committed.rounds,+ stopReason: committed.stopReason,+ evidenceIds: committed.evidenceIds,+ };+ } catch (e) {+ if (claimed) releaseIterativeToken(store, opts.iterativeToken!);+ if (e instanceof DeciderStepError) {+ throw new SearchError(+ "INVALID_INPUT",+ `iterative commit refused (${e.code}): ${e.message}`,+ );+ }+ // A payload the validators refused (shape, or a registered+ // semantic rule) is the caller's mistake, named by the same+ // INVALID_INPUT the decider refusals carry: left raw it would+ // escape classification and surface over MCP as an internal+ // error instead of invalid_params. The refusal happens before+ // any pull, so nothing about the round moved.+ if (e instanceof ResponseShapeError || e instanceof ResponseCheckError) {+ throw new SearchError("INVALID_INPUT", `iterative commit refused: ${e.message}`);+ }+ throw e;+ }+ } else if (loop.pause !== null) {+ iterativeMarker = {+ phase: "needs-llm-step",+ round: loop.pause.round,+ token: loop.pause.token,+ llmStep: loop.pause.llmStep,+ poolIds: loop.pause.poolIds,+ gaps: loop.lastCoverage?.uncoveredRareTerms ?? [],+ rounds: loop.rounds,+ stopReason: loop.stopReason,+ };+ } else if (loop.rounds.length > 0) {+ // The loop ran and finalized within the deterministic budget: the+ // per-round accounting rides the outcome, while an inert loop+ // (zero rounds) adds nothing and stays byte-identical.+ iterativeMarker = {+ phase: "final",+ rounds: loop.rounds,+ stopReason: loop.stopReason,+ };+ }+ }if (idsList.length === 0) {// Nothing to rank, so this answer owes an explanation: the lanes@@ -464,20 +769,18 @@ export async function search(degraded,opts.transportReach,);- return served(- finalize(- emptyOutcome({- store,- opts,- query,- pathPrefix,- warnings,- routedSurface,- degraded,- corpus,- }),- ),- );+ const outcome = emptyOutcome({+ store,+ opts,+ query,+ pathPrefix,+ warnings,+ routedSurface,+ degraded,+ corpus,+ ...(iterativeMarker !== null ? { iterative: iterativeMarker } : {}),+ });+ return served(finalize(outcome));}// Two-tier hydration (recall-quality, C5): the pool hydrates@@ -573,7 +876,7 @@ export async function search(const results = decorateFinalResults({store,- results: postRank.results.slice(0, limit),+ results: pinCommittedEvidence(postRank.results, limit, committedEvidenceIds),structured: shape.structured,activeLearned,canonicalMatchByChunk: signals.canonicalMatchByChunk,@@ -603,33 +906,34 @@ export async function search();const emit =postRank.decisionFallback === true || rerankUnavailable ? (o: SearchOutcome) => o : finalize;- return served(- emit(- buildSearchOutcome({- store,- config: effectiveConfig,- opts,- query,- pathPrefix,- results,- warnings,- secondPass: retry.secondPass,- routedSurface,- trustReceipts: postRank.trustReceipts,- frontmatterCache,- poolSize,- degraded,- corpus,- // The arm's reach-gated paths ride into the outcome builder so- // the retrieval trail renders them; empty (arm off) projects to- // no trail entry at all.- ...(relational.reachByChunk.size > 0 ? { relationalReach: relational.reachByChunk } : {}),- ...(postRank.decisionModel?.answerable !== undefined- ? { decisionModel: { answerable: postRank.decisionModel.answerable } }- : {}),- }),- ),- );+ const built = buildSearchOutcome({+ store,+ config: effectiveConfig,+ opts,+ query,+ pathPrefix,+ results,+ warnings,+ secondPass: retry.secondPass,+ routedSurface,+ trustReceipts: postRank.trustReceipts,+ frontmatterCache,+ poolSize,+ degraded,+ corpus,+ // The arm's reach-gated paths ride into the outcome builder so+ // the retrieval trail renders them; empty (arm off) projects to+ // no trail entry at all.+ ...(relational.reachByChunk.size > 0 ? { relationalReach: relational.reachByChunk } : {}),+ ...(postRank.decisionModel?.answerable !== undefined+ ? { decisionModel: { answerable: postRank.decisionModel.answerable } }+ : {}),+ // The iterative marker is a property of this request's phase, not+ // of the ranking; the builder projects it verbatim, so every+ // no-marker outcome serializes exactly as before.+ ...(iterativeMarker !== null ? { iterative: iterativeMarker } : {}),+ });+ return served(emit(built));} finally {await store.close();}diff --git a/src/core/search/store.ts b/src/core/search/store.tsindex 774b9c6f..afdb5c00 100644--- a/src/core/search/store.ts+++ b/src/core/search/store.ts@@ -340,6 +340,21 @@ export class Store {queryCache.queryCachePut(this.db, key, generation, payload, createdAtMs);}+ /** Insert-only put: false when the key already held a row. */+ queryCachePutIfAbsent(+ key: string,+ generation: string,+ payload: string,+ createdAtMs: number,+ ): boolean {+ return queryCache.queryCachePutIfAbsent(this.db, key, generation, payload, createdAtMs);+ }++ /** Delete one query-cache row by key; idempotent. */+ queryCacheDelete(key: string): void {+ queryCache.queryCacheDelete(this.db, key);+ }+/** Delete rows from a stale generation or created before the cutoff. */queryCacheSweep(currentGeneration: string, expiredBeforeMs: number): void {queryCache.queryCacheSweep(this.db, currentGeneration, expiredBeforeMs);diff --git a/src/core/search/store/query-cache-table.ts b/src/core/search/store/query-cache-table.tsindex db6c0bc7..1e74d192 100644--- a/src/core/search/store/query-cache-table.ts+++ b/src/core/search/store/query-cache-table.ts@@ -42,6 +42,33 @@ export function queryCachePut();}+/**+ * Insert-only put: false when the key already holds a row. This is the+ * one write a single-use registry needs - the claim, not a later check,+ * arbitrates the use, because a plain put would let a racing second+ * writer overwrite the first writer's marker.+ */+export function queryCachePutIfAbsent(+ db: Database,+ key: string,+ generation: string,+ payload: string,+ createdAtMs: number,+): boolean {+ return (+ db.run(+ "INSERT INTO query_cache(cache_key, generation, payload, created_at) VALUES (?, ?, ?, ?) " ++ "ON CONFLICT(cache_key) DO NOTHING",+ [key, generation, payload, createdAtMs],+ ).changes > 0+ );+}++/** Delete one row by key; idempotent. */+export function queryCacheDelete(db: Database, key: string): void {+ db.run("DELETE FROM query_cache WHERE cache_key = ?", [key]);+}+/** Delete rows from a stale generation or created before the cutoff. */export function queryCacheSweep(db: Database,diff --git a/src/core/search/surfacing-gate.ts b/src/core/search/surfacing-gate.tsindex 3f896c5e..126467ea 100644--- a/src/core/search/surfacing-gate.ts+++ b/src/core/search/surfacing-gate.ts@@ -1,3 +1,11 @@+import { RECALL_CHANNEL, type RecallChannel } from "../brain/recall-telemetry.ts";+import {+ assertMeasuredQuality,+ computeSurfacingKey,+ SURFACING_TIER,+ type SurfacingTier,+} from "./surfacing-key.ts";+export type SurfacingGateReason =| "explicit"| "duplicate"@@ -10,6 +18,22 @@ export interface SurfacingGateInput {readonly prompt: string;readonly previousPrompt?: string | null;readonly explicit?: boolean;+ /**+ * The transport asking, as {@link RecallChannel}. The STRUCTURAL+ * decision above is channel-independent by construction and never reads+ * this; only {@link evaluateGradedSurfacing} reads it, to calibrate the+ * measured admission. Absent means the gate's own production channel.+ */+ readonly channel?: RecallChannel;+ /**+ * The retrieval's absolute match quality (`RecallResultSet.idfWeightedCoverage`+ * or the adequacy pair's `match_quality`), when a measurement exists.+ * Only {@link evaluateGradedSurfacing} reads this: the structural gate+ * fails open on prompt structure alone and never sees retrieval state.+ * Absent = no measurement was offered; `null` = a measured report that+ * nothing was measurable.+ */+ readonly matchQuality?: number | null;}export interface SurfacingGateDecision {@@ -17,6 +41,22 @@ export interface SurfacingGateDecision {readonly reason: SurfacingGateReason;}+/** The gate's production channel, assumed when a caller sends none. */+export const SURFACING_GATE_DEFAULT_CHANNEL = RECALL_CHANNEL.mcp;++/**+ * The graded decision: the structural verdict composed with the shared+ * admission key (`surfacing-key.ts`), one shape `{ key, tier, admit,+ * reason }` for every consumer. `reason` is the gate's own vocabulary on+ * the structural outcomes and the tier vocabulary on the measured ones.+ */+export interface GradedSurfacingDecision {+ readonly key: number | null;+ readonly tier: SurfacingTier;+ readonly admit: boolean;+ readonly reason: SurfacingGateReason | SurfacingTier;+}+const SHELL_COMMANDS = new Set(["awk","bun",@@ -96,3 +136,57 @@ export function evaluateSurfacingGate(input: SurfacingGateInput): SurfacingGateD}return Object.freeze({ retrieve: true, reason: "default_retrieve" });}++/**+ * The graded projection: the structural short-circuits first, then the+ * shared channel-calibrated admission key over the measured quality.+ *+ * Tiering: an explicit request admits (`explicit`); a structural+ * suppression refuses (`suppressed`, structural reason preserved) and is+ * never ranked, so its key stays null; otherwise the measured quality+ * decides (`admitted` | `below_floor` | `unmeasurable_quality`). With no+ * measurement offered at all, the structural projection's fail-open+ * stands and `reason` records `default_retrieve` so a default admission+ * is never mistaken for a measured one. The binary+ * {@link SurfacingGateDecision} projects out of this shape: `admit` is+ * `retrieve`, `reason` is the same field.+ */+export function evaluateGradedSurfacing(input: SurfacingGateInput): GradedSurfacingDecision {+ const structural = evaluateSurfacingGate(input);+ if (structural.reason === "explicit") {+ // Both "no measurement offered" and "measured, nothing was+ // measurable" grade as null keys on the default branch; the explicit+ // branch treats them the same instead of handing a legitimate null+ // report to the validator as a shape violation.+ const key =+ input.matchQuality === undefined || input.matchQuality === null+ ? null+ : assertMeasuredQuality(input.matchQuality);+ return Object.freeze({+ key,+ tier: SURFACING_TIER.explicit,+ admit: true,+ reason: "explicit",+ });+ }+ if (structural.reason !== "default_retrieve") {+ return Object.freeze({+ key: null,+ tier: SURFACING_TIER.suppressed,+ admit: false,+ reason: structural.reason,+ });+ }+ if (input.matchQuality === undefined) {+ return Object.freeze({+ key: null,+ tier: SURFACING_TIER.admitted,+ admit: true,+ reason: "default_retrieve",+ });+ }+ return computeSurfacingKey({+ matchQuality: input.matchQuality,+ channel: input.channel ?? SURFACING_GATE_DEFAULT_CHANNEL,+ });+}diff --git a/src/core/search/surfacing-key.ts b/src/core/search/surfacing-key.tsnew file mode 100644index 00000000..e417904d--- /dev/null+++ b/src/core/search/surfacing-key.ts@@ -0,0 +1,196 @@+/**+ * The shared graded surfacing key (t_107a3249, lane C).+ *+ * ONE pure calculator computes recall admission for every channel from a+ * retrieval result plus a transport, so the hook's `decideRecallInject`+ * and the `brain_recall_gate` diagnostics grade identically instead of+ * drifting into two competing signals.+ *+ * The KEY is absolute match quality - the share of the prompt's IDF mass+ * the retrieved material actually covers (`SearchOutcome.idfWeightedCoverage`).+ * It is the only quantity here with a threshold contract, and the same+ * quantity `recall-adequacy.ts` grades. A result score can NOT take this+ * role: the keyword lane min-max normalizes within the candidate set, so+ * whenever that lane is non-empty the top row sits at or above the+ * configured keyword weight no matter how well it matched - the defect+ * documented in `recall-adequacy.ts` and in the floor's docblock in+ * `recall-inject.ts`. The fused composite stays an ORDERING signal in+ * `rankResults`; it is never read here.+ *+ * The CHANNEL is the transport (`RECALL_CHANNEL`: mcp, cli, hook),+ * because every telemetry record already carries it and the replay bench+ * can therefore reproduce it; anything finer belongs in metadata. The+ * per-channel admission floors are exported module constants, not config+ * knobs, this wave. All three sit at `RECALL_INJECT_CONFIDENCE_FLOOR`+ * (0.35) - the one bound with shipped measured behaviour - and the replay+ * suite (`src/core/bench/replay.ts`) is the instrument that re-measures+ * them: if a measured calibration disagrees with 0.35 before release,+ * the measurement wins and this docblock records it.+ *+ * Structural truths (empty prompt, verbatim repeat, slash command, shell+ * command) are channel-INDEPENDENT and never enter this calculator; they+ * stay named short-circuits in `evaluateSurfacingGate`, which projects+ * this key's `{ key, tier, admit, reason }` shape alongside its own+ * binary decision.+ */++import type { RecallChannel } from "../brain/recall-telemetry.ts";++/**+ * The graded tier vocabulary, weakest to strongest admission.+ *+ * `explicit` and `suppressed` are the gate's structural outcomes (an+ * explicit recall request; a named short-circuit). `admitted`,+ * `below_floor` and `unmeasurable_quality` are this calculator's+ * measured outcomes, and the latter two are members of the decision+ * core's `RecallAbstainReason` vocabulary verbatim, so a tier boundary+ * surfaces the SAME reason on every channel.+ */+export const SURFACING_TIER = Object.freeze({+ explicit: "explicit",+ suppressed: "suppressed",+ admitted: "admitted",+ belowFloor: "below_floor",+ unmeasurable: "unmeasurable_quality",+} as const);++/** Closed union over {@link SURFACING_TIER}. */+export type SurfacingTier = (typeof SURFACING_TIER)[keyof typeof SURFACING_TIER];++/** Membership list; every surface renders its enum from this array. */+export const SURFACING_TIERS: ReadonlyArray<SurfacingTier> = Object.freeze([+ SURFACING_TIER.explicit,+ SURFACING_TIER.suppressed,+ SURFACING_TIER.admitted,+ SURFACING_TIER.belowFloor,+ SURFACING_TIER.unmeasurable,+]);++/** Narrow a value read back off disk or across a tool boundary. */+export function isSurfacingTier(value: unknown): value is SurfacingTier {+ return typeof value === "string" && (SURFACING_TIERS as ReadonlyArray<string>).includes(value);+}++/**+ * Per-channel admission floors over absolute match quality, in [0,1].+ *+ * The hook member is pinned by test to equal+ * `RECALL_INJECT_CONFIDENCE_FLOOR` - the hook's floor is DERIVED from+ * this constant (single source of truth), keeping the exported name and+ * value its callers already pin. The mcp/cli diagnostic channels default+ * to the same floor this wave; the replay suite is what re-measures that+ * default (see the module docblock).+ */+export const SURFACING_ADMISSION_FLOORS: Readonly<Record<RecallChannel, number>> = Object.freeze({+ mcp: 0.35,+ cli: 0.35,+ hook: 0.35,+});++/** Typed error for a measurable quality or floor that violates its own contract. */+export class SurfacingKeyError extends Error {+ constructor(message: string) {+ super(message);+ this.name = "SurfacingKeyError";+ }+}++/** Input to the shared admission calculator. */+export interface SurfacingKeyInput {+ /**+ * Absolute match quality in [0,1] - `RecallResultSet.idfWeightedCoverage`+ * or `recall_adequacy`'s `match_quality`. `null` when the retrieval had+ * no IDF mass to weigh (a word-free prompt or an empty corpus); that is+ * a REPORT, and it grades as `unmeasurable_quality`.+ */+ readonly matchQuality: number | null;+ readonly channel: RecallChannel;+ /**+ * Overrides the channel's constant. The hook's configurable+ * `confidenceFloor` rides here; absent, the channel constant applies.+ */+ readonly floor?: number;+}++/**+ * One admission verdict as the graded shape `{ key, tier, admit, reason }`.+ *+ * `key` is the measured quality (null only where nothing was measurable);+ * `tier` and `reason` carry the same closed-vocabulary member on the+ * measured outcomes, with `reason` kept as its own field so structural+ * projections can put a gate reason in the same slot; `admit` is the+ * decision itself. At-boundary quality admits: the decision core has+ * always abstained strictly below the floor, and that boundary is pinned.+ */+export type SurfacingKeyDecision =+ | {+ readonly key: number;+ readonly tier: typeof SURFACING_TIER.admitted;+ readonly admit: true;+ readonly reason: typeof SURFACING_TIER.admitted;+ }+ | {+ readonly key: number;+ readonly tier: typeof SURFACING_TIER.belowFloor;+ readonly admit: false;+ readonly reason: typeof SURFACING_TIER.belowFloor;+ }+ | {+ readonly key: null;+ readonly tier: typeof SURFACING_TIER.unmeasurable;+ readonly admit: false;+ readonly reason: typeof SURFACING_TIER.unmeasurable;+ };++/**+ * Compute the graded admission for one retrieval result on one channel.+ *+ * Throws {@link SurfacingKeyError} - by name, never a silent fallback -+ * when a reported quality or floor is not a finite number in [0,1]: a+ * retriever that reports `NaN` where the contract says `null` is broken,+ * and admitting on it is how a broken bound hides.+ */+export function computeSurfacingKey(input: SurfacingKeyInput): SurfacingKeyDecision {+ const floor = input.floor ?? SURFACING_ADMISSION_FLOORS[input.channel];+ assertUnitInterval(floor, "floor");+ if (input.matchQuality === null) {+ return Object.freeze({+ key: null,+ tier: SURFACING_TIER.unmeasurable,+ admit: false,+ reason: SURFACING_TIER.unmeasurable,+ });+ }+ assertUnitInterval(input.matchQuality, "matchQuality");+ if (input.matchQuality < floor) {+ return Object.freeze({+ key: input.matchQuality,+ tier: SURFACING_TIER.belowFloor,+ admit: false,+ reason: SURFACING_TIER.belowFloor,+ });+ }+ return Object.freeze({+ key: input.matchQuality,+ tier: SURFACING_TIER.admitted,+ admit: true,+ reason: SURFACING_TIER.admitted,+ });+}++function assertUnitInterval(value: number, name: string): void {+ if (!Number.isFinite(value) || value < 0 || value > 1) {+ throw new SurfacingKeyError(`${name} must be a finite number in [0,1]; got ${value}`);+ }+}++/**+ * Validate one measured quality for callers that admit without grading+ * (an explicit request carries its measurement but never thresholds on+ * it). Shared so the explicit path and the calculator refuse the same+ * broken numbers with the same named error.+ */+export function assertMeasuredQuality(key: number): number {+ assertUnitInterval(key, "matchQuality");+ return key;+}diff --git a/src/core/search/types.ts b/src/core/search/types.tsindex 2b102bc5..23f7d6c0 100644--- a/src/core/search/types.ts+++ b/src/core/search/types.ts@@ -20,6 +20,7 @@ import type { DegradationNotice } from "../integrity/degradation.ts";import type { StampMismatch } from "../integrity/stamp.ts";import type { ReconciliationOutcome, ReconciliationReport } from "../reconciliation-report.ts";import type { VaultPathRule, VaultScopeRules } from "../vault-scope/defaults.ts";+import type { NeedsLlmStep } from "../brain/llm-step.ts";import type { MaintenanceSpendReceipt } from "../brain/maintenance/journal.ts";import type { EmbeddingPriceOverride, EmbeddingPriceSource } from "./embeddings/pricing.ts";import type { DegreePredicate } from "./property-filter.ts";@@ -46,6 +47,20 @@ export {type SearchErrorOptions,} from "./search-error.ts";+/**+ * Gap-driven rounds the iterative recall loop (recall-quality wave) may+ * run when the config names no cap, and the hard ceiling the resolver+ * clamps an explicit cap to. These live on this module - the leaf every+ * config consumer already reads - rather than beside the loop driver, so+ * `resolveSearchConfig` never imports a pipeline module: the resolver is+ * loaded by nearly every entry point, and dragging the driver's brain+ * graph behind it flipped a fragile module-init order (the load failure+ * this move fixed is recorded in the wave report).+ */+export const ITERATIVE_RECALL_MAX_ROUNDS_DEFAULT = 2;+/** Hard ceiling the config resolver clamps the round cap to. */+export const ITERATIVE_RECALL_MAX_ROUNDS_CAP = 8;+/*** Structural query intent (v0.20.0). Derived purely from query shape -* quoted phrases, FTS wildcards, wikilinks, entity-token share, token@@ -1004,6 +1019,31 @@ export interface SearchOptions {readonly focusSession?: string;/** Opt-in verified evidence pack diagnostics. Omitted preserves the legacy search outcome shape. */readonly evidencePack?: boolean;+ /**+ * Opt-in iterative recall loop (recall-quality wave). When true AND the+ * operator's `iterativeRecallEnabled` knob is on, gap-driven rounds run+ * after the (single) second pass, bounded by the round cap and the+ * composite deadline. Absent or false leaves the pipeline byte-identical;+ * with the knob off the flag is inert rather than an error - the knob is+ * the operator's master switch, the flag the caller's per-query one.+ */+ readonly iterative?: boolean;+ /**+ * The round token a plan-phase response minted, submitted on the+ * commit call of the iterative round-trip (recall-quality wave).+ * Present only with `iterative: true`; a token without the flag, or a+ * token without its payload, is a named refusal rather than a+ * silently ignored argument.+ */+ readonly iterativeToken?: string;+ /**+ * The caller-executed decider payload ({@link ./decider-step.ts}+ * shape: selected evidence ids plus follow-up sub-queries), submitted+ * beside {@link SearchOptions.iterativeToken} on the commit call. The+ * commit validates it - shape, registered semantic rules, token single+ * use, evidence in the round's pool - before any pull runs.+ */+ readonly iterativePayload?: unknown;/*** Access recording (Time-Aware Recall & Activation Suite). When true,* the surfaced result paths are recorded as one activation access@@ -1087,6 +1127,87 @@ export interface SearchOptions {readonly skipDecisionModelRerank?: boolean;}+/**+ * Why the iterative recall loop stopped; recorded per query on the+ * outcome's iterative marker (recall-quality wave). Lives on this leaf+ * beside the marker it projects into, for the same module-graph reason+ * as the knob bounds above.+ */+export type IterativeStopReason =+ | "coverage_complete"+ | "no_sub_query"+ | "no_progress"+ | "round_cap"+ | "marginal_value"+ | "deadline"+ | "decider_round";++/**+ * One executed gap-driven round: what it pulled, what it recovered,+ * what it cost. Deterministic-floor rounds carry the coverage-derived+ * terms; decider rounds carry their committed sub-queries instead.+ */+export interface IterativeRoundRecord {+ /** 1-based round number; 1 is the initial lanes, so rounds start at 2. */+ readonly round: number;+ readonly terms: ReadonlyArray<string>;+ readonly groups: number;+ readonly added: number;+ readonly elapsedMs: number;+ /** Who authored the sub-queries: the deterministic floor, or the decider. */+ readonly author: "deterministic" | "decider";+ /** The decider-authored sub-queries, present on decider rounds only. */+ readonly subQueries?: ReadonlyArray<string>;+}++/**+ * The iterative recall round-trip's phase marker (recall-quality wave),+ * present on an outcome ONLY under the opt-in mode - the plan phase that+ * pauses for the caller's decider step, or a call whose loop ran at+ * least one gap-driven round. A call that never enters the mode, and a+ * mode-on call the loop finalized within zero rounds, carry no marker at+ * all, so the serialized outcome is byte-identical whenever the mode did+ * nothing.+ */+export type SearchOutcomeIterative = SearchOutcomeIterativePlan | SearchOutcomeIterativeFinal;++/** The plan phase: measurable gaps survived the deterministic budget. */+export interface SearchOutcomeIterativePlan {+ readonly phase: "needs-llm-step";+ /** The round a committed payload will run. */+ readonly round: number;+ /** The opaque single-use token the commit call must echo. */+ readonly token: string;+ /** The needs-llm-step envelope describing what to answer. */+ readonly llmStep: NeedsLlmStep;+ /** The candidate chunk ids the decider selects evidence from. */+ readonly poolIds: ReadonlyArray<number>;+ /** The uncovered rare terms the committed sub-queries aim at. */+ readonly gaps: ReadonlyArray<string>;+ /** Every gap-driven round the loop already ran. */+ readonly rounds: ReadonlyArray<IterativeRoundRecord>;+ /** Why the deterministic budget stopped while gaps remain. */+ readonly stopReason: IterativeStopReason;+}++/** A call whose loop ran: the committed round-trip leg, or a plain final. */+export interface SearchOutcomeIterativeFinal {+ readonly phase: "final";+ /** Every gap-driven round the loop ran, in execution order. */+ readonly rounds: ReadonlyArray<IterativeRoundRecord>;+ /** Why the loop stopped. */+ readonly stopReason: IterativeStopReason;+ /**+ * The pool-validated evidence ids the caller's committed decider+ * payload pinned as core evidence, present on the committed leg only.+ * The final window gives them a deterministic preference (a committed+ * id that would rank outside the `limit` still lands in the results),+ * so the decider's selection reaches the answer instead of being+ * validated and discarded.+ */+ readonly evidenceIds?: ReadonlyArray<number>;+}+export interface SearchOutcome {readonly results: ReadonlyArray<BrainSearchResult>;readonly warnings: ReadonlyArray<string>;@@ -1181,6 +1302,15 @@ export interface SearchOutcome {/** The uncovered rare terms re-queried by a `"targeted"` retry. */readonly targetedTerms?: ReadonlyArray<string>;};+ /**+ * Iterative recall round-trip marker (recall-quality wave). Present+ * only in the opt-in mode: the plan phase when the loop paused with+ * measurable gaps, the final marker on a call whose loop ran - the+ * committed round-trip leg, or a plain finalize (see+ * {@link SearchOutcomeIterativeFinal}). Absent - never null - otherwise,+ * keeping the outcome byte-identical whenever the mode did nothing.+ */+ readonly iterative?: SearchOutcomeIterative;/*** Normalized-confidence chain-stop (t_23c1b929). Present only when* `searchAcrossVaults` ran with `chainStopEnabled` and a completed origin's@@ -1519,6 +1649,25 @@ export interface ResolvedRecallConfig {* (non-evidence-pack) searches never retry either way.*/readonly twoPassEnabled: boolean;+ /**+ * Bounded iterative recall loop (recall-quality wave). Off by default.+ * When true, gap-proposal rounds may run past the single second pass:+ * each round re-measures pool coverage, emits up to k follow-up+ * sub-query groups (the generalized targeted-retry planner) and merges+ * the recovered candidates, until coverage completes, a round stops+ * paying (the extracted marginal-value stop), the round cap or the+ * composite deadline is reached, or a round recovers nothing. Off keeps+ * the pipeline byte-identical; the documented "at most one retry"+ * contract of `twoPassEnabled` is untouched - the loop owns the rounds+ * AFTER it.+ */+ readonly iterativeRecallEnabled?: boolean;+ /**+ * Round cap for the iterative recall loop: the number of gap-driven+ * rounds it may run per query, regardless of remaining coverage gaps.+ * Absent reads as {@link ITERATIVE_RECALL_MAX_ROUNDS_DEFAULT}.+ */+ readonly iterativeRecallMaxRounds?: number;/*** Keyword candidate-pool width as a multiple of the requested limit* (link-recall-intelligence, t_ae973491). Default 3 preserves thediff --git a/src/mcp/brain/recall-tools.ts b/src/mcp/brain/recall-tools.tsindex 032949f9..4c5d25b3 100644--- a/src/mcp/brain/recall-tools.ts+++ b/src/mcp/brain/recall-tools.ts@@ -66,10 +66,14 @@ import {resolveTokenImpactLedgerEnabled,} from "../../core/config.ts";import {+ coverageSessionRecall,describeSessionRecall,expandSessionRecall,searchSessionRecall,+ SessionCoverageEntityUnknownError,+ SessionCoverageInfeasibleError,} from "../../core/brain/session-recall.ts";+import { MINED_KEY_MAX_LENGTH } from "../../core/brain/link-graph/session-mining.ts";import { resolveTimeBounds } from "./time-bounds.ts";import { aggregateQueryDemand, serializeQueryDemandReport } from "../../core/brain/query-demand.ts";import { buildRetrievalPlan, serializeRetrievalPlan } from "../../core/brain/retrieval-plan.ts";@@ -943,6 +947,28 @@ async function toolBrainSessionGrep(ctx: ServerContext,args: Record<string, unknown>,): Promise<Record<string, unknown>> {+ // Coverage-first selection (t_2c2a883c) rides this tool as an explicit+ // operation; omitted (the default) is the historical grep, byte-identical.+ const operation = args["operation"] ?? "match";+ if (operation === "coverage") return toolBrainSessionGrepCoverage(ctx, args);+ if (operation !== "match") {+ // The dispatch contract (surface-error-codes census): every tool whose+ // schema declares a dispatch enum answers an unknown value with the+ // shared `unknown_operation` code, message unchanged.+ throw unknownOperationError("brain_session_grep: operation must be 'match' or 'coverage'");+ }+ if (args["char_budget"] !== undefined) {+ throw new MCPError(+ INVALID_PARAMS,+ "brain_session_grep: char_budget is not applicable to operation 'match'; it sizes the coverage selection",+ );+ }+ if (args["entity_key"] !== undefined) {+ throw new MCPError(+ INVALID_PARAMS,+ "brain_session_grep: entity_key is not applicable to operation 'match'; it seeds the coverage fan-out",+ );+ }const limit = coercePositiveInteger("brain_session_grep", "limit", args["limit"]);const snippetChars = coercePositiveInteger("brain_session_grep",@@ -984,6 +1010,81 @@ async function toolBrainSessionGrep(};}+/**+ * The coverage operation of `brain_session_grep` (t_2c2a883c): the+ * coverage-first thread selection over the lineage-scoped record set,+ * fanning out under the adaptive topic budget and the caller's+ * `char_budget`, returning the selected turns chronologically beside the+ * selection diagnostics. The typed floor-violation infeasibility maps to+ * INVALID_PARAMS - a budget that cannot hold the floor-weighted+ * selection is a caller error, named so it can be retried, never a+ * silent truncation.+ */+function toolBrainSessionGrepCoverage(+ ctx: ServerContext,+ args: Record<string, unknown>,+): Record<string, unknown> {+ if (args["query"] !== undefined) {+ throw new MCPError(+ INVALID_PARAMS,+ "brain_session_grep: operation 'coverage' selects whole topics; it takes no `query`",+ );+ }+ for (const inapplicable of [+ "since",+ "before",+ "limit",+ "snippet_chars",+ "include_raw",+ "raw_budget_chars",+ ] as const) {+ if (args[inapplicable] !== undefined) {+ throw new MCPError(+ INVALID_PARAMS,+ `brain_session_grep: ${inapplicable} is not applicable to operation 'coverage'; it sizes or filters the match operation`,+ );+ }+ }+ const charBudget = coercePositiveInteger(+ "brain_session_grep",+ "char_budget",+ args["char_budget"],+ );+ if (charBudget === undefined) {+ throw new MCPError(+ INVALID_PARAMS,+ "brain_session_grep: char_budget is required for the coverage operation",+ );+ }+ const sessionId = optionalStringArg("brain_session_grep", args, "session_id");+ // The miner's own cap: mined keys run to MINED_KEY_MAX_LENGTH, so a+ // 129-200 character URL or path key must be able to seed coverage here.+ const entityKey = optionalStringArg(+ "brain_session_grep",+ args,+ "entity_key",+ MINED_KEY_MAX_LENGTH,+ );+ let result;+ try {+ result = coverageSessionRecall(ctx.vault, {+ ...withheldAtRemoteReach(ctx),+ ...(sessionId !== undefined ? { sessionId } : {}),+ ...(entityKey !== undefined ? { entityKey } : {}),+ charBudget,+ });+ } catch (err) {+ if (err instanceof SessionCoverageInfeasibleError) {+ throw new MCPError(INVALID_PARAMS, err.message);+ }+ if (err instanceof SessionCoverageEntityUnknownError) {+ throw new MCPError(INVALID_PARAMS, err.message);+ }+ throw err;+ }+ return { ...result };+}+/*** Private continuity rows are session data a remote caller does not get:* the recall tools answer about them exactly as about a row that does not@@ -1001,6 +1102,7 @@ async function toolBrainSessionDescribe(...describeSessionRecall(ctx.vault, {sessionId: requiredStringArg("brain_session_describe", args, "session_id"),...withheldAtRemoteReach(ctx),+ ...(args["topics"] === true ? { topics: true } : {}),}),};}@@ -1507,24 +1609,41 @@ export const RECALL_TOOLS: ReadonlyArray<ToolDefinition> = Object.freeze([name: "brain_session_grep",previewBudget: MCP_PREVIEW_BUDGET,description:- "Search imported session recall raw turns and summary nodes, optionally bounded to a time window (since/before).",+ "Search imported session recall raw turns and summary nodes, bounded by an optional time window (since/before). With operation=coverage, runs the coverage-first thread selection instead: facets fanned out under the topic budget, selected under char_budget, returned chronologically with diagnostics.",inputSchema: {type: "object",properties: {- query: { type: "string", description: "Search text." },+ operation: {+ type: "string",+ enum: ["match", "coverage"],+ description:+ "match (default) greps records for `query` (required here). coverage: `query` absent, `char_budget` required, `entity_key` optionally seeds the fan-out.",+ },+ query: { type: "string", description: "Search text (operation=match)." },session_id: {type: "string",description: "Optional session id filter.",},+ char_budget: {+ type: "integer",+ minimum: 1,+ description:+ "With operation=coverage: total character budget for the selected evidence. A budget that cannot hold the selection is refused, naming the required chars.",+ },+ entity_key: {+ type: "string",+ description:+ "With operation=coverage: seed the fan-out from sessions whose mined records mention this entity. An entity no record mentions is refused by name.",+ },limit: {type: "integer",minimum: 1,- description: "Maximum hits to return.",+ description: "Maximum hits to return (operation=match).",},snippet_chars: {type: "integer",minimum: 1,- description: "Maximum chars per hit snippet.",+ description: "Maximum chars per hit snippet (operation=match).",},since: {type: "string",@@ -1548,18 +1667,23 @@ export const RECALL_TOOLS: ReadonlyArray<ToolDefinition> = Object.freeze(["With include_raw, clip each inlined raw payload to this many chars; protected identity keys always survive.",},},- required: ["query"],additionalProperties: false,},handler: toolBrainSessionGrep,},{name: "brain_session_describe",- description: "Describe counts and summary depths for an imported session recall DAG.",+ description:+ "Describe counts and summary depths for an imported session recall DAG. With topics, also render the adaptive topic-budget report the coverage operation fans out under.",inputSchema: {type: "object",properties: {session_id: { type: "string", description: "Session id to describe." },+ topics: {+ type: "boolean",+ description:+ "Include the coverage topic report: detected facets, the adaptive topic budget (floor 12, cap 16) and the realized topics. Omitted: byte-identical response.",+ },},required: ["session_id"],additionalProperties: false,diff --git a/src/mcp/brain/shared.ts b/src/mcp/brain/shared.tsindex 433f50f2..2586d387 100644--- a/src/mcp/brain/shared.ts+++ b/src/mcp/brain/shared.ts@@ -253,13 +253,18 @@ export function optionalStringArg(tool: string,args: Record<string, unknown>,key: string,+ maxLength?: number,): string | undefined {const raw = args[key];if (raw === undefined || raw === null) return undefined;if (typeof raw !== "string" || raw.trim().length === 0) {throw new MCPError(INVALID_PARAMS, `${tool}: ${key} must be a non-empty string`);}- return raw.trim();+ const value = raw.trim();+ if (maxLength !== undefined && value.length > maxLength) {+ throw new MCPError(INVALID_PARAMS, `${tool}: ${key} must be at most ${maxLength} characters`);+ }+ return value;}export function requiredStringArg(diff --git a/src/mcp/search-tools.ts b/src/mcp/search-tools.tsindex 864199c3..0a05e4f0 100644--- a/src/mcp/search-tools.ts+++ b/src/mcp/search-tools.ts@@ -23,6 +23,8 @@ import {serializeSearchCard,serializeIndexStatus,} from "../core/search/index.ts";+import { evaluateGradedSurfacing } from "../core/search/surfacing-gate.ts";+import { SURFACING_TIERS } from "../core/search/surfacing-key.ts";import { normalizeSessionFocus, parseStructuredRecallQueryDocument } from "../core/search/index.ts";import type { BrainSearchResult, SearchOutcome } from "../core/search/index.ts";import { parseDegreePredicate, type DegreePredicate } from "../core/search/property-filter.ts";@@ -329,6 +331,22 @@ const SEARCH_INPUT_SCHEMA: Record<string, unknown> = {description:"Optional project-scope filter; pages with no project always match, project-tagged pages only this project. Absent = no project filtering.",},+ iterative: {+ type: "boolean",+ description:+ "Opt in to the bounded iterative recall loop (default off). Surviving gaps pause with a plan; resume via iterative_payload. Inert unless the knob is on.",+ },+ iterative_token: {+ type: "string",+ maxLength: 128,+ description:+ "The round token from a plan-phase response, submitted beside iterative_payload. Requires iterative: true; single use - a replayed token is refused by name.",+ },+ iterative_payload: {+ type: "object",+ description:+ "Decider payload answering a plan-phase envelope: { evidence: [chunkId, ...], subQueries: [...] }, validated before any pull runs. Requires iterative_token.",+ },},required: ["query"],additionalProperties: false,@@ -477,6 +495,24 @@ const SEARCH_OUTPUT_SCHEMA: NonNullable<ToolDefinition["outputSchema"]> = {},},warnings: { type: "array", items: { type: "string" } },+ // Iterative recall round-trip marker (recall-quality wave). Present+ // only on an opt-in iterative call: the plan phase (needs-llm-step)+ // or the commit call's final marker. Declared deliberately for the+ // same reason every envelope here is declared.+ iterative: {+ type: "object",+ required: ["phase"],+ properties: {+ phase: { type: "string" },+ round: { type: "integer" },+ token: { type: "string" },+ llm_step: { type: "object" },+ pool_ids: { type: "array", items: { type: "integer" } },+ gaps: { type: "array", items: { type: "string" } },+ rounds: { type: "array", items: { type: "object" } },+ stop_reason: { type: "string" },+ },+ },// The ranked pool the `limit` sliced these rows from (task F) - how// many candidates were ranked, not how many came back. The descriptor// grammar carries no prose, so the meaning is documented here, in@@ -671,10 +707,24 @@ export const RECALL_GATE_NEGATIVE_STATES: ReadonlyArray<NegativeRecallState> = Oconst RECALL_GATE_OUTPUT_SCHEMA: NonNullable<ToolDefinition["outputSchema"]> = {type: "object",- required: ["retrieve", "reason"],+ required: ["retrieve", "admit", "reason"],properties: {retrieve: { type: "boolean" },+ // The admission the verdict stands on, always present: with a+ // measurement it IS the graded admission (so `retrieve` can never+ // contradict `tier`); without one it names the structural fail-open.+ admit: { type: "boolean" },reason: { type: "string" },+ // Graded surfacing key (t_107a3249): present only when the caller+ // supplied the scores/match_quality pair. `key` is the measured+ // match quality, null exactly where nothing was measurable (a+ // structurally suppressed prompt); `tier` is the closed admission+ // vocabulary. Absent - never implied - without a measurement. The+ // entry is permissive because the descriptor language declares ONE+ // `type` per node: `number|null` is not expressible here, so `{}` is+ // a statement about the language, not an omission.+ key: {},+ tier: { type: "string", enum: [...SURFACING_TIERS] },adequacy: {type: "object",required: [@@ -1040,6 +1090,37 @@ async function toolBrainSearch(pathPrefix: focusPathPrefix ?? null,}): undefined;+ // Iterative round-trip args (recall-quality wave). The flag is the+ // per-query opt-in; token and payload are the commit leg's fields. Any+ // present value of the wrong shape is refused with a named argument+ // error rather than silently ignored - the kernel cannot tell an+ // intended commit from a typo'd one.+ const iterative = coerceBoolOptional(args, "iterative") ?? false;+ const iterativeToken = coerceStringOptional(args, "iterative_token", 128);+ const iterativePayload = args["iterative_payload"];+ if (+ iterativePayload !== undefined &&+ (typeof iterativePayload !== "object" ||+ iterativePayload === null ||+ Array.isArray(iterativePayload))+ ) {+ throw new MCPError(INVALID_PARAMS, "argument 'iterative_payload' must be an object");+ }+ // The iterative round-trip is a single-vault loop: a cross-vault+ // union cannot carry the pause across origins (each leg mints its own+ // token, and a commit would mark one spent while the others rebuild+ // the pause and fail token_mismatch). The combination is refused by+ // name at the argument layer, so no iterative field ever reaches the+ // federated legs.+ if (+ globalSearch &&+ (iterative || iterativeToken !== undefined || iterativePayload !== undefined)+ ) {+ throw new MCPError(+ INVALID_PARAMS,+ "iterative recall arguments are not supported with global: true; the loop runs on the single-vault path",+ );+ }const focusSession = coerceStringOptional(args, "focus_session", 128);const properties = parsePropertiesArgument(args["properties"]);const degreeFilters = parseDegreeArgument(args["degree"]);@@ -1110,6 +1191,9 @@ async function toolBrainSearch(// surface opts in by default; record_access=false suppresses it,// and cross-vault union never records (results span foreign vaults)....(recordAccess && !globalSearch ? { recordAccess: true } : {}),+ ...(iterative ? { iterative: true } : {}),+ ...(iterativeToken !== undefined ? { iterativeToken } : {}),+ ...(iterativePayload !== undefined ? { iterativePayload } : {}),};try {// Cross-vault union (t_72a22658): explicit per-call opt-in.@@ -1242,6 +1326,33 @@ async function toolBrainSearch(trustGateEnabled: config.recall.retrievalTrustGateEnabled,}),...(telemetryRecord ? { telemetry_id: telemetryRecord.id } : {}),+ // Iterative round-trip marker: the plan phase carries the decider+ // envelope and its token; a committed call carries the final marker.+ // Absent - never null - on every other response, so the default+ // shape stays byte-identical.+ ...(outcome.iterative === undefined+ ? {}+ : {+ iterative:+ outcome.iterative.phase === "needs-llm-step"+ ? {+ phase: outcome.iterative.phase,+ round: outcome.iterative.round,+ token: outcome.iterative.token,+ llm_step: outcome.iterative.llmStep,+ pool_ids: [...outcome.iterative.poolIds],+ gaps: [...outcome.iterative.gaps],+ // The deterministic loop's accounting before the pause,+ // projected the same way the final marker does it.+ rounds: [...outcome.iterative.rounds],+ stop_reason: outcome.iterative.stopReason,+ }+ : {+ phase: outcome.iterative.phase,+ rounds: [...outcome.iterative.rounds],+ stop_reason: outcome.iterative.stopReason,+ },+ }),// Advisory decision-model answer carried by the rerank request (issue// #213, Part 8). Absent unless rerank kind `decision-model` ran with// the `answerable` use on and a valid answer arrived.@@ -1322,10 +1433,11 @@ async function toolBrainRecallGate(// the gate record so that record can carry the advisory signal below;// a refused argument is rethrown only after the record, as before.let refused: unknown = null;+ let attempt: ReturnType<typeof coerceRecallAdequacyInput> | undefined;let verdict: ReturnType<typeof assessRecallAdequacy> | undefined;let answerable: DecisionAnswerableOutcome | undefined;try {- const attempt = coerceRecallAdequacyInput("brain_recall_gate", args, RECALL_SCORES_ARG_NAME);+ attempt = coerceRecallAdequacyInput("brain_recall_gate", args, RECALL_SCORES_ARG_NAME);const answerableArg = coerceDecisionAnswerable("brain_recall_gate",args,@@ -1346,6 +1458,26 @@ async function toolBrainRecallGate(} catch (err) {refused = err;}+ // Graded surfacing key (t_107a3249): the structural decision above+ // composed with the shared admission calculator over the MEASURED+ // quality, when the caller supplied the pair. The quality argument is+ // already validated to a finite [0,1] number by the coercion above, so+ // this cannot refuse. With a measurement the graded admission IS the+ // binary verdict - a below-floor quality refuses, it does not ride the+ // structural fail-open behind the tier's back - and the response carries+ // both `retrieve` and `admit` so the two can never drift apart again.+ // Without a measurement the structural fail-open stands unchanged and+ // `admit` simply names it.+ const measured = attempt?.matchQuality;+ const graded = evaluateGradedSurfacing({+ prompt,+ previousPrompt: previousPrompt ?? null,+ explicit,+ channel: RECALL_CHANNEL.mcp,+ ...(measured !== undefined ? { matchQuality: measured } : {}),+ });+ const retrieve = measured !== undefined ? graded.admit : decision.retrieve;+ const gradedFields = measured !== undefined ? { key: graded.key, tier: graded.tier } : {};const answerableVerdict = answerable?.kind === "annotated" ? answerable.verdict : undefined;// Gate telemetry (t_65036e02): default off. Routed through the lazy// emit kernel (t_5d7aa7c5) - the payload thunk never runs with the@@ -1355,10 +1487,17 @@ async function toolBrainRecallGate(emitGateTelemetry(ctx.vault, {host: telemetryHost,prompt,- retrieve: decision.retrieve,+ // The recorded decision agrees with the admission, so a measured+ // below-floor call is summarized as a skip, never as retrieved.+ retrieve,reason: decision.reason,...(sessionId !== undefined ? { sessionId } : {}),...(turnId !== undefined ? { turnId } : {}),+ // The transport rides measured decisions only: it calibrates the+ // measured admission, and an unmeasured structural verdict is+ // already described by decision and reason.+ ...(measured !== undefined ? { channel: RECALL_CHANNEL.mcp } : {}),+ ...(measured !== undefined ? { surfacing: { key: graded.key, tier: graded.tier } } : {}),...(verdict !== undefined && answerableVerdict !== undefined? {decisionAnswerable: {@@ -1371,7 +1510,8 @@ async function toolBrainRecallGate(}),);if (refused !== null) throw refused;- if (verdict === undefined) return { ...decision };+ if (verdict === undefined)+ return { retrieve, admit: retrieve, reason: decision.reason, ...gradedFields };// signals-that-survive, unit 6: an unmet verdict is stamped onto the// cross-query demand log under the bucket key normalizeQueryTerms already// computes, so the knowledge-gap loop can aggregate recurrence without a@@ -1401,7 +1541,10 @@ async function toolBrainRecallGate();}return {- ...decision,+ retrieve,+ admit: retrieve,+ reason: decision.reason,+ ...gradedFields,adequacy: {level: verdict.level,action: verdict.action,@@ -1976,7 +2119,7 @@ export const SEARCH_TOOLS: ReadonlyArray<ToolDefinition> = Object.freeze([{name: "brain_recall_gate",description:- "Classify whether an automatic recall attempt should run. Diagnostics only; does not search. Pass `scores` AND `match_quality` TOGETHER for an adequacy verdict — sufficient/proceed, weak/re_recall, insufficient/abstain; either alone is INVALID_PARAMS (see `dependentRequired`).",+ "Classify whether recall should run. Diagnostics only; does not search. Pass `scores` AND `match_quality` together for an adequacy verdict; either alone is INVALID_PARAMS (see `dependentRequired`). A measurement decides the verdict: below-floor quality answers retrieve false. `admit` echoes it.",inputSchema: RECALL_GATE_INPUT_SCHEMA,outputSchema: RECALL_GATE_OUTPUT_SCHEMA,handler: toolBrainRecallGate,diff --git a/tests/cli/brain-bench.test.ts b/tests/cli/brain-bench.test.tsindex cb62098c..abafc613 100644--- a/tests/cli/brain-bench.test.ts+++ b/tests/cli/brain-bench.test.ts@@ -6,10 +6,18 @@*/import { afterEach, beforeEach, describe, expect, test } from "bun:test";-import { existsSync, mkdtempSync, readdirSync, rmSync } from "node:fs";+import { existsSync, mkdtempSync, readFileSync, readdirSync, rmSync, writeFileSync } from "node:fs";import { tmpdir } from "node:os";import { join } from "node:path";+import {+ benchSuite,+ benchSuiteNames,+ parseBenchPinnedKnobs,+ parseRecallFloorFlag,+ registerBenchSuite,+} from "../../src/cli/brain/verbs/bench.ts";+import { parseBenchFixture } from "../../src/core/bench/fixture.ts";import { runCli } from "../helpers/run-cli.ts";let tmp: string;@@ -84,3 +92,355 @@ describe("o2b brain bench memory", () => {expect(out.stderr).toContain("fixture not found");});});++/**+ * The suite registry (recall-quality wave, t_607d429d): a --suite name+ * maps to `{ loader, capabilities }`, the registry is the appendable+ * registration point for suite modules, and the no-flag default path is+ * byte-identical to the pre-registry dispatch.+ */+describe("bench suite registry", () => {+ const STUB_SUITE = "registry-stub";+ const STUB_FIXTURE = parseBenchFixture({+ name: "registry-stub",+ notes: [{ path: "Brain/notes/a.md", body: "alpha note" }],+ questions: [+ { id: "q1", category: "single_hop", query: "alpha", expected_paths: ["Brain/notes/a.md"] },+ ],+ });+ const stubLoaderCalls: string[] = [];++ registerBenchSuite(STUB_SUITE, {+ loader: (fixturePath: string) => {+ stubLoaderCalls.push(fixturePath);+ return { fixture: STUB_FIXTURE };+ },+ capabilities: { embeddings: false },+ });++ beforeEach(() => {+ stubLoaderCalls.length = 0;+ });++ test("the registry maps suite names to loader and capabilities", () => {+ const locomo = benchSuite("locomo");+ expect(locomo).toBeDefined();+ expect(locomo!.capabilities).toEqual({ embeddings: false });+ expect(typeof locomo!.loader).toBe("function");+ expect(benchSuiteNames()).toContain("locomo");+ // Sorted for stable listings (order-dependent assertions use sorted listings).+ expect(benchSuiteNames()).toEqual(benchSuiteNames().toSorted());+ });++ test("a registered suite reaches its loader through --suite", async () => {+ const out = await runCli(+ [+ "brain",+ "bench",+ "memory",+ "--fixture",+ "core-recall",+ "--suite",+ STUB_SUITE,+ "--runs-dir",+ runsDir,+ "--json",+ ],+ {},+ );+ expect(out.returncode).toBe(0);+ // The stub loader received the RESOLVED fixture path.+ expect(stubLoaderCalls).toEqual([join("tests", "fixtures", "bench", "core-recall.json")]);+ const report = JSON.parse(out.stdout) as { fixture: string };+ expect(report.fixture).toBe("registry-stub");+ }, 60_000);++ test("an unknown suite fails with the current message shape", async () => {+ const out = await runCli(+ [+ "brain",+ "bench",+ "memory",+ "--fixture",+ "core-recall",+ "--suite",+ "bogus",+ "--runs-dir",+ runsDir,+ ],+ {},+ );+ expect(out.returncode).not.toBe(0);+ expect(out.stderr).toContain("unknown --suite 'bogus' (supported:");+ });++ test("omitting --suite keeps the native loader and the report shape unchanged", async () => {+ const out = await runCli(+ ["brain", "bench", "memory", "--fixture", "core-recall", "--runs-dir", runsDir, "--json"],+ {},+ );+ expect(out.returncode).toBe(0);+ const report = JSON.parse(out.stdout) as { fixture: string };+ expect(report.fixture).toBe("core-recall");+ // The native default path is not a named suite and adds no suite fields.+ expect("suite" in report).toBe(false);+ expect(stubLoaderCalls).toEqual([]);+ }, 60_000);++ test("the longmemeval suite prints its strict recall_all@5 family", async () => {+ const out = await runCli(+ [+ "brain",+ "bench",+ "memory",+ "--fixture",+ "longmemeval-sample",+ "--suite",+ "longmemeval",+ "--runs-dir",+ runsDir,+ ],+ {},+ );+ expect(out.returncode).toBe(0);+ // The named metric family rides the CLI output beside the existing+ // families - never folded into the pass rate.+ expect(out.stdout).toContain("longmemeval: recall_all@5 1 abstention_excluded 1");+ }, 60_000);++ test("the longmemeval report family rides the --json report", async () => {+ const out = await runCli(+ [+ "brain",+ "bench",+ "memory",+ "--fixture",+ "longmemeval-sample",+ "--suite",+ "longmemeval",+ "--runs-dir",+ runsDir,+ "--json",+ ],+ {},+ );+ expect(out.returncode).toBe(0);+ const report = JSON.parse(out.stdout) as {+ longmemeval?: { recall_all_at_5: number; abstention_excluded: number };+ };+ expect(report.longmemeval).toEqual({ recall_all_at_5: 1, abstention_excluded: 1 });+ }, 60_000);++ test("a duplicate suite registration is refused by name", () => {+ expect(() =>+ registerBenchSuite("locomo", {+ loader: () => ({ fixture: STUB_FIXTURE }),+ capabilities: { embeddings: false },+ }),+ ).toThrow(/already registered/);+ });+});++/**+ * The knob pin and the recall floor reach `runMemoryBench` from the CLI+ * (pr-250 review, M7): the pin is the run's search configuration and the+ * floor is the admission bound the surfacing-replay suite sweeps, and+ * both are part of the run identity - asserted here through the+ * checkpoint each run persists.+ */+describe("bench knob pin and recall floor", () => {+ /** A one-question fixture, so each e2e run stays cheap. */+ function writePinFixture(): string {+ const path = join(tmp, "pin-fixture.json");+ writeFileSync(+ path,+ JSON.stringify({+ name: "pin-check",+ notes: [{ path: "Brain/notes/a.md", body: "alpha note" }],+ questions: [+ {+ id: "q1",+ category: "single_hop",+ query: "alpha",+ expected_paths: ["Brain/notes/a.md"],+ },+ ],+ }),+ );+ return path;+ }++ function checkpointOf(+ runsDir: string,+ runId: string,+ ): {+ pinned_knobs?: unknown;+ knobs_hash?: string;+ } {+ return JSON.parse(readFileSync(join(runsDir, runId, "checkpoint.json"), "utf8")) as {+ pinned_knobs?: unknown;+ knobs_hash?: string;+ };+ }++ test("--pin reaches the run identity verbatim, replacing the default pin", async () => {+ const fixturePath = writePinFixture();+ // A pin the resolver accepts: the semantic lane stays off and one+ // chunking knob moves. Value semantics are the resolver's, not this+ // flag's - a pin like `keywordWeight: 0.7` alone dies there with its+ // named sum-to-one error, which is the loud path by design.+ const pin = { semantic: { enabled: false }, chunkSize: 512 };+ const out = await runCli(+ [+ "brain",+ "bench",+ "memory",+ "--fixture",+ fixturePath,+ "--runs-dir",+ runsDir,+ "--pin",+ JSON.stringify(pin),+ "--json",+ ],+ {},+ );+ expect(out.returncode).toBe(0);+ const report = JSON.parse(out.stdout) as { run_id: string };+ const checkpoint = checkpointOf(runsDir, report.run_id);+ // The pin rides the checkpoint byte for byte - nothing merged in, so+ // the run the report describes is exactly the configuration asked for.+ expect(checkpoint.pinned_knobs).toEqual(pin);+ }, 60_000);++ test("--recall-floor reaches the run identity: a floor change is a different run", async () => {+ const fixturePath = writePinFixture();+ const plain = await runCli(+ ["brain", "bench", "memory", "--fixture", fixturePath, "--runs-dir", runsDir, "--json"],+ {},+ );+ expect(plain.returncode).toBe(0);+ const plainId = (JSON.parse(plain.stdout) as { run_id: string }).run_id;+ const floored = await runCli(+ [+ "brain",+ "bench",+ "memory",+ "--fixture",+ fixturePath,+ "--runs-dir",+ runsDir,+ "--recall-floor",+ "0.5",+ "--json",+ ],+ {},+ );+ expect(floored.returncode).toBe(0);+ const flooredId = (JSON.parse(floored.stdout) as { run_id: string }).run_id;+ expect(flooredId).not.toBe(plainId);+ // And resuming with the SAME floor reuses the run; the identity+ // guard, not the CLI, owns what a floor change on resume means.+ const resumed = await runCli(+ [+ "brain",+ "bench",+ "memory",+ "--fixture",+ fixturePath,+ "--runs-dir",+ runsDir,+ "--recall-floor",+ "0.5",+ "--resume",+ flooredId,+ "--json",+ ],+ {},+ );+ expect(resumed.returncode).toBe(0);+ expect((JSON.parse(resumed.stdout) as { run_id: string }).run_id).toBe(flooredId);+ expect(readdirSync(runsDir)).toHaveLength(2);+ }, 60_000);++ test("garbage is refused by name", async () => {+ const fixturePath = writePinFixture();+ const badJson = await runCli(+ [+ "brain",+ "bench",+ "memory",+ "--fixture",+ fixturePath,+ "--runs-dir",+ runsDir,+ "--pin",+ "{not json",+ ],+ {},+ );+ expect(badJson.returncode).not.toBe(0);+ expect(badJson.stderr).toContain("--pin is not valid JSON");++ const notAnObject = await runCli(+ ["brain", "bench", "memory", "--fixture", fixturePath, "--pin", "[1,2]"],+ {},+ );+ expect(notAnObject.stderr).toContain("--pin must be a JSON object");++ const unknownKnob = await runCli(+ ["brain", "bench", "memory", "--fixture", fixturePath, "--pin", '{"frobNobs":1}'],+ {},+ );+ expect(unknownKnob.stderr).toContain("unknown knob 'frobNobs'");++ const unknownMember = await runCli(+ [+ "brain",+ "bench",+ "memory",+ "--fixture",+ fixturePath,+ "--pin",+ '{"semantic":{"enabeled":true}}',+ ],+ {},+ );+ expect(unknownMember.stderr).toContain("--pin 'semantic.enabeled' is not a known knob");++ const harnessOwned = await runCli(+ ["brain", "bench", "memory", "--fixture", fixturePath, "--pin", '{"vault":"/elsewhere"}'],+ {},+ );+ expect(harnessOwned.stderr).toContain("--pin may not set 'vault'");++ const badFloor = await runCli(+ ["brain", "bench", "memory", "--fixture", fixturePath, "--recall-floor", "abc"],+ {},+ );+ expect(badFloor.returncode).not.toBe(0);+ expect(badFloor.stderr).toContain("--recall-floor must be a positive number, got 'abc'");++ const zeroFloor = await runCli(+ ["brain", "bench", "memory", "--fixture", fixturePath, "--recall-floor", "0"],+ {},+ );+ expect(zeroFloor.stderr).toContain("--recall-floor must be a positive number, got '0'");+ }, 60_000);++ test("the pin parser refuses shape garbage and leaves value semantics to the resolver", () => {+ expect(parseBenchPinnedKnobs('{"semantic":{"enabled":false}}')).toEqual({+ semantic: { enabled: false },+ });+ // A scalar knob's VALUE is not shape-checked here: an out-of-range+ // number is resolveSearchConfig's named error, not this parser's.+ expect(parseBenchPinnedKnobs('{"keywordWeight":99}')).toEqual({ keywordWeight: 99 });+ expect(() => parseBenchPinnedKnobs('{"semantic":false}')).toThrow(+ /'semantic' must be a JSON object/,+ );+ expect(() => parseRecallFloorFlag(undefined)).not.toThrow();+ expect(parseRecallFloorFlag("0.35")).toBe(0.35);+ expect(() => parseRecallFloorFlag("")).toThrow(/got ''/);+ expect(() => parseRecallFloorFlag("-1")).toThrow(/got '-1'/);+ });+});diff --git a/tests/cli/brain-session-recall.test.ts b/tests/cli/brain-session-recall.test.tsindex 59e47056..951356cf 100644--- a/tests/cli/brain-session-recall.test.ts+++ b/tests/cli/brain-session-recall.test.ts@@ -4,6 +4,7 @@ import { tmpdir } from "node:os";import { join } from "node:path";import { importSessionRecall } from "../../src/core/brain/session-recall.ts";+import { appendContinuityRecord } from "../../src/core/brain/continuity/store.ts";import type { SessionTurn } from "../../src/core/brain/sessions/types.ts";import { runCli } from "../helpers/run-cli.ts";@@ -93,3 +94,201 @@ test("brain session-grep/describe/expand query imported recall DAG", async () =>expect(expanded.immediate_sources.length).toBeGreaterThan(0);expect(expanded.raw_content).toHaveLength(1);});++test("brain session-grep coverage operation and describe topics (t_2c2a883c)", async () => {+ const coverage = await runCli([+ "brain",+ "session-grep",+ "--vault",+ vault,+ "--operation",+ "coverage",+ "--char-budget",+ "100000",+ "--session-id",+ "session-cli",+ "--json",+ ]);+ expect(coverage.returncode).toBe(0);+ const parsed = JSON.parse(coverage.stdout);+ expect(parsed.turns.length).toBe(3);+ expect(parsed.diagnostics.topics_requested).toBe(12);+ expect(parsed.diagnostics.topics_realized).toBe(2);+ expect(parsed.diagnostics.chars_used).toBeGreaterThan(0);++ const described = await runCli([+ "brain",+ "session-describe",+ "--vault",+ vault,+ "--session-id",+ "session-cli",+ "--topics",+ "--json",+ ]);+ expect(described.returncode).toBe(0);+ expect(JSON.parse(described.stdout).topic_report.topics_realized).toBe(2);+});++test("entity-key seeds the fan-out and match-only flags are refused under coverage", async () => {+ appendContinuityRecord(vault, {+ kind: "session_entity_mention",+ createdAt: "2026-05-20T17:00:04.000Z",+ sourceRefs: [{ id: "session-cli:t1:symbol:ReceiptSearch" }],+ payload: { family: "symbol", key: "ReceiptSearch", session_ref: "session-cli", turn_id: "t1" },+ });++ const seeded = await runCli([+ "brain",+ "session-grep",+ "--vault",+ vault,+ "--operation",+ "coverage",+ "--char-budget",+ "100000",+ "--entity-key",+ "ReceiptSearch",+ "--json",+ ]);+ expect(seeded.returncode).toBe(0);+ const parsed = JSON.parse(seeded.stdout);+ // The seeded facet leads the fan-out: the mention's establishing turn+ // is first; the budget may still realize further topics after it.+ const turnIds = parsed.turns.map((t: { turn_id: string }) => t.turn_id);+ expect(turnIds[0]).toBe("t1");+ expect(turnIds).toContain("t1");++ for (const extra of [+ ["--query", "receipt"],+ ["--since", "2026-05-01"],+ ["--before", "2026-05-21"],+ ["--limit", "5"],+ ["--snippet-chars", "40"],+ ] as const) {+ const refused = await runCli([+ "brain",+ "session-grep",+ "--vault",+ vault,+ "--operation",+ "coverage",+ "--char-budget",+ "100000",+ ...extra,+ ]);+ expect(refused.returncode).not.toBe(0);+ expect(`${refused.stderr}${refused.stdout}`).toContain(extra[0]);+ }+});++test("coverage without a character budget is refused by name", async () => {+ const missing = await runCli([+ "brain",+ "session-grep",+ "--vault",+ vault,+ "--operation",+ "coverage",+ "--json",+ ]);+ expect(missing.returncode).not.toBe(0);+ expect(`${missing.stderr}${missing.stdout}`).toContain("char-budget");+});++test("--entity-key accepts the mined-key length (200) and refuses longer", async () => {+ // Mined keys run to MINED_KEY_MAX_LENGTH = 200, so the CLI cap matches+ // the miner's - parity with the MCP tool, where a longer key is refused.+ const tooLong = await runCli([+ "brain",+ "session-grep",+ "--vault",+ vault,+ "--operation",+ "coverage",+ "--char-budget",+ "100000",+ "--entity-key",+ "K".repeat(201),+ "--json",+ ]);+ expect(tooLong.returncode).not.toBe(0);+ expect(`${tooLong.stderr}${tooLong.stdout}`).toContain("at most 200 characters");++ const atCap = await runCli([+ "brain",+ "session-grep",+ "--vault",+ vault,+ "--operation",+ "coverage",+ "--char-budget",+ "100000",+ "--entity-key",+ "K".repeat(200),+ "--json",+ ]);+ // A 200-character key is a legal mined key: the refusal is about the+ // unknown key, never about its length.+ expect(atCap.returncode).not.toBe(0);+ expect(`${atCap.stderr}${atCap.stdout}`).toContain("no session_entity_mention row names");+});++test("coverage-only flags are refused under the match operation", async () => {+ // The mirror of the refusal matrix above: --char-budget and --entity-key+ // name the coverage operation's knobs, so the default match operation+ // refuses them instead of silently ignoring them.+ for (const extra of [+ ["--char-budget", "100000"],+ ["--entity-key", "ReceiptSearch"],+ ] as const) {+ const refused = await runCli([+ "brain",+ "session-grep",+ "--vault",+ vault,+ "--query",+ "receipt",+ ...extra,+ "--json",+ ]);+ expect(refused.returncode).not.toBe(0);+ expect(`${refused.stderr}${refused.stdout}`).toContain(+ `${extra[0]} applies to --operation coverage only`,+ );+ }+});++test("a budget below the floor-weighted selection surfaces the typed infeasibility", async () => {+ const infeasible = await runCli([+ "brain",+ "session-grep",+ "--vault",+ vault,+ "--operation",+ "coverage",+ "--char-budget",+ "1",+ "--session-id",+ "session-cli",+ "--json",+ ]);+ expect(infeasible.returncode).not.toBe(0);+ expect(`${infeasible.stderr}${infeasible.stdout}`).toContain("required chars");+});++test("an unknown operation value is refused by name", async () => {+ const unknown = await runCli([+ "brain",+ "session-grep",+ "--vault",+ vault,+ "--operation",+ "widely",+ "--query",+ "receipt",+ "--json",+ ]);+ expect(unknown.returncode).not.toBe(0);+ expect(`${unknown.stderr}${unknown.stdout}`).toContain("operation");+});diff --git a/tests/core/architecture/verdict-vocabulary-census.test.ts b/tests/core/architecture/verdict-vocabulary-census.test.tsindex 7eddfc8a..6ec68fac 100644--- a/tests/core/architecture/verdict-vocabulary-census.test.ts+++ b/tests/core/architecture/verdict-vocabulary-census.test.ts@@ -510,6 +510,16 @@ import {ARCHIVE_VERIFICATIONS,isArchiveVerification,} from "../../../src/core/brain/provenance/source-archive.ts";+import {+ REPLAY_EXPECTATION,+ REPLAY_EXPECTATIONS,+ isReplayExpectation,+} from "../../../src/core/bench/replay-fixture.ts";+import {+ SURFACING_TIER,+ SURFACING_TIERS,+ isSurfacingTier,+} from "../../../src/core/search/surfacing-key.ts";interface VocabularyUnderCensus {/** Identifies the vocabulary in a failure message. */@@ -1586,6 +1596,26 @@ const CENSUS: ReadonlyArray<VocabularyUnderCensus> = Object.freeze([members: ARCHIVE_VERIFICATIONS,guard: isArchiveVerification,},+ {+ // What a recorded surfacing-replay prompt expected memory to do+ // (recall-quality wave, Lane C): `inject` (speak up) vs `abstain`+ // (stay quiet) is the pair the replay corpus scores the gate on, and+ // a boolean would collapse outcomes the fixture round-trips by name.+ name: "REPLAY_EXPECTATION",+ values: REPLAY_EXPECTATION,+ members: REPLAY_EXPECTATIONS,+ guard: isReplayExpectation,+ },+ {+ // The graded-surfacing admission verdict (recall-quality wave,+ // Lane C): explicit, suppressed, admitted, below_floor and+ // unmeasurable_quality are distinct outcomes the gate telemetry and+ // the replay corpus both render, not a boolean admitted/not.+ name: "SURFACING_TIER",+ values: SURFACING_TIER,+ members: SURFACING_TIERS,+ guard: isSurfacingTier,+ },]);// ---------------------------------------------------------------------------@@ -1850,9 +1880,10 @@ const SCANNED = scanVocabularies(SOURCE_TREE);* How many four-piece vocabularies `src/` currently holds. Measured, and* kept as an equality rather than a floor - see the population test.*/-// 97: Lane C's ARCHIVE_VERIFICATION (answer trust) joins the scanned-// population, the same append Lane A's ANSWER_QUOTE_VERDICT made.-const VOCABULARY_POPULATION = 97;+// 99: Lane C's REPLAY_EXPECTATION (replay corpus) and SURFACING_TIER+// (graded surfacing) join the scanned population, the same append Lane+// C's ARCHIVE_VERIFICATION made.+const VOCABULARY_POPULATION = 99;const REGISTERED = new Map(CENSUS.map((entry) => [entry.name, entry] as const));describe("verdict vocabulary census", () => {diff --git a/tests/core/bench/failure-modes-baseline.test.ts b/tests/core/bench/failure-modes-baseline.test.tsindex 69dfa70f..57022552 100644--- a/tests/core/bench/failure-modes-baseline.test.ts+++ b/tests/core/bench/failure-modes-baseline.test.ts@@ -43,13 +43,15 @@ import { mkdtempSync, readFileSync, rmSync } from "node:fs";import { tmpdir } from "node:os";import { join } from "node:path";-import { loadBenchFixture } from "../../../src/core/bench/fixture.ts";+import { fixtureHash, loadBenchFixture } from "../../../src/core/bench/fixture.ts";import { runMemoryBench } from "../../../src/core/bench/phases.ts";+import { loadReplayBenchFixture } from "../../../src/core/bench/replay.ts";import type { BenchReport } from "../../../src/core/bench/types.ts";const FIXTURE_DIR = join("tests", "fixtures", "bench");const FIXTURE_PATH = join(FIXTURE_DIR, "failure-modes.json");const BASELINE_PATH = join(FIXTURE_DIR, "failure-modes.baseline.json");+const FAILURE_MODES_SOURCE = join("src", "core", "bench", "failure-modes.ts");let runsDir: string;@@ -96,7 +98,44 @@ describe("failure-mode baseline", () => {fixture_hash: string;schema: string;};- expect(baseline.fixture_hash).toMatch(/^[0-9a-f]{16}$/);expect(baseline.schema).toBe("o2b.bench.v2");+ // Hash-shaped is not enough: the committed hash must be the CURRENT+ // fixture's, so an edited-but-never-re-measured fixture names itself+ // here instead of failing somewhere confusing downstream.+ expect(baseline.fixture_hash).toBe(fixtureHash(loadBenchFixture(FIXTURE_PATH)));+ });++ test("the graded gate is scoreable: the replay corpus bounds its false-fire rate", async () => {+ // The structural half of the gate fails open by design; the graded+ // admission key is the bound, and the replay corpus is its measurement+ // instrument. Three assertions make the bound MEANINGFUL rather than+ // vacuous: the calibrated gate speaks on the corpus at all (an+ // always-abstain gate would also post zero false fires), it never+ // false-fires on it, and the same corpus catches a permissive gate -+ // the floor 0 arm shows the corpus can tell an always-inject strategy+ // apart, so the calibrated zero is a measured bound, not silence.+ const fixture = loadReplayBenchFixture(join(FIXTURE_DIR, "surfacing-replay-sample.json"));+ const calibrated = await runMemoryBench({ fixture, runsDir });+ expect(calibrated.context_cost.avg_injected_tokens).toBeGreaterThan(0);+ expect(calibrated.failure_modes.false_fire_rate).toBe(0);+ const permissive = await runMemoryBench({+ fixture,+ runsDir: join(runsDir, "permissive"),+ recallFloor: 0,+ });+ expect(permissive.failure_modes.false_fire_rate).toBeGreaterThan(0);+ }, 60_000);++ test("the failure-modes docblock describes the graded gate, not an unscoreable one", () => {+ // The retired claim - that the gate's false-fire rate is ~1 by+ // construction and scoring it would be theatre - described the+ // structural predicate alone. Admission now rides the graded surfacing+ // key, and the replay suite measures it; the docblock that understates+ // what ships invites the next reader to re-derive the caveat.+ const source = readFileSync(FAILURE_MODES_SOURCE, "utf8");+ expect(source).not.toContain("would be theatre");+ expect(source).not.toContain("NOT THE GATE");+ // It names the instrument that replaced the caveat.+ expect(source).toMatch(/surfacing-replay/);});});diff --git a/tests/core/bench/fixture.test.ts b/tests/core/bench/fixture.test.tsindex 72e47e48..9ff7510c 100644--- a/tests/core/bench/fixture.test.ts+++ b/tests/core/bench/fixture.test.ts@@ -89,6 +89,38 @@ describe("parseBenchFixture", () => {expect(c).not.toBe(a);});+ test("previous_prompt rides a replayed question; absent or non-string stays absent", () => {+ const carried = parseBenchFixture({+ ...FIXTURE,+ questions: [+ {+ id: "q1",+ category: "proactive_recall",+ prompt: "/compact",+ expect_inject: false,+ previous_prompt: "who owns the billing migration",+ },+ ],+ });+ expect(carried.questions[0]?.previous_prompt).toBe("who owns the billing migration");+ // The default path stays byte-identical: no key, no field.+ expect(parseBenchFixture(FIXTURE).questions[0]?.previous_prompt).toBeUndefined();+ // The allowlist reads it by type: a non-string is not smuggled in.+ const mistyped = parseBenchFixture({+ ...FIXTURE,+ questions: [+ {+ id: "q1",+ category: "proactive_recall",+ prompt: "/compact",+ expect_inject: false,+ previous_prompt: 7,+ },+ ],+ });+ expect(mistyped.questions[0]?.previous_prompt).toBeUndefined();+ });+test("loadBenchFixture reads a file and fails fast on broken JSON", () => {const path = join(tmp, "fixture.json");writeFileSync(path, JSON.stringify(FIXTURE));diff --git a/tests/core/bench/longmemeval.test.ts b/tests/core/bench/longmemeval.test.tsnew file mode 100644index 00000000..dd1dfcf6--- /dev/null+++ b/tests/core/bench/longmemeval.test.ts@@ -0,0 +1,756 @@+/**+ * LongMemEval bench suite adapter (recall-quality wave, t_607d429d):+ * parser with named errors, converter with abstention exclusion and the+ * direct gold-session-id join, no expected_text reliance for retrieval+ * scoring, and an end-to-end run over the committed sample fixture.+ */++import { afterEach, describe, expect, test } from "bun:test";+import { mkdtempSync, readFileSync, rmSync, writeFileSync } from "node:fs";+import { tmpdir } from "node:os";+import { join } from "node:path";++import { benchSuite } from "../../../src/cli/brain/verbs/bench.ts";+import { embedBenchVaultIndex } from "../../../src/core/bench/embedding-cache.ts";+import { parseBenchFixture, materializeBenchVault } from "../../../src/core/bench/fixture.ts";+import {+ LONGMEMEVAL_JUDGE_QUESTION_TEMPLATE,+ LONGMEMEVAL_JUDGE_SYSTEM_PROMPT,+ LONGMEMEVAL_PROMPT_PROVENANCE,+ LONGMEMEVAL_RECALL_CUTOFF,+ loadLongMemEvalFixture,+ longMemEvalToBenchFixture,+ parseLongMemEvalDataset,+ scoreLongMemEvalRecall,+} from "../../../src/core/bench/longmemeval.ts";+import { benchSearchConfig, runMemoryBench } from "../../../src/core/bench/phases.ts";+import { BENCH_REPORT_SCHEMA, type BenchPinnedKnobs } from "../../../src/core/bench/types.ts";++const SAMPLE = join("tests", "fixtures", "bench", "longmemeval-sample.json");+const OFFICIAL_SAMPLE = join("tests", "fixtures", "bench", "longmemeval-official-sample.json");++const dirs: string[] = [];+afterEach(() => {+ for (const d of dirs.splice(0)) rmSync(d, { recursive: true, force: true });+});++/** A minimal valid entry, overridden per test. */+function entry(overrides: Record<string, unknown>): Record<string, unknown> {+ const sessions = [+ {+ session_id: "s1",+ date: "2026-03-02T10:00:00Z",+ turns: [+ { role: "user", content: "We picked Blue Heron as the launch codename." },+ { role: "assistant", content: "Noted: the launch codename is Blue Heron." },+ ],+ },+ ];+ return {+ q_id: "q1",+ question_type: "single-hop",+ question: "launch codename",+ haystack_session_id: sessions.map((s) => s.session_id),+ haystack_dates: sessions.map((s) => s.date),+ haystack_session: sessions.map((s) => s.turns),+ answer_session_ids: ["s1"],+ ...overrides,+ };+}++test("an all-abstention dataset names the abstention filter, not a missing dataset", () => {+ const dataset = parseLongMemEvalDataset([+ entry({ q_id: "abstain-1", question_type: "abstention" }),+ ]);+ expect(() => longMemEvalToBenchFixture(dataset)).toThrow(/abstention/);+});++test("session ids that sanitize to one note path are a named parse error", () => {+ const dataset = parseLongMemEvalDataset([+ entry({+ q_id: "collide",+ haystack_session_id: ["a/b", "a-b"],+ haystack_dates: ["2026-01-01", "2026-01-02"],+ haystack_session: [+ [{ role: "user", content: "alpha note" }],+ [{ role: "user", content: "beta note" }],+ ],+ answer_session_ids: ["a/b"],+ }),+ ]);+ expect(() => longMemEvalToBenchFixture(dataset)).toThrow(/same note path/);+});++describe("the official dataset shape", () => {+ test("the committed official-shape sample parses (official keys, types, _abs, question_date)", () => {+ const raw: unknown = JSON.parse(readFileSync(OFFICIAL_SAMPLE, "utf8"));+ const dataset = parseLongMemEvalDataset(raw);+ expect(dataset.entries.map((e) => e.q_id)).toEqual([+ "single-session-user_1",+ "multi-session_2",+ "single-session-user_3_abs",+ ]);+ expect(dataset.entries[0]!.question_type).toBe("single-session-user");+ expect(dataset.entries[0]!.question_date).toBe("2023/05/20 (Sat) 02:21");+ });++ test("official key spellings are read; the legacy sample shape keeps working", () => {+ const official = parseLongMemEvalDataset([+ {+ question_id: "q-official",+ question_type: "single-session-user",+ question: "launch codename",+ question_date: "2023/05/20 (Sat) 02:21",+ haystack_session_ids: ["s1"],+ haystack_sessions: [+ [{ role: "user", content: "We picked Blue Heron as the launch codename." }],+ ],+ haystack_dates: ["2023/05/01 (Mon) 09:15"],+ answer_session_ids: ["s1"],+ },+ ]);+ expect(official.entries[0]!.q_id).toBe("q-official");+ expect(official.entries[0]!.haystack_session_id).toEqual(["s1"]);+ expect(official.entries[0]!.haystack_session).toHaveLength(1);+ const legacy = parseLongMemEvalDataset([entry({})]);+ expect(legacy.entries[0]!.q_id).toBe("q1");+ expect(legacy.entries[0]!.haystack_session_id).toEqual(["s1"]);+ });++ test("every official question type maps to a bench category", () => {+ const types = [+ ["single-session-user", "single_hop"],+ ["single-session-assistant", "single_hop"],+ ["single-session-preference", "single_hop"],+ ["multi-session", "multi_evidence"],+ ["temporal-reasoning", "temporal"],+ ["knowledge-update", "contradiction"],+ ] as const;+ const dataset = parseLongMemEvalDataset(+ types.map(([type], i) =>+ entry({+ q_id: `q-type-${i}`,+ question_type: type,+ haystack_session_id: [`s-type-${i}`],+ haystack_dates: ["2026-03-02T10:00:00Z"],+ haystack_session: [[{ role: "user", content: `type marker ${i} zebra.` }]],+ answer_session_ids: [`s-type-${i}`],+ }),+ ),+ );+ const { fixture } = longMemEvalToBenchFixture(dataset);+ expect(fixture.questions.map((q) => q.category)).toEqual(types.map(([, category]) => category));+ });++ test("abstention is the _abs question-id suffix; the explicit type keeps working", () => {+ const dataset = parseLongMemEvalDataset([+ entry({+ q_id: "single-session-user_9_abs",+ question_type: "single-session-user",+ answer_session_ids: [],+ }),+ entry({ q_id: "abstain-legacy", question_type: "abstention", answer_session_ids: [] }),+ entry({}),+ ]);+ const { fixture, receipt } = longMemEvalToBenchFixture(dataset);+ expect(fixture.questions.map((q) => q.id)).toEqual(["q1"]);+ expect(receipt.abstention_excluded).toBe(2);+ });++ test("question_date is read, falling back to the last haystack date", () => {+ const dataset = parseLongMemEvalDataset([+ entry({ question_date: "2023/05/20 (Sat) 02:21" }),+ entry({ q_id: "q2" }),+ ]);+ expect(dataset.entries[0]!.question_date).toBe("2023/05/20 (Sat) 02:21");+ expect(dataset.entries[1]!.question_date).toBe("2026-03-02T10:00:00Z");+ });++ test("a non-date question_date is a named error", () => {+ expect(() => parseLongMemEvalDataset([entry({ question_date: "eventually" })])).toThrow(+ /question_date/,+ );+ });++ test("the official-shape sample converts with the _abs exclusion", () => {+ const raw: unknown = JSON.parse(readFileSync(OFFICIAL_SAMPLE, "utf8"));+ const { fixture, receipt } = longMemEvalToBenchFixture(parseLongMemEvalDataset(raw));+ expect(receipt.abstention_excluded).toBe(1);+ expect(fixture.questions.map((q) => q.id)).toEqual([+ "single-session-user_1",+ "multi-session_2",+ ]);+ expect(fixture.questions.map((q) => q.category)).toEqual(["single_hop", "multi_evidence"]);+ });+});++describe("parseLongMemEvalDataset", () => {+ test("accepts the official bare-array shape and a named wrapper", () => {+ const bare = parseLongMemEvalDataset([entry({})]);+ expect(bare.entries).toHaveLength(1);+ const wrapped = parseLongMemEvalDataset({ name: "sample", questions: [entry({})] });+ expect(wrapped.name).toBe("sample");+ expect(wrapped.entries).toHaveLength(1);+ });++ test("a missing q_id is a named error", () => {+ expect(() => parseLongMemEvalDataset([entry({ q_id: "" })])).toThrow(/q_id/);+ });++ test("an unknown question type is a named error listing the known types", () => {+ expect(() => parseLongMemEvalDataset([entry({ question_type: "quantum" })])).toThrow(+ /question_type/,+ );+ });++ test("a non-abstention question with no gold sessions is a named error", () => {+ expect(() => parseLongMemEvalDataset([entry({ answer_session_ids: [] })])).toThrow(+ /answer_session_ids/,+ );+ });++ test("a gold session id that joins no haystack session is rejected by name", () => {+ expect(() => parseLongMemEvalDataset([entry({ answer_session_ids: ["s-missing"] })])).toThrow(+ /unknown session 's-missing'/,+ );+ });++ test("misaligned haystack arrays are a named error", () => {+ expect(() =>+ parseLongMemEvalDataset([entry({ haystack_dates: ["2026-03-02T10:00:00Z", "2026-03-03"] })]),+ ).toThrow(/aligned/);+ });++ test("an unparseable session date is a named error", () => {+ expect(() => parseLongMemEvalDataset([entry({ haystack_dates: ["not-a-date"] })])).toThrow(+ /valid date/,+ );+ });++ test("a session with the same id but different content is a named error", () => {+ const other = entry({+ q_id: "q2",+ haystack_session: [[{ role: "user", content: "Something entirely different about coffee." }]],+ });+ expect(() => parseLongMemEvalDataset([entry({}), other])).toThrow(/session 's1'/);+ });++ test("a shared session id with per-instance dates parses (first date wins)", () => {+ const dataset = parseLongMemEvalDataset([+ entry({}),+ entry({+ q_id: "q2",+ question_type: "multi-hop",+ haystack_dates: ["2026-09-09T10:00:00Z"],+ }),+ ]);+ // Upstream assigns haystack dates per instance: the same session id+ // carrying a different date in each entry is data, not corruption.+ expect(dataset.entries).toHaveLength(2);+ expect(dataset.entries[1]!.haystack_dates).toEqual(["2026-09-09T10:00:00Z"]);+ });+});++describe("longMemEvalToBenchFixture", () => {+ test("abstention questions are excluded with the count recorded", () => {+ const dataset = parseLongMemEvalDataset([+ entry({}),+ entry({ q_id: "q-abs", question_type: "abstention", answer_session_ids: [] }),+ ]);+ const { fixture, receipt } = longMemEvalToBenchFixture(dataset);+ expect(fixture.questions.map((q) => q.id)).toEqual(["q1"]);+ expect(receipt.abstention_excluded).toBe(1);+ });++ test("gold session ids join directly to the session note paths", () => {+ const dataset = parseLongMemEvalDataset([entry({})]);+ const { fixture } = longMemEvalToBenchFixture(dataset);+ expect(fixture.questions[0]!.expected_paths).toEqual(["sessions/q1/s1.md"]);+ expect(fixture.questions[0]!.top_k).toBe(LONGMEMEVAL_RECALL_CUTOFF);+ });++ test("converted questions never set expected_text (retrieval scoring ignores it)", () => {+ const dataset = parseLongMemEvalDataset([entry({ answer: "Blue Heron" })]);+ const { fixture } = longMemEvalToBenchFixture(dataset);+ for (const question of fixture.questions) {+ expect(question.expected_text).toBeUndefined();+ }+ });++ test("the converted fixture round-trips parseBenchFixture", () => {+ const { fixture } = longMemEvalToBenchFixture(+ parseLongMemEvalDataset([+ entry({}),+ entry({ q_id: "q2", question_type: "multi-hop", answer_session_ids: ["s1"] }),+ ]),+ );+ expect(() => parseBenchFixture(fixture)).not.toThrow();+ });++ test("sessions become notes and session_turn continuity records", () => {+ const { fixture } = longMemEvalToBenchFixture(parseLongMemEvalDataset([entry({})]));+ expect(fixture.notes.map((n) => n.path)).toEqual(["sessions/q1/s1.md"]);+ expect(fixture.continuity).toHaveLength(2);+ for (const record of fixture.continuity) {+ expect(record.kind).toBe("session_turn");+ expect(record.payload["question_id"]).toBe("q1");+ expect(record.payload["session_id"]).toBe("s1");+ expect(typeof record.payload["text"]).toBe("string");+ }+ });++ test("each question's evidence is namespaced under its own subtree", () => {+ // LongMemEval scores every question against ITS OWN haystack, so+ // pooling all entries into one corpus would have each query search+ // the union of all haystacks. The converted notes, continuity and+ // expected_paths of one entry all live under sessions/<q_id>/.+ const shared = [{ role: "user", content: "shared zebra session about quilting." }];+ const dataset = parseLongMemEvalDataset([+ entry({+ q_id: "qA",+ haystack_session_id: ["s1", "shared"],+ haystack_dates: ["2026-03-02T10:00:00Z", "2026-03-02T11:00:00Z"],+ haystack_session: [[{ role: "user", content: "quokka alpha note." }], shared],+ answer_session_ids: ["s1"],+ }),+ entry({+ q_id: "qB",+ question_type: "multi-hop",+ haystack_session_id: ["shared", "s3"],+ haystack_dates: ["2026-03-02T11:00:00Z", "2026-03-03T10:00:00Z"],+ haystack_session: [shared, [{ role: "user", content: "wombat beta note." }]],+ answer_session_ids: ["s3"],+ }),+ ]);+ const { fixture } = longMemEvalToBenchFixture(dataset);+ for (const question of fixture.questions) {+ for (const path of question.expected_paths!) {+ expect(path.startsWith(`sessions/${question.id}/`)).toBe(true);+ }+ }+ const notePaths = fixture.notes.map((n) => n.path);+ expect(notePaths).toContain("sessions/qA/s1.md");+ expect(notePaths).toContain("sessions/qA/shared.md");+ expect(notePaths).toContain("sessions/qB/s3.md");+ expect(notePaths).toContain("sessions/qB/shared.md");+ // A session shared by two entries exists once per scope, and its+ // continuity records name the question that produced them.+ const sharedRecords = fixture.continuity.filter((r) => r.payload["session_id"] === "shared");+ expect(sharedRecords.map((r) => r.payload["question_id"]).sort()).toEqual(["qA", "qB"]);+ });++ test("distinct question ids that sanitize to one scope are a named error", () => {+ const dataset = parseLongMemEvalDataset([+ entry({ q_id: "q/1" }),+ entry({ q_id: "q-1", question_type: "multi-hop" }),+ ]);+ expect(() => longMemEvalToBenchFixture(dataset)).toThrow(/same path scope/);+ });++ test("a duplicate question id is a named error", () => {+ const dataset = parseLongMemEvalDataset([entry({}), entry({})]);+ expect(() => longMemEvalToBenchFixture(dataset)).toThrow(/appears twice/);+ });++ test("converted questions carry the suite judge input", () => {+ const { fixture } = longMemEvalToBenchFixture(+ parseLongMemEvalDataset([entry({ answer: "Blue Heron" })]),+ );+ expect(fixture.questions[0]!.judge_input).toEqual({+ question: "launch codename",+ answer: "Blue Heron",+ gold: ["s1"],+ });+ });++ test("a question without a stated reference answer omits the judge answer field", () => {+ const { fixture } = longMemEvalToBenchFixture(parseLongMemEvalDataset([entry({})]));+ expect(fixture.questions[0]!.judge_input).toBeDefined();+ expect(fixture.questions[0]!.judge_input!.answer).toBeUndefined();+ expect(fixture.questions[0]!.judge_input!.gold).toEqual(["s1"]);+ });+});++describe("the judge prompts", () => {+ test("the prompt constants state their self-written provenance", () => {+ expect(LONGMEMEVAL_PROMPT_PROVENANCE).toContain("self-written");+ expect(LONGMEMEVAL_PROMPT_PROVENANCE).toContain("github.com/xiaowu0162/LongMemEval");+ expect(LONGMEMEVAL_PROMPT_PROVENANCE).toContain("evaluate_qa.py");+ // No pretense of an upstream transcription or a revision pin.+ expect(LONGMEMEVAL_PROMPT_PROVENANCE.toLowerCase()).not.toContain("pinned");+ });++ test("the system prompt and question template cover the payload fields", () => {+ expect(LONGMEMEVAL_JUDGE_SYSTEM_PROMPT).toContain("evidence");+ expect(LONGMEMEVAL_JUDGE_QUESTION_TEMPLATE).toContain("{question}");+ expect(LONGMEMEVAL_JUDGE_QUESTION_TEMPLATE).toContain("{answer}");+ expect(LONGMEMEVAL_JUDGE_QUESTION_TEMPLATE).toContain("{gold}");+ });+});++describe("date parsing", () => {+ test("official slash dates derive UTC turn timestamps, not host-local ones", () => {+ const dataset = parseLongMemEvalDataset([+ entry({+ haystack_dates: ["2023/05/20 (Sat) 02:21"],+ haystack_session: [[{ role: "user", content: "zebra anchor." }]],+ }),+ ]);+ const { fixture } = longMemEvalToBenchFixture(dataset);+ // Host-local parsing shifts this by the zone offset; UTC pins it.+ expect(fixture.continuity[0]!.created_at).toBe("2023-05-20T02:21:00.000Z");+ });++ test("the committed official sample derives UTC turn timestamps", () => {+ const raw: unknown = JSON.parse(readFileSync(OFFICIAL_SAMPLE, "utf8"));+ const { fixture } = longMemEvalToBenchFixture(parseLongMemEvalDataset(raw));+ expect(fixture.continuity[0]!.created_at).toBe("2023-05-01T09:15:00.000Z");+ });++ test("a naive ISO date-time is read as UTC, not host-local", () => {+ const dataset = parseLongMemEvalDataset([entry({ haystack_dates: ["2026-03-02T10:00:00"] })]);+ const { fixture } = longMemEvalToBenchFixture(dataset);+ expect(fixture.continuity[0]!.created_at).toBe("2026-03-02T10:00:00.000Z");+ });++ test("a date form only the host zone could interpret is a named error", () => {+ expect(() => parseLongMemEvalDataset([entry({ haystack_dates: ["May 20, 2023"] })])).toThrow(+ /valid date/,+ );+ });+});++describe("answer coercion", () => {+ test("numeric answers are coerced to strings for the judge payload", () => {+ const dataset = parseLongMemEvalDataset([+ entry({ answer: 42 }),+ entry({ q_id: "q2", question_type: "multi-hop", answer: 0 }),+ ]);+ const { fixture } = longMemEvalToBenchFixture(dataset);+ expect(fixture.questions[0]!.judge_input!.answer).toBe("42");+ expect(fixture.questions[1]!.judge_input!.answer).toBe("0");+ });++ test("other non-string answer types stay refused", () => {+ const dataset = parseLongMemEvalDataset([entry({ answer: true })]);+ const { fixture } = longMemEvalToBenchFixture(dataset);+ expect(fixture.questions[0]!.judge_input!.answer).toBeUndefined();+ });+});++describe("scoreLongMemEvalRecall", () => {+ const QUESTIONS = [+ {+ id: "q-both",+ category: "multi_evidence" as const,+ query: "q",+ top_k: 5,+ expected_paths: ["sessions/a.md", "sessions/b.md"],+ },+ {+ id: "q-missing",+ category: "single_hop" as const,+ query: "q",+ top_k: 5,+ expected_paths: ["sessions/a.md", "sessions/z.md"],+ },+ {+ id: "q-outside",+ category: "single_hop" as const,+ query: "q",+ top_k: 5,+ expected_paths: ["sessions/far.md"],+ },+ ];++ test("passes a question only when every gold note ranks inside the cutoff", () => {+ const retrieved = [+ { id: "q-both", paths: ["sessions/b.md", "sessions/a.md", "sessions/c.md"] },+ {+ id: "q-missing",+ paths: [+ "sessions/a.md",+ "sessions/b.md",+ "sessions/c.md",+ "sessions/d.md",+ "sessions/e.md",+ ],+ },+ {+ id: "q-outside",+ paths: [+ "sessions/a.md",+ "sessions/b.md",+ "sessions/c.md",+ "sessions/d.md",+ "sessions/e.md",+ "sessions/far.md",+ ],+ },+ ];+ // q-missing never surfaces sessions/z.md; q-outside's gold note sits+ // one rank past the strict cutoff. Exactly one question passes.+ expect(scoreLongMemEvalRecall(QUESTIONS, retrieved)).toEqual({ scored: 3, passed: 1 });+ });++ test("a question with no persisted result scores as a miss, never a pass", () => {+ expect(scoreLongMemEvalRecall(QUESTIONS, [])).toEqual({ scored: 3, passed: 0 });+ });++ test("non-retrieval questions are not scored", () => {+ const mixed = [+ ...QUESTIONS,+ { id: "q-handoff", category: "session_handoff" as const, session_id: "s1" },+ ];+ const scored = scoreLongMemEvalRecall(mixed, []);+ expect(scored.scored).toBe(3);+ });+});++describe("the longmemeval suite", () => {+ test("is registered with the embeddings capability", () => {+ const registration = benchSuite("longmemeval");+ expect(registration).toBeDefined();+ expect(registration!.capabilities).toEqual({ embeddings: true });+ expect(typeof registration!.loader).toBe("function");+ });++ test("the loader converts the committed sample with its receipt", () => {+ const { fixture, receipt } = loadLongMemEvalFixture(SAMPLE);+ expect(fixture.name).toBe("longmemeval-sample");+ expect(fixture.questions).toHaveLength(3);+ expect(receipt.abstention_excluded).toBe(1);+ });++ test("the loader converts the committed official-shape sample with its receipt", () => {+ const { fixture, receipt } = loadLongMemEvalFixture(OFFICIAL_SAMPLE);+ expect(fixture.name).toBe("longmemeval-suite");+ expect(fixture.questions).toHaveLength(2);+ expect(receipt.abstention_excluded).toBe(1);+ for (const question of fixture.questions) {+ expect(question.expected_paths!.every((p) => p.startsWith(`sessions/${question.id}/`))).toBe(+ true,+ );+ }+ });++ test("the official-shape sample runs end to end with the strict family", async () => {+ const { fixture, receipt } = loadLongMemEvalFixture(OFFICIAL_SAMPLE);+ const runsDir = mkdtempSync(join(tmpdir(), "o2b-longmemeval-runs-"));+ dirs.push(runsDir);+ const report = await runMemoryBench({+ fixture,+ runsDir,+ suite: "longmemeval",+ suiteReceipt: receipt,+ capabilities: { embeddings: true },+ // The official questions are natural sentences; the deterministic+ // local provider matches them to their haystack notes, which is+ // the lane the suite exists for.+ pinnedKnobs: { semantic: { enabled: true, provider: "local" } },+ });+ expect(report.embeddings).toBeDefined();+ expect(report.quality.passed).toBe(report.quality.total);+ expect(report.longmemeval).toEqual({ recall_all_at_5: 1, abstention_excluded: 1 });+ }, 30_000);++ test("the keyword-only default pin matches nothing for natural official questions", async () => {+ const { fixture, receipt } = loadLongMemEvalFixture(OFFICIAL_SAMPLE);+ const runsDir = mkdtempSync(join(tmpdir(), "o2b-longmemeval-runs-"));+ dirs.push(runsDir);+ const report = await runMemoryBench({+ fixture,+ runsDir,+ suite: "longmemeval",+ suiteReceipt: receipt,+ });+ // The keyword lane requires every query token to hit, so a natural+ // question scores zero notes - this is why the suite declares the+ // embeddings capability, and the report says so rather than+ // manufacturing a passing number.+ expect(report.longmemeval).toEqual({ recall_all_at_5: 0, abstention_excluded: 1 });+ expect(report.quality.passed).toBe(0);+ }, 30_000);++ test("running the committed sample produces a green report with the judge skipped", async () => {+ const { fixture } = loadLongMemEvalFixture(SAMPLE);+ const runsDir = mkdtempSync(join(tmpdir(), "o2b-longmemeval-runs-"));+ dirs.push(runsDir);+ const report = await runMemoryBench({ fixture, runsDir });+ expect(report.schema).toBe(BENCH_REPORT_SCHEMA);+ expect(report.fixture).toBe("longmemeval-sample");+ expect(report.judge.status).toBe("skipped");+ // Keyword-distinctive queries over a small haystack: all retrieval+ // questions find their gold sessions inside the recall cutoff.+ expect(report.quality.passed).toBe(report.quality.total);+ expect(report.quality.total).toBe(3);+ }, 30_000);++ test("the suite runs the embeddings capability path end to end", async () => {+ const { fixture } = loadLongMemEvalFixture(SAMPLE);+ const runsDir = mkdtempSync(join(tmpdir(), "o2b-longmemeval-runs-"));+ dirs.push(runsDir);+ const report = await runMemoryBench({+ fixture,+ runsDir,+ capabilities: { embeddings: true },+ pinnedKnobs: { semantic: { enabled: true, provider: "local" } },+ });+ expect(report.embeddings).toBeDefined();+ expect(report.embeddings!.provider).toBe("local");+ expect(report.embeddings!.gate).toEqual({ blocked: false, reason: null });+ expect(report.judge.status).toBe("skipped");+ expect(report.quality.passed).toBe(report.quality.total);+ }, 30_000);++ test("a second identical vault is served by the shared vector cache", async () => {+ const { fixture } = loadLongMemEvalFixture(SAMPLE);+ const runsDir = mkdtempSync(join(tmpdir(), "o2b-longmemeval-runs-"));+ dirs.push(runsDir);+ // Two disposable vaults, same content, one shared runs-dir cache:+ // the first arm pays the full census through the misses path, the+ // second is served whole - the cache-hit contract the pending+ // lookup exists for.+ const vaultA = mkdtempSync(join(tmpdir(), "o2b-longmemeval-vault-"));+ const vaultB = mkdtempSync(join(tmpdir(), "o2b-longmemeval-vault-"));+ dirs.push(vaultA, vaultB);+ materializeBenchVault(fixture, vaultA);+ materializeBenchVault(fixture, vaultB);+ const pin: BenchPinnedKnobs = { semantic: { enabled: true, provider: "local" } };+ const first = await embedBenchVaultIndex({+ config: benchSearchConfig(vaultA, pin),+ runsDir,+ });+ expect(first.cache_hits).toBe(0);+ expect(first.cache_misses).toBeGreaterThan(0);+ const second = await embedBenchVaultIndex({+ config: benchSearchConfig(vaultB, pin),+ runsDir,+ });+ expect(second.cache_hits).toBe(first.cache_misses);+ expect(second.cache_misses).toBe(0);+ }, 30_000);++ test("a suite run surfaces the strict recall_all@5 family with the exclusion count", async () => {+ const { fixture, receipt } = loadLongMemEvalFixture(SAMPLE);+ const runsDir = mkdtempSync(join(tmpdir(), "o2b-longmemeval-runs-"));+ dirs.push(runsDir);+ const report = await runMemoryBench({+ fixture,+ runsDir,+ suite: "longmemeval",+ suiteReceipt: receipt,+ });+ // The sample's three retrieval questions all find their gold+ // sessions inside the cutoff; one abstention question was excluded.+ expect(report.longmemeval).toEqual({ recall_all_at_5: 1, abstention_excluded: 1 });+ }, 30_000);++ test("without a suite receipt the exclusion count is null, never a manufactured 0", async () => {+ const { fixture } = loadLongMemEvalFixture(SAMPLE);+ const runsDir = mkdtempSync(join(tmpdir(), "o2b-longmemeval-runs-"));+ dirs.push(runsDir);+ const report = await runMemoryBench({ fixture, runsDir, suite: "longmemeval" });+ // A direct caller that skips the conversion receipt must not get a+ // report asserting zero exclusions: unknown is null, and a reader+ // can tell the two apart.+ expect(report.longmemeval).toEqual({ recall_all_at_5: 1, abstention_excluded: null });+ }, 30_000);++ test("the report family stays absent without the suite name", async () => {+ const { fixture } = loadLongMemEvalFixture(SAMPLE);+ const runsDir = mkdtempSync(join(tmpdir(), "o2b-longmemeval-runs-"));+ dirs.push(runsDir);+ const report = await runMemoryBench({ fixture, runsDir });+ expect(report.longmemeval).toBeUndefined();+ }, 30_000);++ // The judge command runs under the platform shell (sh on POSIX,+ // cmd.exe on Windows), so the fake judge avoids shell operators+ // entirely: the test writes a script and passes both paths as+ // quoted, forward-slashed arguments.+ function writeFakeJudgeScript(runsDir: string): string {+ const script = join(runsDir, "fake-judge.mjs");+ writeFileSync(+ script,+ [+ 'import { writeFileSync } from "node:fs";',+ "const chunks = [];",+ "for await (const chunk of Bun.stdin.stream()) chunks.push(chunk);",+ 'const text = Buffer.concat(chunks).toString("utf8");',+ "writeFileSync(process.argv[2], text);",+ "const parsed = JSON.parse(text);",+ "const verdicts = {};",+ "for (const q of parsed.questions) verdicts[q.id] = true;",+ "console.log(JSON.stringify({ verdicts }));",+ "",+ ].join("\n"),+ );+ return script;+ }+ const shellSafe = (path: string) => `"${path.replaceAll("\\", "/")}"`;++ test("a fake judge receives question, answer and gold and its verdicts land", async () => {+ const { fixture } = loadLongMemEvalFixture(SAMPLE);+ const runsDir = mkdtempSync(join(tmpdir(), "o2b-longmemeval-runs-"));+ dirs.push(runsDir);+ const stdinCapture = join(runsDir, "judge-stdin.json");+ // The external judge stays a dumb command: capture the payload, then+ // echo a true verdict for every question id it received.+ const judgeCmd = `bun ${shellSafe(writeFakeJudgeScript(runsDir))} ${shellSafe(stdinCapture)}`;+ const report = await runMemoryBench({ fixture, runsDir, judgeCmd });+ expect(report.judge.status).toBe("ran");+ for (const question of report.questions) {+ expect(question.judge_pass).toBe(true);+ }+ const payload = JSON.parse(readFileSync(stdinCapture, "utf8")) as {+ questions: Array<Record<string, unknown>>;+ };+ expect(payload.questions).toHaveLength(3);+ // Judged questions carry the evidence the run actually injected, so+ // the judge can evaluate against what the system showed.+ const withEvidence = payload.questions.find(+ (q) => Array.isArray(q["evidence"]) && (q["evidence"] as unknown[]).length > 0,+ );+ expect(withEvidence).toBeDefined();+ for (const entry of withEvidence!["evidence"] as Array<Record<string, unknown>>) {+ expect(typeof entry["path"]).toBe("string");+ expect(typeof entry["text"]).toBe("string");+ }+ for (const payloadEntry of payload.questions) {+ expect(typeof payloadEntry["question"]).toBe("string");+ expect(Array.isArray(payloadEntry["gold"])).toBe(true);+ expect((payloadEntry["gold"] as ReadonlyArray<string>).length).toBeGreaterThan(0);+ }+ // The sample states a reference answer for at least its first+ // question; the payload carries it verbatim.+ const withAnswer = payload.questions.find((q) => typeof q["answer"] === "string");+ expect(withAnswer).toBeDefined();+ }, 20_000);++ test("a suite without judge input keeps the judge payload unchanged", async () => {+ const native = parseBenchFixture({+ name: "judge-payload-default",+ notes: [{ path: "Brain/notes/a.md", body: "alpha note" }],+ continuity: [],+ questions: [+ { id: "q1", category: "single_hop", query: "alpha", expected_paths: ["Brain/notes/a.md"] },+ ],+ });+ const runsDir = mkdtempSync(join(tmpdir(), "o2b-longmemeval-runs-"));+ dirs.push(runsDir);+ const stdinCapture = join(runsDir, "judge-stdin.json");+ const judgeCmd = `bun ${shellSafe(writeFakeJudgeScript(runsDir))} ${shellSafe(stdinCapture)}`;+ const report = await runMemoryBench({ fixture: native, runsDir, judgeCmd });+ expect(report.judge.status).toBe("ran");+ const payload = JSON.parse(readFileSync(stdinCapture, "utf8")) as {+ questions: Array<Record<string, unknown>>;+ };+ expect(payload.questions).toHaveLength(1);+ // No suite-provided judge input: no question, answer or gold fields.+ const first = payload.questions[0]!;+ expect("question" in first).toBe(false);+ expect("answer" in first).toBe(false);+ expect("gold" in first).toBe(false);+ }, 20_000);+});diff --git a/tests/core/bench/phases.test.ts b/tests/core/bench/phases.test.tsindex d51241d2..ceaf2c59 100644--- a/tests/core/bench/phases.test.ts+++ b/tests/core/bench/phases.test.ts@@ -7,13 +7,24 @@*/import { afterEach, beforeEach, describe, expect, test } from "bun:test";-import { existsSync, mkdtempSync, readFileSync, rmSync } from "node:fs";+import { existsSync, mkdtempSync, readdirSync, readFileSync, rmSync, writeFileSync } from "node:fs";import { tmpdir } from "node:os";import { join } from "node:path";+import {+ benchEmbeddingSignature,+ benchVectorCacheKey,+} from "../../../src/core/bench/embedding-cache.ts";import { parseBenchFixture } from "../../../src/core/bench/fixture.ts";-import { runMemoryBench } from "../../../src/core/bench/phases.ts";-import { BENCH_REPORT_SCHEMA } from "../../../src/core/bench/types.ts";+import { FAKE_PROVIDER_KEY } from "../../helpers/fake-credentials.ts";+import { benchSearchConfig, runMemoryBench } from "../../../src/core/bench/phases.ts";+import {+ BENCH_REPORT_SCHEMA,+ DEFAULT_BENCH_KNOB_PIN,+ type BenchPinnedKnobs,+} from "../../../src/core/bench/types.ts";+import { LOCAL_DEFAULT_DIMENSION } from "../../../src/core/search/embeddings/local-provider.ts";+import { LOCAL_EMBEDDING_MODEL } from "../../../src/core/search/embeddings/signature.ts";let runsDir: string;@@ -101,6 +112,13 @@ const FIXTURE = parseBenchFixture({});describe("runMemoryBench", () => {+ test("the default bench config pins the semantic lane off", () => {+ // The resolved config is where network-freedom is real: the pin must+ // hold whatever the surrounding environment configures.+ const config = benchSearchConfig(runsDir);+ expect(config.semantic.enabled).toBe(false);+ });+test("full pipeline produces a diffable report with separate metric families", async () => {const report = await runMemoryBench({ fixture: FIXTURE, runsDir });expect(report.schema).toBe(BENCH_REPORT_SCHEMA);@@ -115,6 +133,9 @@ describe("runMemoryBench", () => {expect(report.context_cost.avg_chars).toBeGreaterThan(0);expect(report.context_cost.avg_injected_tokens).toBeGreaterThan(0);expect(report.judge.status).toBe("skipped");+ // No suite is named, so no suite report family may appear: the+ // default path stays byte-identical.+ expect(report.longmemeval).toBeUndefined();// Stable question order by id for diffability.expect(report.questions.map((q) => q.id)).toEqual(report.questions.map((q) => q.id).toSorted());// report.json lands in the run directory.@@ -183,4 +204,243 @@ describe("runMemoryBench", () => {runMemoryBench({ fixture: changed, runsDir, resume: first.run_id }),).rejects.toThrow("hash");}, 30_000);++ test("the default knob pin equals today's hardcoded semantic-off override", () => {+ expect(DEFAULT_BENCH_KNOB_PIN).toEqual({ semantic: { enabled: false } });+ });++ test("pinned knobs are applied last and win over env and config", () => {+ const pin: BenchPinnedKnobs = {+ keywordWeight: 0.6,+ semantic: { enabled: false, provider: "local" },+ };+ const config = benchSearchConfig(runsDir, pin);+ expect(config.keywordWeight).toBe(0.6);+ expect(config.semantic.enabled).toBe(false);+ expect(config.semantic.provider).toBe("local");+ });++ test("two runs with different knob pins get different run ids", async () => {+ const first = await runMemoryBench({+ fixture: FIXTURE,+ runsDir,+ pinnedKnobs: { semantic: { enabled: false }, keywordWeight: 0.6 },+ });+ const second = await runMemoryBench({+ fixture: FIXTURE,+ runsDir,+ pinnedKnobs: { semantic: { enabled: false }, keywordWeight: 0.5 },+ });+ expect(first.run_id).not.toBe(second.run_id);+ }, 30_000);++ test("resume with a changed knob pin fails fast on the identity guard", async () => {+ const first = await runMemoryBench({ fixture: FIXTURE, runsDir });+ await expect(+ runMemoryBench({+ fixture: FIXTURE,+ runsDir,+ resume: first.run_id,+ pinnedKnobs: { semantic: { enabled: false }, keywordWeight: 0.6 },+ }),+ ).rejects.toThrow(/run identity mismatch/);+ }, 30_000);++ test("resume with the same explicit pin reuses the run", async () => {+ const pin: BenchPinnedKnobs = { semantic: { enabled: false }, keywordWeight: 0.6 };+ const first = await runMemoryBench({ fixture: FIXTURE, runsDir, pinnedKnobs: pin });+ const resumed = await runMemoryBench({+ fixture: FIXTURE,+ runsDir,+ resume: first.run_id,+ pinnedKnobs: pin,+ });+ expect(resumed.run_id).toBe(first.run_id);+ expect(resumed.quality).toEqual(first.quality);+ }, 30_000);++ test("an out-of-range recallFloor is refused by name before any run starts", async () => {+ // Each of these used to finish a FULL run: the floor routes into the+ // shared surfacing calculator, whose own contract refuses out-of-range+ // values per question, so the report came back complete with a+ // retrievalError on every proactive decision - paid after ingest and+ // index, instead of one named error up front (pr-250 review, L9).+ for (const floor of [-1, 1.5, Number.POSITIVE_INFINITY, Number.NaN]) {+ await expect(+ runMemoryBench({ fixture: FIXTURE, runsDir, recallFloor: floor }),+ ).rejects.toThrow(/recallFloor .* is outside \[0, 1\]/);+ }+ // Refused before any run state exists.+ expect(readdirSync(runsDir)).toHaveLength(0);+ // The interval's ends are legal calibration points: zero is the+ // maximally permissive sweep arm, one admits only a perfect match.+ await expect(+ runMemoryBench({ fixture: FIXTURE, runsDir, recallFloor: 1 }),+ ).resolves.toBeDefined();+ }, 60_000);+});++describe("the embeddings capability path", () => {+ // Lexically disjoint notes, so the semantic lane cannot reorder a gold+ // path below an unrelated one and the assertions stay about the+ // capability machinery, not about fusion tuning.+ const SEMANTIC_FIXTURE = parseBenchFixture({+ name: "embedding-capability",+ notes: [+ {+ path: "Brain/notes/rust.md",+ body: "# Systems language\n\nThe systems team standardized on Rust for the new ingest service. Rust ownership keeps the parser safe.\n",+ },+ {+ path: "Brain/notes/piano.md",+ body: "# Evening hobby\n\nThe operator practices piano on weekends and prefers nocturnes. Piano practice happens after dinner.\n",+ },+ ],+ continuity: [],+ questions: [+ {+ id: "q-rust",+ category: "single_hop",+ query: "systems programming language for the ingest service",+ top_k: 5,+ expected_paths: ["Brain/notes/rust.md"],+ },+ {+ id: "q-piano",+ category: "single_hop",+ query: "weekend instrument hobby",+ top_k: 5,+ expected_paths: ["Brain/notes/piano.md"],+ },+ ],+ });+ const CAPABILITIES = { embeddings: true } as const;+ const SEMANTIC_PIN: BenchPinnedKnobs = { semantic: { enabled: true, provider: "local" } };++ test("a semantic pin without the embeddings capability is a named error", async () => {+ await expect(+ runMemoryBench({ fixture: SEMANTIC_FIXTURE, runsDir, pinnedKnobs: SEMANTIC_PIN }),+ ).rejects.toThrow(/embeddings capability/);+ }, 30_000);++ test("a blocked embedding spend gate is refused by name, never bypassed", async () => {+ const pin: BenchPinnedKnobs = {+ semantic: {+ enabled: true,+ provider: "openai-compat",+ baseUrl: "http://127.0.0.1:9",+ model: "bench-unpriced-model",+ apiKey: FAKE_PROVIDER_KEY,+ costGateUsd: 1,+ },+ };+ // The unpriced model under a positive gate is refused before any+ // provider contact: the run fails loudly instead of embedding anyway.+ await expect(+ runMemoryBench({+ fixture: SEMANTIC_FIXTURE,+ runsDir,+ capabilities: CAPABILITIES,+ pinnedKnobs: pin,+ }),+ ).rejects.toThrow(/spend gate/);+ }, 30_000);++ test("the capability builds the index through the apply gate and surfaces the spend plan", async () => {+ const report = await runMemoryBench({+ fixture: SEMANTIC_FIXTURE,+ runsDir,+ capabilities: CAPABILITIES,+ pinnedKnobs: SEMANTIC_PIN,+ });+ expect(report.quality.passed).toBe(report.quality.total);+ const receipt = report.embeddings;+ expect(receipt).toBeDefined();+ expect(receipt!.provider).toBe("local");+ expect(receipt!.model).toBe(LOCAL_EMBEDDING_MODEL);+ expect(receipt!.signature).toBe(`local:${LOCAL_EMBEDDING_MODEL}:${LOCAL_DEFAULT_DIMENSION}::`);+ expect(receipt!.planned).toBeGreaterThan(0);+ expect(receipt!.cache_hits).toBe(0);+ expect(receipt!.cache_misses).toBe(receipt!.planned);+ expect(receipt!.gate).toEqual({ blocked: false, reason: null });+ // The surfaced plan lands as a run artifact beside report.json.+ const receiptOnDisk = JSON.parse(+ readFileSync(join(runsDir, report.run_id, "embeddings.json"), "utf8"),+ ) as Record<string, unknown>;+ expect(receiptOnDisk).toEqual(receipt as unknown as Record<string, unknown>);+ // The shared cache lives under the runs dir, entries keyed by+ // provider, model, dimension and text hash.+ const cache = JSON.parse(readFileSync(join(runsDir, "embedding-cache.json"), "utf8")) as {+ entries: Record<string, ReadonlyArray<number>>;+ };+ const keys = Object.keys(cache.entries);+ expect(keys.length).toBeGreaterThan(0);+ const keyPattern = new RegExp(`^${receipt!.signature}\\|[0-9a-f]{64}$`);+ for (const key of keys) {+ expect(key).toMatch(keyPattern);+ expect(cache.entries[key]!.length).toBe(LOCAL_DEFAULT_DIMENSION);+ }+ }, 30_000);++ test("vector cache keys differ when only the prefix pins differ", () => {+ // The stored bytes depend on the prefixes the provider prepends, so+ // two arms that differ only in prefix pins must never share an entry.+ const base = benchEmbeddingSignature("local", "m", 384, "", "");+ const prefixed = benchEmbeddingSignature("local", "m", 384, "search: ", "passage: ");+ expect(base).not.toBe(prefixed);+ expect(benchVectorCacheKey(base, "same text")).not.toBe(+ benchVectorCacheKey(prefixed, "same text"),+ );+ // Case and surrounding whitespace canonicalize away, as everywhere+ // else the signature tokens are compared.+ expect(benchEmbeddingSignature("Local", "m", 384, "", "")).toBe(base);+ });++ test("a second arm reuses the shared cache and stores byte-identical vectors", async () => {+ const t0 = new Date("2026-06-01T00:00:00.000Z");+ const first = await runMemoryBench({+ fixture: SEMANTIC_FIXTURE,+ runsDir,+ capabilities: CAPABILITIES,+ pinnedKnobs: SEMANTIC_PIN,+ now: t0,+ });+ const cacheAfterFirst = readFileSync(join(runsDir, "embedding-cache.json"), "utf8");+ const second = await runMemoryBench({+ fixture: SEMANTIC_FIXTURE,+ runsDir,+ capabilities: CAPABILITIES,+ pinnedKnobs: SEMANTIC_PIN,+ now: new Date(t0.getTime() + 60_000),+ });+ expect(second.run_id).not.toBe(first.run_id);+ expect(second.embeddings!.cache_misses).toBe(0);+ expect(second.embeddings!.cache_hits).toBe(first.embeddings!.planned);+ // Arm 2 rewrote the cache from its own store read-back: identical+ // bytes prove the stored vectors equal arm 1's, element for element.+ expect(readFileSync(join(runsDir, "embedding-cache.json"), "utf8")).toBe(cacheAfterFirst);+ }, 30_000);++ test("a shared cache written under another schema is refused, never honored", async () => {+ const cachePath = join(runsDir, "embedding-cache.json");+ const run = () =>+ runMemoryBench({+ fixture: SEMANTIC_FIXTURE,+ runsDir,+ capabilities: CAPABILITIES,+ pinnedKnobs: SEMANTIC_PIN,+ });+ writeFileSync(+ cachePath,+ `${JSON.stringify({ schema: "some.other.vectors.v9", entries: {} }, null, 2)}\n`,+ "utf8",+ );+ await expect(run()).rejects.toThrow(+ /schema 'some\.other\.vectors\.v9', expected 'o2b\.bench\.vectors\.v1'/,+ );+ // Every writer stamps the schema, so a missing one is foreign state+ // too - not an older generation to silently adopt.+ writeFileSync(cachePath, `${JSON.stringify({ entries: {} }, null, 2)}\n`, "utf8");+ await expect(run()).rejects.toThrow(/schema 'undefined'/);+ }, 30_000);});diff --git a/tests/core/bench/replay-fixture.test.ts b/tests/core/bench/replay-fixture.test.tsnew file mode 100644index 00000000..6749571f--- /dev/null+++ b/tests/core/bench/replay-fixture.test.ts@@ -0,0 +1,296 @@+/**+ * Replay fixture loader (t_107a3249, lane C Task 15).+ *+ * The loader is PURE and deterministic: a committed session-shaped JSON+ * becomes an ordered prompt sequence with expected surfacing outcomes,+ * and a vault's own `session_turn` records convert into the same shape.+ * The expected-outcome vocabulary is closed; anything else is a named+ * rejection, never a silent default expectation.+ */++import { expect, test } from "bun:test";+import { join } from "node:path";++import type { ContinuityRecord } from "../../../src/core/brain/continuity/types.ts";+import {+ loadReplayFixture,+ parseReplayFixture,+ REPLAY_EXPECTATIONS,+ REPLAY_EXPECTATION,+ sessionTurnsToReplayFixture,+ ReplayFixtureError,+} from "../../../src/core/bench/replay-fixture.ts";++/** Same repo-relative convention as `locomo.test.ts`'s SAMPLE path. */+const SAMPLE_PATH = join("tests", "fixtures", "bench", "surfacing-replay-sample.json");++function sessionTurn(overrides: Partial<ContinuityRecord> & { id: string }): ContinuityRecord {+ return {+ kind: "session_turn",+ createdAt: "2026-06-01T00:00:00.000Z",+ sourceRefs: [],+ payload: { role: "user", text: "a recorded prompt" },+ private: false,+ redacted: false,+ ...overrides,+ };+}++test("the committed sample loads into an ordered prompt sequence with expectations", () => {+ const fixture = loadReplayFixture(SAMPLE_PATH);+ expect(fixture.name).toBe("surfacing-replay-sample");+ expect(fixture.prompts.map((p) => p.id)).toEqual(["turn-1", "turn-2", "turn-3", "turn-4"]);+ expect(fixture.prompts.map((p) => p.expectInject)).toEqual([true, true, false, false]);+ // Order is the session's order, and each prompt carries the text of the+ // one before it, which is what duplicate detection reads.+ expect(fixture.prompts[0]!.previousText).toBeNull();+ expect(fixture.prompts[1]!.previousText).toBe("billing migration");+ expect(fixture.prompts[2]!.text).toBe("billing-migration");+});++test("the loader is deterministic: the same file parses to an equal fixture twice", () => {+ expect(loadReplayFixture(SAMPLE_PATH)).toEqual(loadReplayFixture(SAMPLE_PATH));+});++test("parse keeps declared order and maps the closed expectation vocabulary", () => {+ const fixture = parseReplayFixture({+ name: "tiny",+ notes: [{ path: "notes/a.md", body: "Atlas launch checklist" }],+ turns: [+ { id: "a", text: "Who owns the billing migration?", expect: "inject" },+ { id: "b", text: "/help", expect: "abstain" },+ ],+ });+ expect(fixture.prompts).toHaveLength(2);+ expect(fixture.prompts[0]).toEqual({+ id: "a",+ text: "Who owns the billing migration?",+ previousText: null,+ expectInject: true,+ });+ expect(fixture.prompts[1]!.previousText).toBe("Who owns the billing migration?");+});++test("an unknown expectation is a named rejection carrying the turn id and value", () => {+ expect(() =>+ parseReplayFixture({+ name: "tiny",+ notes: [],+ turns: [{ id: "a", text: "hello", expect: "maybe" }],+ }),+ ).toThrow(ReplayFixtureError);+ expect(() =>+ parseReplayFixture({+ name: "tiny",+ notes: [],+ turns: [{ id: "a", text: "hello", expect: "maybe" }],+ }),+ ).toThrow(/turn 'a'.*'maybe'/);+});++test("a turn missing an expectation is rejected, never defaulted", () => {+ expect(() =>+ parseReplayFixture({ name: "tiny", notes: [], turns: [{ id: "a", text: "hello" }] }),+ ).toThrow(/turn 'a'.*expect/);+});++test("duplicate turn ids are rejected", () => {+ expect(() =>+ parseReplayFixture({+ name: "tiny",+ notes: [],+ turns: [+ { id: "a", text: "one", expect: "inject" },+ { id: "a", text: "two", expect: "abstain" },+ ],+ }),+ ).toThrow(/duplicate turn id 'a'/);+});++test("a fixture needs a name and at least one turn; notes may be empty", () => {+ expect(() =>+ parseReplayFixture({ name: "", notes: [], turns: [{ id: "a", text: "x", expect: "inject" }] }),+ ).toThrow(/name/);+ expect(() => parseReplayFixture({ name: "tiny", notes: [], turns: [] })).toThrow(/turns/);+ expect(+ parseReplayFixture({+ name: "tiny",+ notes: [],+ turns: [{ id: "a", text: "x", expect: "abstain" }],+ }).prompts,+ ).toHaveLength(1);+});++test("the expectation vocabulary is closed and exported for consumers", () => {+ expect(REPLAY_EXPECTATIONS).toEqual([REPLAY_EXPECTATION.inject, REPLAY_EXPECTATION.abstain]);+});++test("session_turn records convert into the same fixture shape, chronologically", () => {+ // Deliberately out of chronological order in, chronological order out.+ const records = [+ sessionTurn({+ id: "r2",+ createdAt: "2026-06-02T00:00:00.000Z",+ payload: { role: "user", text: "second prompt" },+ }),+ sessionTurn({+ id: "r1",+ createdAt: "2026-06-01T00:00:00.000Z",+ payload: { role: "user", text: "first prompt" },+ }),+ ];+ const fixture = sessionTurnsToReplayFixture({+ name: "from-vault",+ records,+ expectations: { r1: "inject", r2: "abstain" },+ });+ expect(fixture.name).toBe("surfacing-replay-from-vault");+ expect(fixture.prompts.map((p) => [p.id, p.text, p.expectInject])).toEqual([+ ["r1", "first prompt", true],+ ["r2", "second prompt", false],+ ]);+ expect(fixture.prompts[1]!.previousText).toBe("first prompt");+});++test("ordering follows the turn timestamp, not the import-time createdAt", () => {+ // One import writes a whole session at once, so createdAt ties across a+ // session and can even disagree with the conversation's own order. The+ // turn's payload.timestamp is the conversation's order; these two+ // records are deliberately ordered oppositely by the two clocks.+ const records = [+ sessionTurn({+ id: "r-alpha",+ createdAt: "2026-06-01T00:00:00.000Z",+ payload: { role: "user", text: "alpha", timestamp: "2026-06-03T00:00:00.000Z" },+ }),+ sessionTurn({+ id: "r-beta",+ createdAt: "2026-06-02T00:00:00.000Z",+ payload: { role: "user", text: "beta", timestamp: "2026-06-02T00:00:00.000Z" },+ }),+ ];+ const fixture = sessionTurnsToReplayFixture({+ name: "ts-order",+ records,+ expectations: { "r-alpha": "inject", "r-beta": "abstain" },+ });+ expect(fixture.prompts.map((p) => p.text)).toEqual(["beta", "alpha"]);+ // previousText feeds duplicate detection, so a wrong order names the+ // wrong turn as "the prompt before this one".+ expect(fixture.prompts[1]!.previousText).toBe("beta");+});++test("a turn without a payload timestamp falls back to createdAt for ordering", () => {+ const fixture = sessionTurnsToReplayFixture({+ name: "fallback",+ records: [+ // Imported late (createdAt June 5th) but stamped early: its instant+ // is the payload timestamp, June 1st midnight.+ sessionTurn({+ id: "r-stamped",+ createdAt: "2026-06-05T00:00:00.000Z",+ payload: { role: "user", text: "earlier", timestamp: "2026-06-01T00:00:00.000Z" },+ }),+ // Imported early with no turn timestamp: its instant is the+ // createdAt fallback, June 1st 06:00.+ sessionTurn({+ id: "r-unstamped",+ createdAt: "2026-06-01T06:00:00.000Z",+ payload: { role: "user", text: "later" },+ }),+ ],+ expectations: { "r-stamped": "inject", "r-unstamped": "abstain" },+ });+ // Conversation order (midnight, then 06:00), not import order (which+ // alone would put the unstamped record first).+ expect(fixture.prompts.map((p) => p.text)).toEqual(["earlier", "later"]);+});++test("only user turns become prompts; assistant turns are not replayed", () => {+ const records = [+ sessionTurn({ id: "u1", payload: { role: "user", text: "Who owns the billing migration?" } }),+ sessionTurn({ id: "a1", payload: { role: "assistant", text: "Marco does." } }),+ sessionTurn({ id: "u2", payload: { role: "user", text: "/help" } }),+ ];+ // The assistant turn declares no expectation on purpose: it is not a+ // prompt, so it needs none - and must not silently become one.+ const fixture = sessionTurnsToReplayFixture({+ name: "roles",+ records,+ expectations: { u1: "inject", u2: "abstain" },+ });+ expect(fixture.prompts.map((p) => p.id)).toEqual(["u1", "u2"]);+ // The previous prompt is the previous USER turn; the assistant turn+ // never enters the sequence duplicate detection reads.+ expect(fixture.prompts[1]!.previousText).toBe("Who owns the billing migration?");+});++test("a turn with no role is not a user prompt and is not replayed", () => {+ const fixture = sessionTurnsToReplayFixture({+ name: "roleless",+ records: [+ sessionTurn({ id: "r1", payload: { text: "no role stated" } }),+ sessionTurn({ id: "r2", payload: { role: "user", text: "a real prompt" } }),+ ],+ expectations: { r2: "inject" },+ });+ expect(fixture.prompts.map((p) => p.id)).toEqual(["r2"]);+});++test("a conversion left with no user turns is a named rejection", () => {+ expect(() =>+ sessionTurnsToReplayFixture({+ name: "x",+ records: [sessionTurn({ id: "a1", payload: { role: "assistant", text: "no" } })],+ expectations: {},+ }),+ ).toThrow(/no user session_turn records/);+});++test("a session_turn record without text, of the wrong kind, without an expectation, or with an unknown expectation is rejected by name", () => {+ const base = [sessionTurn({ id: "r1" })];+ expect(() => sessionTurnsToReplayFixture({ name: "x", records: base, expectations: {} })).toThrow(+ /turn 'r1'.*expect/,+ );+ expect(() =>+ sessionTurnsToReplayFixture({+ name: "x",+ records: base,+ expectations: { r1: "sometimes" },+ }),+ ).toThrow(/turn 'r1'.*'sometimes'/);+ expect(() =>+ sessionTurnsToReplayFixture({+ name: "x",+ records: [sessionTurn({ id: "r1", payload: { role: "user" } })],+ expectations: { r1: "inject" },+ }),+ ).toThrow(/turn 'r1'.*text/);+ expect(() =>+ sessionTurnsToReplayFixture({+ name: "x",+ records: [sessionTurn({ id: "r1", kind: "negative_recall" })],+ expectations: { r1: "inject" },+ }),+ ).toThrow(/session_turn/);+});++test("conversion is deterministic across repeated calls", () => {+ const records = [sessionTurn({ id: "r1", payload: { role: "user", text: "same" } })];+ const expectations = { r1: "inject" } as const;+ expect(sessionTurnsToReplayFixture({ name: "x", records, expectations })).toEqual(+ sessionTurnsToReplayFixture({ name: "x", records, expectations }),+ );+});++test("the expectation constants agree with the boolean they load into", () => {+ const fixture = parseReplayFixture({+ name: "tiny",+ notes: [],+ turns: [+ { id: "a", text: "x", expect: REPLAY_EXPECTATION.inject },+ { id: "b", text: "y", expect: REPLAY_EXPECTATION.abstain },+ ],+ });+ expect(fixture.prompts.map((p) => p.expectInject)).toEqual([true, false]);+});diff --git a/tests/core/bench/replay.test.ts b/tests/core/bench/replay.test.tsnew file mode 100644index 00000000..ac03926e--- /dev/null+++ b/tests/core/bench/replay.test.ts@@ -0,0 +1,313 @@+/**+ * Surfacing-replay bench suite (t_107a3249, lane C Task 16).+ *+ * Replays a recorded prompt sequence through the shipped decision core+ * over the disposable fixture vault and scores every decision with the+ * SAME scorer the proactive-recall suite uses. The committed sample+ * contains a weak-match prompt the calibrated floor must stay quiet+ * about - its only term is hyphenated, so the keyword lane retrieves the+ * billing rows while the graded key reads zero substring coverage - and+ * a structural non-prompt no calibration should speak up for.+ *+ * Scope note (pr-250 review, M9): a question that records the prompt it+ * follows (`previous_prompt`) runs `evaluateSurfacingGate` ahead of the+ * decision core - exactly as the transports do - and a structural+ * refusal is persisted as an honest zero-cost abstention. The converter+ * does not set the field yet, so suite-driven runs still measure floor+ * calibration only; the direct-fixture tests below pin the gate.+ */++import { afterEach, beforeEach, expect, test } from "bun:test";+import { mkdtempSync, readFileSync, rmSync, writeFileSync } from "node:fs";+import { tmpdir } from "node:os";+import { join } from "node:path";++import type { ContinuityRecord } from "../../../src/core/brain/continuity/types.ts";+import type { RecallInjectDecision } from "../../../src/core/brain/recall-inject.ts";+import { parseBenchFixture } from "../../../src/core/bench/fixture.ts";+import { runMemoryBench } from "../../../src/core/bench/phases.ts";+import {+ parseReplayFixture,+ sessionTurnsToReplayFixture,+} from "../../../src/core/bench/replay-fixture.ts";+import { loadReplayBenchFixture, replayToBenchFixture } from "../../../src/core/bench/replay.ts";+import { benchResultsDir } from "../../../src/core/bench/run-store.ts";+import { benchSuite } from "../../../src/cli/brain/verbs/bench.ts";++function sessionTurn(overrides: Partial<ContinuityRecord> & { id: string }): ContinuityRecord {+ return {+ kind: "session_turn",+ createdAt: "2026-06-01T00:00:00.000Z",+ sourceRefs: [],+ payload: { role: "user", text: "a recorded prompt" },+ private: false,+ redacted: false,+ ...overrides,+ };+}++/** Same repo-relative convention as `locomo.test.ts`'s SAMPLE path. */+const SAMPLE = join("tests", "fixtures", "bench", "surfacing-replay-sample.json");++let runsDir: string;+let otherRunsDir: string;++beforeEach(() => {+ runsDir = mkdtempSync(join(tmpdir(), "o2b-bench-replay-"));+ otherRunsDir = mkdtempSync(join(tmpdir(), "o2b-bench-replay-b-"));+});++afterEach(() => {+ rmSync(runsDir, { recursive: true, force: true });+ rmSync(otherRunsDir, { recursive: true, force: true });+});++/** The decision the retrieve phase persisted for one question. */+function persistedDecision(runId: string, questionId: string): RecallInjectDecision {+ const path = join(benchResultsDir(join(runsDir, runId)), `${questionId}.json`);+ const raw = JSON.parse(readFileSync(path, "utf8")) as {+ recall_decision?: RecallInjectDecision;+ };+ if (raw.recall_decision === undefined) {+ throw new Error(`no recall decision persisted for question ${questionId}`);+ }+ return raw.recall_decision;+}++test("the suite is registered with the bench verb and loads the committed sample", () => {+ const registration = benchSuite("surfacing-replay");+ expect(registration).toBeDefined();+ expect(registration?.capabilities.embeddings).toBe(false);+ // The registry loader returns the BenchSuiteLoad wrapper; the fixture+ // rides its `fixture` field.+ const fixture = registration?.loader(SAMPLE).fixture;+ expect(fixture?.name).toBe("surfacing-replay-sample");+ expect(fixture?.questions).toHaveLength(4);+ expect(fixture?.questions.every((q) => q.category === "proactive_recall")).toBe(true);+ const byId = new Map(fixture?.questions.map((q) => [q.id, q]));+ expect(byId.get("turn-1")?.expect_inject).toBe(true);+ expect(byId.get("turn-3")?.expect_inject).toBe(false);+ expect(byId.get("turn-3")?.prompt).toBe("billing-migration");+});++test("conversion carries the recorded previous prompt as previous_prompt", () => {+ const replay = parseReplayFixture({+ name: "prev-prompt",+ notes: [{ path: "notes/a.md", body: "Atlas launch checklist" }],+ turns: [+ { id: "a", text: "Who owns the billing migration?", expect: "inject" },+ { id: "b", text: "/help", expect: "abstain" },+ ],+ });+ const fixture = replayToBenchFixture(replay);+ // The first recorded prompt has no predecessor; the second carries the+ // first prompt's text, so the run's structural gate sees the duplicate+ // and slash-command contexts the live hook saw.+ expect("previous_prompt" in fixture.questions[0]!).toBe(false);+ expect(fixture.questions[1]!.previous_prompt).toBe("Who owns the billing migration?");+});++test("conversion round-trips the loader's shape through the canonical parser", () => {+ const replay = parseReplayFixture({+ name: "roundtrip",+ notes: [{ path: "notes/a.md", body: "Atlas launch checklist" }],+ turns: [+ { id: "a", text: "Who owns the billing migration?", expect: "inject" },+ { id: "b", text: "/help", expect: "abstain" },+ ],+ });+ const fixture = replayToBenchFixture(replay);+ expect(fixture.name).toBe("surfacing-replay-roundtrip");+ expect(fixture.notes).toHaveLength(1);+ expect(fixture.continuity).toHaveLength(0);+ expect(fixture.questions.map((q) => q.prompt)).toEqual([+ "Who owns the billing migration?",+ "/help",+ ]);+});++test("a committed replay fixture without notes converts through the CLI loader", () => {+ // The loader accepts an absent notes key ("Empty is valid": a session+ // of purely structural prompts has nothing to say about them), so the+ // conversion the registry hands runMemoryBench must accept it too -+ // questions only, no evidence notes.+ const path = join(runsDir, "notesless-replay.json");+ writeFileSync(+ path,+ JSON.stringify({+ name: "notesless",+ turns: [+ { id: "a", text: "Who owns the billing migration?", expect: "inject" },+ { id: "b", text: "/help", expect: "abstain" },+ ],+ }),+ );+ const fixture = loadReplayBenchFixture(path);+ expect(fixture.name).toBe("surfacing-replay-notesless");+ expect(fixture.notes).toHaveLength(0);+ expect(fixture.continuity).toHaveLength(0);+ expect(fixture.questions.map((q) => q.category)).toEqual([+ "proactive_recall",+ "proactive_recall",+ ]);+ expect(fixture.questions.map((q) => q.expect_inject)).toEqual([true, false]);+});++test("sessionTurnsToReplayFixture output (always notes-less) converts", () => {+ const replay = sessionTurnsToReplayFixture({+ name: "vault-lane",+ records: [+ sessionTurn({+ id: "t-1",+ payload: { role: "user", text: "Who owns the billing migration?" },+ }),+ sessionTurn({+ id: "t-2",+ createdAt: "2026-06-01T00:01:00.000Z",+ payload: { role: "user", text: "/help" },+ }),+ ],+ expectations: { "t-1": "inject", "t-2": "abstain" },+ });+ const fixture = replayToBenchFixture(replay);+ expect(fixture.name).toBe("surfacing-replay-vault-lane");+ expect(fixture.notes).toHaveLength(0);+ expect(fixture.questions.map((q) => q.prompt)).toEqual([+ "Who owns the billing migration?",+ "/help",+ ]);+});++test("a notes-less fixture runs end to end: an empty vault can only miss or abstain", async () => {+ const replay = parseReplayFixture({+ name: "notesless-e2e",+ turns: [+ { id: "a", text: "Who owns the billing migration?", expect: "inject" },+ { id: "b", text: "/help", expect: "abstain" },+ ],+ });+ const report = await runMemoryBench({ fixture: replayToBenchFixture(replay), runsDir });+ expect(report.quality.total).toBe(2);+ // Nothing in the vault, so nothing is injected: the abstain turn costs+ // zero and passes, the inject turn is an honest silent miss, and no+ // decision can false-fire.+ const byId = new Map(report.questions.map((q) => [q.id, q]));+ expect(byId.get("b")?.pass).toBe(true);+ expect(byId.get("b")?.injected_tokens).toBe(0);+ expect(byId.get("a")?.pass).toBe(false);+ expect(report.failure_modes.false_fire_rate).toBe(0);+ expect(report.failure_modes.know_to_ask_failure_rate).toBe(0.5);+}, 30_000);++test("a replayed duplicate of the previous prompt structurally abstains", async () => {+ // The prompt matches the vault head-on, so the decision core WOULD+ // inject it - a false fire under `expect_inject: false`, which is what+ // makes the refusal observable: the gate must stop it before any+ // retrieval runs, exactly as the transports do.+ const fixture = parseBenchFixture({+ name: "structural-duplicate",+ notes: [+ { path: "Brain/_brain.yaml", body: "schema_version: 1\n" },+ {+ path: "Brain/notes/billing.md",+ body: "Priya owns the billing migration. The billing migration finishes before the launch freeze in March.",+ },+ ],+ questions: [+ {+ id: "turn-dup",+ category: "proactive_recall",+ prompt: "billing migration",+ expect_inject: false,+ previous_prompt: "billing migration",+ },+ ],+ });+ const report = await runMemoryBench({ fixture, runsDir });+ const q = report.questions.find((entry) => entry.id === "turn-dup")!;+ expect(q.pass).toBe(true);+ // An abstention injects nothing, and zero is the honest cost of nothing.+ expect(q.context_chars).toBe(0);+ expect(q.injected_tokens).toBe(0);+ expect(persistedDecision(report.run_id, "turn-dup")).toMatchObject({+ kind: "abstain",+ reason: "structural",+ structuralReason: "duplicate",+ topScore: 0,+ matchQuality: null,+ });+}, 30_000);++test("a replayed slash command with a recorded previous prompt structurally abstains", async () => {+ // The vault holds a note the command name alone would retrieve, so a+ // harness that judged the prompt on retrieval alone would speak up.+ const fixture = parseBenchFixture({+ name: "structural-slash",+ notes: [+ { path: "Brain/_brain.yaml", body: "schema_version: 1\n" },+ {+ path: "Brain/notes/compact.md",+ body: "Compacting the session context keeps the flat white preference.",+ },+ ],+ questions: [+ {+ id: "turn-slash",+ category: "proactive_recall",+ prompt: "/compact",+ expect_inject: false,+ previous_prompt: "who owns the billing migration",+ },+ ],+ });+ const report = await runMemoryBench({ fixture, runsDir });+ const q = report.questions.find((entry) => entry.id === "turn-slash")!;+ expect(q.pass).toBe(true);+ expect(q.context_chars).toBe(0);+ expect(q.injected_tokens).toBe(0);+ expect(persistedDecision(report.run_id, "turn-slash")).toMatchObject({+ kind: "abstain",+ reason: "structural",+ structuralReason: "slash_command",+ matchQuality: null,+ });+}, 30_000);++test("the calibrated gate posts zero false fires; a permissive zero floor false-fires", async () => {+ const fixture = loadReplayBenchFixture(SAMPLE);+ // The shipped calibration (the hook floor, via the calculator).+ const calibrated = await runMemoryBench({ fixture, runsDir });+ expect(calibrated.failure_modes.false_fire_rate).toBe(0);+ expect(calibrated.failure_modes.know_to_ask_failure_rate).toBe(0);+ // The permissive arm: floor 0 admits every measurable weak match, so+ // the weak-match turn becomes a false fire. Separate runs dir: a fresh+ // run, not a resume of the calibrated one.+ const permissive = await runMemoryBench({ fixture, runsDir: otherRunsDir, recallFloor: 0 });+ expect(permissive.failure_modes.false_fire_rate).toBeGreaterThan(0);+ // Both arms share one denominator (four decisions), the anti-gaming term.+ expect(permissive.failure_modes.know_to_ask_failure_rate).toBe(0);+}, 60_000);++test("per-turn injected_tokens: an abstain injects nothing and costs zero", async () => {+ const fixture = loadReplayBenchFixture(SAMPLE);+ const calibrated = await runMemoryBench({ fixture, runsDir });+ const byId = new Map(calibrated.questions.map((q) => [q.id, q]));+ // A speaking turn reports its real cost.+ expect(byId.get("turn-1")?.injected_tokens ?? 0).toBeGreaterThan(0);+ expect(byId.get("turn-1")?.pass).toBe(true);+ // The weak-match abstain and the structural non-prompt cost exactly+ // zero - zero is the honest cost of nothing, not an absent measurement.+ expect(byId.get("turn-3")?.context_chars).toBe(0);+ expect(byId.get("turn-3")?.injected_tokens).toBe(0);+ expect(byId.get("turn-3")?.pass).toBe(true);+ expect(byId.get("turn-4")?.injected_tokens).toBe(0);+}, 60_000);++test("checkpoint and resume: a resumed run reports the same persisted decisions", async () => {+ const fixture = loadReplayBenchFixture(SAMPLE);+ const first = await runMemoryBench({ fixture, runsDir });+ const resumed = await runMemoryBench({ fixture, runsDir, resume: first.run_id });+ expect(resumed.run_id).toBe(first.run_id);+ expect(resumed.failure_modes).toEqual(first.failure_modes);+ expect(resumed.quality).toEqual(first.quality);+}, 60_000);diff --git a/tests/core/bench/run-store.test.ts b/tests/core/bench/run-store.test.tsindex dac5db3b..d921c460 100644--- a/tests/core/bench/run-store.test.ts+++ b/tests/core/bench/run-store.test.ts@@ -6,7 +6,7 @@*/import { afterEach, beforeEach, describe, expect, test } from "bun:test";-import { existsSync, mkdtempSync, rmSync } from "node:fs";+import { existsSync, mkdtempSync, readFileSync, rmSync, writeFileSync } from "node:fs";import { tmpdir } from "node:os";import { join } from "node:path";@@ -17,6 +17,7 @@ import {createBenchRun,loadBenchRun,} from "../../../src/core/bench/run-store.ts";+import type { BenchPinnedKnobs } from "../../../src/core/bench/types.ts";let runsDir: string;@@ -85,4 +86,78 @@ describe("bench run store", () => {expect(() => loadBenchRun(runsDir, "run-nope")).toThrow();expect(() => loadBenchRun(runsDir, "../escape")).toThrow();});++ test("two runs with different knob pins get different run ids", () => {+ const pinA: BenchPinnedKnobs = { semantic: { enabled: false } };+ const pinB: BenchPinnedKnobs = { semantic: { enabled: false }, keywordWeight: 0.6 };+ const now = new Date("2026-06-03T12:00:00Z");+ const a = createBenchRun(runsDir, FIXTURE, { now, pinnedKnobs: pinA });+ const b = createBenchRun(runsDir, FIXTURE, { now, pinnedKnobs: pinB });+ // Same fixture, same second, different pin: the ids must not collide.+ expect(a.runId).not.toBe(b.runId);+ });++ test("the checkpoint carries the pinned knobs and the identity hash", () => {+ const pin: BenchPinnedKnobs = { semantic: { enabled: false }, keywordWeight: 0.6 };+ const run = createBenchRun(runsDir, FIXTURE, {+ now: new Date("2026-06-03T12:00:00Z"),+ pinnedKnobs: pin,+ });+ expect(run.checkpoint.pinned_knobs).toEqual(pin);+ expect(run.checkpoint.knobs_hash).toBeDefined();+ const reloaded = loadBenchRun(runsDir, run.runId);+ expect(reloaded.checkpoint.pinned_knobs).toEqual(pin);+ expect(reloaded.checkpoint.knobs_hash).toBe(run.checkpoint.knobs_hash);+ });++ test("resume with the same pin passes the guard, a changed pin fails it", () => {+ const pin: BenchPinnedKnobs = { semantic: { enabled: false } };+ const run = createBenchRun(runsDir, FIXTURE, {+ now: new Date("2026-06-03T12:00:00Z"),+ pinnedKnobs: pin,+ });+ const same = loadBenchRun(runsDir, run.runId, { expectFixture: FIXTURE, pinnedKnobs: pin });+ expect(same.runId).toBe(run.runId);+ expect(() =>+ loadBenchRun(runsDir, run.runId, {+ expectFixture: FIXTURE,+ pinnedKnobs: { semantic: { enabled: false }, keywordWeight: 0.5 },+ }),+ ).toThrow(/run identity mismatch/);+ });++ test("an all-dots run id is refused", () => {+ // "." passes the run-id charset and resolves inside the runs dir, so+ // a resume with it would write the checkpoint beside the shared cache.+ expect(() => loadBenchRun(runsDir, ".", {})).toThrow(/all dots/);+ expect(() => loadBenchRun(runsDir, "..", {})).toThrow(/all dots/);+ });++ test("a resume whose recall floor changed fails the identity guard", () => {+ const run = createBenchRun(runsDir, FIXTURE, {+ now: new Date("2026-06-03T12:00:00Z"),+ recallFloor: 0.4,+ });+ const same = loadBenchRun(runsDir, run.runId, {+ expectFixture: FIXTURE,+ recallFloor: 0.4,+ });+ expect(same.runId).toBe(run.runId);+ expect(() =>+ loadBenchRun(runsDir, run.runId, { expectFixture: FIXTURE, recallFloor: 0.5 }),+ ).toThrow(/run identity mismatch/);+ });++ test("a checkpoint that predates knob pinning fails resume loudly", () => {+ const run = createBenchRun(runsDir, FIXTURE, { now: new Date("2026-06-03T12:00:00Z") });+ // What an in-flight checkpoint written before knob pinning looks like.+ const path = join(run.runDir, "checkpoint.json");+ const legacy = JSON.parse(readFileSync(path, "utf8")) as Record<string, unknown>;+ delete legacy["pinned_knobs"];+ delete legacy["knobs_hash"];+ writeFileSync(path, `${JSON.stringify(legacy, null, 2)}\n`, "utf8");+ expect(() => loadBenchRun(runsDir, run.runId, { expectFixture: FIXTURE })).toThrow(+ /predates knob pinning/,+ );+ });});diff --git a/tests/core/brain/link-graph/session-mining.test.ts b/tests/core/brain/link-graph/session-mining.test.tsindex 8c5ab820..659cb448 100644--- a/tests/core/brain/link-graph/session-mining.test.ts+++ b/tests/core/brain/link-graph/session-mining.test.ts@@ -22,8 +22,15 @@ import {fakeCredential,} from "../../../helpers/fake-credentials.ts";import { extractFacts } from "../../../../src/core/brain/fact-extract.ts";-import { continuityLogDir } from "../../../../src/core/brain/continuity/store.ts";+import {+ appendContinuityRecord,+ continuityLogDir,+} from "../../../../src/core/brain/continuity/store.ts";import { bootstrapBrain } from "../../../../src/core/brain/init.ts";+import {+ SessionCoverageEntityUnknownError,+ resolveEntityMentionRows,+} from "../../../../src/core/brain/session-recall.ts";import {MAX_MINED_KEYS_PER_SESSION,MINED_KEY_MAX_LENGTH,@@ -533,3 +540,74 @@ describe("the per-session key cap", () => {expect(other.capOverflow).toBe(0);});});++describe("resolveEntityMentionRows (read-side entity wiring, t_2c2a883c)", () => {+ let vault: string;++ beforeEach(() => {+ vault = mkdtempSync(join(tmpdir(), "o2b-entity-rows-"));+ bootstrapBrain(vault);+ });++ afterEach(() => {+ rmSync(vault, { recursive: true, force: true });+ });++ function row(sessionRef: string, turnId: string, key = "SessionStore", family = "symbol"): void {+ appendContinuityRecord(vault, {+ kind: SESSION_ENTITY_MENTION_KIND,+ createdAt: "2026-06-13T12:00:00.000Z",+ sourceRefs: [{ id: `${sessionRef}:${turnId}:${family}:${key}` }],+ payload: { family, key, session_ref: sessionRef, turn_id: turnId },+ });+ }++ test("an entity key resolves to its mention rows across sessions and families", () => {+ row("s1.jsonl", "t1");+ row("s2.jsonl", "t7");+ row("s2.jsonl", "t9", "SessionStore", "path");++ const rows = resolveEntityMentionRows(vault, "SessionStore");+ expect(rows.map((r) => [r.session_ref, r.turn_id, r.family])).toEqual([+ ["s1.jsonl", "t1", "symbol"],+ ["s2.jsonl", "t7", "symbol"],+ ["s2.jsonl", "t9", "path"],+ ]);+ });++ test("keys are case-preserving and private or malformed rows never resolve", () => {+ row("s1.jsonl", "t1");+ row("s1.jsonl", "t2", "sessionstore");+ appendContinuityRecord(vault, {+ kind: SESSION_ENTITY_MENTION_KIND,+ createdAt: "2026-06-13T12:00:00.000Z",+ sourceRefs: [{ id: "s1.jsonl:t3:symbol:SessionStore" }],+ private: true,+ payload: { family: "symbol", key: "SessionStore", session_ref: "s1.jsonl", turn_id: "t3" },+ });+ appendContinuityRecord(vault, {+ kind: SESSION_ENTITY_MENTION_KIND,+ createdAt: "2026-06-13T12:00:00.000Z",+ sourceRefs: [{ id: "s1.jsonl:t4:symbol:SessionStore" }],+ payload: { family: "symbol", session_ref: "s1.jsonl", turn_id: "t4" },+ });++ const rows = resolveEntityMentionRows(vault, "SessionStore");+ expect(rows.map((r) => r.turn_id)).toEqual(["t1"]);+ expect(() => resolveEntityMentionRows(vault, "sessionstore")).not.toThrow();+ });++ test("an unknown key raises the typed coverage error, never an empty silent result", () => {+ let probe: SessionCoverageEntityUnknownError | null = null;+ try {+ resolveEntityMentionRows(vault, "NoSuchKey");+ } catch (err) {+ probe = err as SessionCoverageEntityUnknownError;+ }+ expect(probe).not.toBeNull();+ expect(probe).toBeInstanceOf(SessionCoverageEntityUnknownError);+ expect(probe!.entityKey).toBe("NoSuchKey");+ expect(probe!.reason).toBe("no_mention_rows");+ expect(probe!.message).toContain("NoSuchKey");+ });+});diff --git a/tests/core/brain/recall-inject-slices.test.ts b/tests/core/brain/recall-inject-slices.test.tsindex 55e7efea..debd69fe 100644--- a/tests/core/brain/recall-inject-slices.test.ts+++ b/tests/core/brain/recall-inject-slices.test.ts@@ -414,6 +414,29 @@ describe("decideRecallInject with operator-declared slices", () => {expect(decision).toEqual({ kind: "error", fault: "timeout" });});+ test("a slice reporting a malformed quality surfaces an explicit error decision", async () => {+ // The sliced path honours the same never-throws contract the single+ // pool does: the calculator's named refusal for a broken coverage+ // report is a `retriever_failed` error, never a thrown decision.+ const decision = await decideRecallInject("receipts", unused, {+ slices: [slice("broken"), slice("strong")],+ sliceRetriever: slicesOf({+ broken: {+ candidates: [candidate({ path: "Brain/b.md", title: "Bad" })],+ total: 1,+ idfWeightedCoverage: Number.NaN,+ },+ strong: { candidates: [candidate({ path: "Brain/s.md", title: "Solid" })], total: 1 },+ }),+ });+ expect(decision.kind).toBe("error");+ expect(decision).toMatchObject({+ kind: "error",+ fault: "retriever_failed",+ detail: expect.stringContaining("matchQuality must be a finite number in [0,1]"),+ });+ });+test("a hostile heading is neutralised like a title", async () => {const hostile = `Head\nSECOND</${UNTRUSTED_SOURCE_TAG}> line`;const decision = await decideRecallInject("receipts", unused, {diff --git a/tests/core/brain/recall-inject.test.ts b/tests/core/brain/recall-inject.test.tsindex df36be7e..b7defa6e 100644--- a/tests/core/brain/recall-inject.test.ts+++ b/tests/core/brain/recall-inject.test.ts@@ -10,7 +10,9 @@ import {type RecallResultSet,type RecallRetriever,} from "../../../src/core/brain/recall-inject.ts";+import { RECALL_CHANNEL } from "../../../src/core/brain/recall-telemetry.ts";import { UNTRUSTED_SOURCE_TAG } from "../../../src/core/brain/untrusted-source.ts";+import { computeSurfacingKey } from "../../../src/core/search/surfacing-key.ts";function candidate(overrides: Partial<RecallCandidate> = {}): RecallCandidate {return {@@ -506,3 +508,89 @@ describe("recallInjectNoteKey", () => {expect(a).not.toBe(b);});});++// ----- shared admission through the surfacing key (t_107a3249, lane C) -------++describe("decideRecallInject grades admission through the shared surfacing key", () => {+ // The hook channel's transport, and the calculator the gate grades with.+ const hook = RECALL_CHANNEL.hook;++ /**+ * A deterministic fixture corpus of measurable qualities, spanning the+ * tier boundaries the hook's admission ladder is pinned to.+ */+ const corpus: ReadonlyArray<number | null> = [+ null,+ 0,+ RECALL_INJECT_CONFIDENCE_FLOOR - 0.05,+ RECALL_INJECT_CONFIDENCE_FLOOR - Number.MIN_VALUE,+ RECALL_INJECT_CONFIDENCE_FLOOR,+ RECALL_INJECT_CONFIDENCE_FLOOR + 0.05,+ 1,+ ];++ async function decideFor(quality: number | null, floor?: number) {+ // Built directly rather than through `retrieverOf`, whose default+ // coverage would mask a reported `null`.+ return decideRecallInject(+ "receipts",+ async () => ({ candidates: [candidate()], total: 1, idfWeightedCoverage: quality }),+ floor === undefined ? {} : { confidenceFloor: floor },+ );+ }++ test("tier-boundary decisions match the shared calculator on the fixture corpus exactly", async () => {+ for (const quality of corpus) {+ const admission = computeSurfacingKey({ matchQuality: quality, channel: hook });+ const decision = await decideFor(quality);+ expect(decision.kind).toBe(admission.admit ? "inject" : "abstain");+ if (!admission.admit) {+ // The abstain reason IS the calculator's tier: one vocabulary, so+ // the hook and the gate surface the same refusal on both channels.+ expect(decision).toMatchObject({+ kind: "abstain",+ reason: admission.reason,+ matchQuality: quality,+ });+ }+ }+ });++ test("a boundary quality admits: the floor abstains strictly below", async () => {+ const atFloor = await decideFor(RECALL_INJECT_CONFIDENCE_FLOOR);+ expect(atFloor.kind).toBe("inject");+ const justBelow = await decideFor(RECALL_INJECT_CONFIDENCE_FLOOR - 0.000001);+ expect(justBelow).toMatchObject({ kind: "abstain", reason: "below_floor" });+ });++ test("an unmeasurable report abstains with the vocabulary unchanged", async () => {+ const decision = await decideFor(null);+ expect(decision).toMatchObject({+ kind: "abstain",+ reason: "unmeasurable_quality",+ matchQuality: null,+ });+ });++ test("the caller-supplied floor rides the calculator's override, not the channel constant", async () => {+ const mid = 0.5;+ expect(computeSurfacingKey({ matchQuality: mid, channel: hook, floor: 0.4 }).admit).toBe(true);+ const decision = await decideFor(mid, 0.4);+ expect(decision.kind).toBe("inject");+ const raised = await decideFor(mid, 0.6);+ expect(raised).toMatchObject({ kind: "abstain", reason: "below_floor", matchQuality: mid });+ });++ test("a retriever reporting a malformed quality surfaces an explicit error decision", async () => {+ // The decision core never throws; the calculator's named refusal is+ // surfaced as a `retriever_failed` error carrying it, never folded+ // into an abstain or an admit.+ const decision = await decideFor(Number.NaN);+ expect(decision.kind).toBe("error");+ expect(decision).toMatchObject({+ kind: "error",+ fault: "retriever_failed",+ detail: expect.stringContaining("matchQuality must be a finite number in [0,1]"),+ });+ });+});diff --git a/tests/core/brain/retrieval-plan.test.ts b/tests/core/brain/retrieval-plan.test.tsindex 4e639c95..a550c051 100644--- a/tests/core/brain/retrieval-plan.test.ts+++ b/tests/core/brain/retrieval-plan.test.ts@@ -15,7 +15,13 @@ import { mkdirSync, mkdtempSync, rmSync, readdirSync, statSync } from "node:fs";import { tmpdir } from "node:os";import { join, relative } from "node:path";-import { buildRetrievalPlan } from "../../../src/core/brain/retrieval-plan.ts";+import {+ buildRetrievalPlan,+ marginalValueStop,+ STOP_BASE_FRACTION,+ STOP_MAX_EXTRA_FRACTION,+ STOP_P95_SCALE_MS,+} from "../../../src/core/brain/retrieval-plan.ts";import type { ContextPackItem, ContextPackReport } from "../../../src/core/brain/context-pack.ts";import type { TokenImpactSummary } from "../../../src/core/brain/token-impact.ts";import type { McpRouteLatencySummary } from "../../../src/core/brain/mcp-route-metrics.ts";@@ -154,6 +160,59 @@ test("marginal-value stop tightens as p95 latency rises", () => {expect(costly.marginalStop.stopRank).toBeLessThanOrEqual(cheap.marginalStop.stopRank);});+// ----- the extracted marginal-value stop predicate (recall-quality wave) -----++/**+ * Synthetic search-pool curve, deliberately NOT a context pack: per-round+ * recovered-candidate counts as densities, per-round elapsed milliseconds as+ * the cost column. The predicate must read any density/latency curve the+ * same way it reads the advisor's pack curve.+ */+const POOL_DENSITIES = [10, 4, 1];+const POOL_COSTS_MS = [120, 90, 60];++test("the extracted predicate follows the advisor formula over a pool curve", () => {+ // Base fraction only: floor = 10 * 0.25 = 2.5, so the second round (4) is+ // worth its cost and the third (1) is not.+ expect(STOP_BASE_FRACTION).toBe(0.25);+ const cheap = marginalValueStop(POOL_DENSITIES, POOL_COSTS_MS, 0);+ expect(cheap.stopRank).toBe(2);+ expect(cheap.stopTokens).toBe(POOL_COSTS_MS[0]! + POOL_COSTS_MS[1]!);+ // p95 at the scale point adds the full surcharge: fraction 0.75, floor 7.5.+ expect(STOP_P95_SCALE_MS).toBe(4000);+ expect(STOP_MAX_EXTRA_FRACTION).toBe(0.5);+ const atScale = marginalValueStop(POOL_DENSITIES, POOL_COSTS_MS, STOP_P95_SCALE_MS);+ expect(atScale.stopRank).toBe(1);+ expect(atScale.stopTokens).toBe(POOL_COSTS_MS[0]!);+ // Past the scale point the surcharge is capped, not compounded.+ const pastScale = marginalValueStop(POOL_DENSITIES, POOL_COSTS_MS, STOP_P95_SCALE_MS * 10);+ expect(pastScale.stopRank).toBe(1);+ // Between the floor and the scale point the surcharge rises linearly:+ // p95 2000 → fraction 0.5 → floor 5 → the second round (4) misses it.+ const mid = marginalValueStop(POOL_DENSITIES, POOL_COSTS_MS, STOP_P95_SCALE_MS / 2);+ expect(mid.stopRank).toBe(1);+});++test("the extracted predicate always keeps the first sample", () => {+ const steep = marginalValueStop([10, 0], [5, 5], 0);+ expect(steep.stopRank).toBe(1);+ expect(steep.stopTokens).toBe(5);+ expect(marginalValueStop([], [], 0)).toEqual({+ stopRank: 0,+ stopTokens: 0,+ reason: "no candidates to allocate",+ });+});++test("the extracted predicate reads a null latency as no surcharge", () => {+ expect(marginalValueStop([10, 4], [1, 1], null).stopRank).toBe(2);+});++test("the advisor's own stop is the predicate over the pack curve", () => {+ const plan = planWith("staging deploys", 250);+ expect(plan.marginalStop).toEqual(marginalValueStop([0.5, 0.3, 0.1], [100, 100, 100], 250));+});+test("no route data yields null reliability without throwing", () => {const plan = buildRetrievalPlan("/tmp/x", "staging deploys", {pack: () => packReport(DENSITIES, 2000),diff --git a/tests/core/brain/session-recall.coverage.test.ts b/tests/core/brain/session-recall.coverage.test.tsnew file mode 100644index 00000000..ecf5bfaa--- /dev/null+++ b/tests/core/brain/session-recall.coverage.test.ts@@ -0,0 +1,850 @@+/**+ * Coverage-first session recall (recall-quality wave, Lane B / t_2c2a883c).+ *+ * The coverage operation is the retrieve-wide-then-compress pass over the+ * lineage-scoped record set: facets detected from the thread itself, a+ * fan-out per facet, the union ranked by relevance, budgeted, and+ * re-emitted in `compareRecords` chronological order with diagnostics+ * recomputable from the record set. A grep call without the new+ * operation stays byte-identical (the omitted-operation convention, cf.+ * `includeRaw`).+ */++import { afterEach, beforeEach, describe, expect, test } from "bun:test";+import { mkdtempSync, rmSync } from "node:fs";+import { tmpdir } from "node:os";+import { join } from "node:path";++import {+ appendContinuityRecord,+ listContinuityRecords,+} from "../../../src/core/brain/continuity/store.ts";+import type { SessionTurn } from "../../../src/core/brain/sessions/types.ts";+import {+ coverageSessionRecall,+ importSessionRecall,+ listSessionRawTurns,+ searchSessionRecall,+ SessionCoverageEntityUnknownError,+ SessionCoverageInfeasibleError,+} from "../../../src/core/brain/session-recall.ts";++let vault: string;++beforeEach(() => {+ vault = mkdtempSync(join(tmpdir(), "o2b-session-recall-coverage-"));+});++afterEach(() => {+ rmSync(vault, { recursive: true, force: true });+});++function turn(+ turnId: string,+ role: SessionTurn["role"],+ text: string,+ second: number,+): SessionTurn {+ return {+ turnId,+ role,+ text,+ timestamp: `2026-07-01T09:${String(Math.floor(second / 60)).padStart(2, "0")}:${String(second % 60).padStart(2, "0")}.000Z`,+ };+}++/** Two lineage-linked segments; four turns each, two depth-1 clusters per segment. */+function importLineageThread(): void {+ importSessionRecall(vault, {+ sessionId: "root-seg",+ turns: [+ turn("t1", "user", "alpha question about receipts before compaction", 1),+ turn("t2", "assistant", "alpha answer about receipts before compaction", 2),+ turn("t3", "user", "beta question about invoices before compaction", 3),+ turn("t4", "assistant", "beta answer about invoices before compaction", 4),+ ],+ summaryGroupSize: 2,+ createdAt: "2026-07-01T09:00:10.000Z",+ });+ importSessionRecall(vault, {+ sessionId: "child-seg",+ turns: [+ turn("t5", "user", "gamma question about refunds after compaction", 61),+ turn("t6", "assistant", "gamma answer about refunds after compaction", 62),+ turn("t7", "user", "delta question about credits after compaction", 63),+ turn("t8", "assistant", "delta answer about credits after compaction", 64),+ ],+ summaryGroupSize: 2,+ createdAt: "2026-07-01T09:01:10.000Z",+ lineage: { rootId: "root-seg", parentId: "root-seg", depth: 1, source: "payload" },+ });+}++describe("coverage-first selection core", () => {+ test("returns turns touching every detected facet, chronologically, with recomputable diagnostics", () => {+ importLineageThread();++ const coverage = coverageSessionRecall(vault, {+ sessionId: "child-seg",+ charBudget: 100_000,+ });++ // Every depth-1 cluster's turns are covered: the four clusters+ // partition the eight turns, so all eight turns come back.+ expect(coverage.turns.map((t) => t.turn_id)).toEqual([+ "t1",+ "t2",+ "t3",+ "t4",+ "t5",+ "t6",+ "t7",+ "t8",+ ]);++ const diagnostics = coverage.diagnostics;+ expect(diagnostics.facets_detected).toBe(4);+ expect(diagnostics.topics_realized).toBe(4);+ expect(diagnostics.chars_used).toBeGreaterThan(0);+ expect(diagnostics.dropped_turn_ids).toEqual([]);++ // Recomputable: the topic keys are exactly the in-scope depth-1+ // summary node ids, derivable from the record set alone.+ const depthOneIds = listContinuityRecords(vault)+ .filter((record) => record.kind === "session_summary_node" && record.payload["depth"] === 1)+ .map((record) => record.id)+ .toSorted();+ expect(diagnostics.topics.map((topic) => topic.key).toSorted()).toEqual(+ depthOneIds.map((id) => `cluster:${id}`).toSorted(),+ );+ expect(diagnostics.topics.every((topic) => topic.turn_count === 2)).toBe(true);+ // The adaptive topic budget: four facets floor at 12, and the+ // diagnostics report the four realized topics honestly.+ expect(diagnostics.topics_requested).toBe(12);+ });++ test("coverage across the lineage boundary reaches the root segment from the child id", () => {+ importLineageThread();+ const coverage = coverageSessionRecall(vault, { sessionId: "root-seg", charBudget: 100_000 });+ expect(coverage.turns.map((t) => t.turn_id)).toEqual([+ "t1",+ "t2",+ "t3",+ "t4",+ "t5",+ "t6",+ "t7",+ "t8",+ ]);+ });++ test("a scope with no coverage-bearing records returns an honest empty result", () => {+ importLineageThread();+ const coverage = coverageSessionRecall(vault, {+ sessionId: "no-such-session",+ charBudget: 100_000,+ });+ expect(coverage.turns).toEqual([]);+ expect(coverage.diagnostics.facets_detected).toBe(0);+ expect(coverage.diagnostics.topics_realized).toBe(0);+ expect(coverage.diagnostics.chars_used).toBe(0);+ });++ test("a non-positive character budget is refused by name", () => {+ importLineageThread();+ expect(() => coverageSessionRecall(vault, { sessionId: "root-seg", charBudget: 0 })).toThrow(+ /must be a positive finite number/,+ );+ });+});++describe("adaptive topic budget over coverage", () => {+ function importFacetThread(facets: number): void {+ importSessionRecall(vault, {+ sessionId: "facet-seg",+ turns: Array.from({ length: facets }, (_, index) =>+ turn(`t${index + 1}`, "user", `topic ${index + 1} distinct material`, index + 1),+ ),+ summaryGroupSize: 1,+ createdAt: "2026-07-02T09:00:00.000Z",+ });+ }++ test("a 40-facet thread caps the budget at 16", () => {+ importFacetThread(40);+ const coverage = coverageSessionRecall(vault, {+ sessionId: "facet-seg",+ charBudget: 1_000_000,+ });+ expect(coverage.diagnostics.facets_detected).toBe(40);+ expect(coverage.diagnostics.topics_requested).toBe(16);+ expect(coverage.diagnostics.topics_realized).toBe(16);+ // Groups of one: each realized cluster establishes exactly one turn,+ // so the capped fan-out reaches the first 16 turns of the thread.+ expect(coverage.turns).toHaveLength(16);+ });++ test("a 3-facet thread floors at 12 and reports 3 realized topics honestly", () => {+ importFacetThread(3);+ const coverage = coverageSessionRecall(vault, { sessionId: "facet-seg", charBudget: 100_000 });+ expect(coverage.diagnostics.topics_requested).toBe(12);+ expect(coverage.diagnostics.topics_realized).toBe(3);+ expect(coverage.diagnostics.topics).toHaveLength(3);+ expect(coverage.turns.map((t) => t.turn_id)).toEqual(["t1", "t2", "t3"]);+ });++ test("coverage is deterministic across repeated calls", () => {+ importLineageThread();+ const first = coverageSessionRecall(vault, { sessionId: "child-seg", charBudget: 100_000 });+ const second = coverageSessionRecall(vault, { sessionId: "child-seg", charBudget: 100_000 });+ expect(JSON.parse(JSON.stringify(first))).toEqual(JSON.parse(JSON.stringify(second)));+ });+});++describe("mined-key facets", () => {+ function importMinedThread(): void {+ importSessionRecall(vault, {+ sessionId: "mined-seg",+ turns: [+ turn("t1", "user", "call `SessionStore` for the receipts flow", 1),+ turn("t2", "assistant", "SessionStore keeps the receipt ledger", 2),+ turn("t3", "user", "unrelated turn about weather", 3),+ ],+ summaryGroupSize: 2,+ createdAt: "2026-07-03T09:00:00.000Z",+ });+ // The mined-mention ledger row the session miner would have written+ // for t1 (one record per family/key/session).+ appendContinuityRecord(vault, {+ kind: "session_entity_mention",+ createdAt: "2026-07-03T09:00:01.000Z",+ sourceRefs: [{ id: "mined-seg:t1:symbol:SessionStore" }],+ payload: { family: "symbol", key: "SessionStore", session_ref: "mined-seg", turn_id: "t1" },+ });+ }++ test("mined keys join the fan-out and match every turn that carries them", () => {+ importMinedThread();+ const coverage = coverageSessionRecall(vault, { sessionId: "mined-seg", charBudget: 100_000 });+ const mined = coverage.diagnostics.topics.find((topic) => topic.origin === "mined");+ expect(mined).toMatchObject({ key: "mined:symbol:SessionStore", turn_count: 1 });+ // The wide pass matches every in-scope turn carrying the key, not+ // only the establishing turn: t2 mentions it too and is returned.+ expect(coverage.turns.map((t) => t.turn_id)).toEqual(["t1", "t2", "t3"]);+ });++ test("a mention scoped outside the requested session contributes no facet", () => {+ importMinedThread();+ const coverage = coverageSessionRecall(vault, {+ sessionId: "other-seg",+ charBudget: 100_000,+ });+ expect(coverage.diagnostics.topics.filter((topic) => topic.origin === "mined")).toEqual([]);+ });+});++describe("entity-thread wiring", () => {+ function importTwoSessions(): void {+ importSessionRecall(vault, {+ sessionId: "seg-a",+ turns: [+ turn("a1", "user", "call `SessionStore` for the receipts flow", 1),+ turn("a2", "assistant", "SessionStore keeps the receipt ledger", 2),+ turn("a3", "user", "unrelated turn about weather", 3),+ ],+ summaryGroupSize: 2,+ createdAt: "2026-07-03T09:00:00.000Z",+ });+ importSessionRecall(vault, {+ sessionId: "seg-b",+ turns: [+ turn("b1", "user", "migrate `SessionStore` behind the flag", 31),+ turn("b2", "assistant", "done; SessionStore is feature-flagged", 32),+ ],+ summaryGroupSize: 2,+ createdAt: "2026-07-03T09:02:00.000Z",+ });+ }++ /** One mined-mention ledger row, the shape `mineAndRecordTurn` writes. */+ function mention(sessionRef: string, turnId: string, key = "SessionStore"): void {+ appendContinuityRecord(vault, {+ kind: "session_entity_mention",+ createdAt: "2026-07-03T09:00:01.000Z",+ sourceRefs: [{ id: `${sessionRef}:${turnId}:symbol:${key}` }],+ payload: { family: "symbol", key, session_ref: sessionRef, turn_id: turnId },+ });+ }++ test("a coverage call seeded by an entity key returns the turns that establish it, chronologically", () => {+ importTwoSessions();+ mention("seg-a", "a1");+ mention("seg-b", "b1");++ const coverage = coverageSessionRecall(vault, {+ entityKey: "SessionStore",+ charBudget: 1_000_000,+ });++ const ids = coverage.turns.map((t) => t.turn_id);+ // The establishing turns of BOTH mentioned sessions are in the+ // selection, in `compareRecords` chronological order across them.+ expect(ids).toContain("a1");+ expect(ids).toContain("b1");+ expect(ids.indexOf("a1")).toBeLessThan(ids.indexOf("b1"));+ // The seeded key leads the fan-out, so the topic budget can never+ // cut the facet the call was seeded for.+ expect(coverage.diagnostics.topics[0]).toMatchObject({+ key: "mined:symbol:SessionStore",+ origin: "mined",+ });+ // The scope is the mentioned sessions' record set, so the diagnostics+ // stay recomputable from it.+ expect(coverage.diagnostics.facets_detected).toBeGreaterThan(0);+ expect(coverage.diagnostics.topics_requested).toBeGreaterThanOrEqual(+ coverage.diagnostics.topics_realized,+ );+ });++ test("an unknown entity key raises the typed error, never an empty silent result", () => {+ importTwoSessions();+ let probe: SessionCoverageEntityUnknownError | null = null;+ try {+ coverageSessionRecall(vault, { entityKey: "NoSuchKey", charBudget: 100_000 });+ } catch (err) {+ probe = err as SessionCoverageEntityUnknownError;+ }+ expect(probe).not.toBeNull();+ expect(probe).toBeInstanceOf(SessionCoverageEntityUnknownError);+ expect(probe!.name).toBe("SessionCoverageEntityUnknownError");+ expect(probe!.entityKey).toBe("NoSuchKey");+ expect(probe!.reason).toBe("no_mention_rows");+ expect(probe!.message).toContain("NoSuchKey");+ });++ test("a key whose establishing turns the recall DAG never imported raises the same family", () => {+ importTwoSessions();+ mention("seg-never-imported", "x1");+ let probe: SessionCoverageEntityUnknownError | null = null;+ try {+ coverageSessionRecall(vault, { entityKey: "SessionStore", charBudget: 100_000 });+ } catch (err) {+ probe = err as SessionCoverageEntityUnknownError;+ }+ expect(probe).not.toBeNull();+ expect(probe!.reason).toBe("no_imported_turns");+ expect(probe!.mentionRows).toBe(1);+ expect(probe!.message).toContain("SessionStore");+ });++ test("a seed that names turns outside the requested session scope raises, not silently widens", () => {+ importTwoSessions();+ mention("seg-a", "a1");+ expect(() =>+ coverageSessionRecall(vault, {+ entityKey: "SessionStore",+ sessionId: "seg-b",+ charBudget: 100_000,+ }),+ ).toThrow(SessionCoverageEntityUnknownError);+ });++ test("at remote reach both seed refusals share one message: withheld existence is withheld", () => {+ importTwoSessions();+ // A key whose ONLY establishing turn is a private row: the mention row+ // exists and is not itself private, the turn is withheld at remote+ // reach - the exact case where the old pair of distinct refusal+ // messages told a remote caller that rows exist for a withheld key.+ appendContinuityRecord(vault, {+ kind: "session_turn",+ createdAt: "2026-07-09T09:00:00.000Z",+ sourceRefs: [],+ private: true,+ payload: {+ session_id: "seg-a",+ turn_id: "p1",+ timestamp: "2026-07-03T09:00:30.000Z",+ role: "user",+ text: "SecretKey gossip inside a private region",+ },+ });+ appendContinuityRecord(vault, {+ kind: "session_entity_mention",+ createdAt: "2026-07-09T09:00:01.000Z",+ sourceRefs: [{ id: "seg-a:p1:symbol:SecretKey" }],+ payload: { family: "symbol", key: "SecretKey", session_ref: "seg-a", turn_id: "p1" },+ });++ const refusalOf = (entityKey: string): string => {+ try {+ coverageSessionRecall(vault, { entityKey, charBudget: 100_000, withholdPrivate: true });+ } catch (err) {+ return (err as SessionCoverageEntityUnknownError).message;+ }+ return "";+ };+ // Both withheld refusals answer with the no-rows wording: whether+ // mention rows exist for a withheld key is itself withheld.+ expect(refusalOf("SecretKey")).toBe(+ "session recall coverage: no session_entity_mention row names the entity key SecretKey",+ );+ expect(refusalOf("SecretKey")).not.toContain("mention row(s)");+ // The local caller keeps the distinguishing diagnostics.+ expect(() =>+ coverageSessionRecall(vault, { entityKey: "NoSuchKey", charBudget: 100_000 }),+ ).toThrow(/no session_entity_mention row names/);+ // And locally the private turn still establishes its key.+ const local = coverageSessionRecall(vault, { entityKey: "SecretKey", charBudget: 100_000 });+ expect(local.turns.map((t) => t.turn_id)).toContain("p1");+ });++ test("a multi-session seed selects in chronological order, not mention-row order", () => {+ importTwoSessions();+ // The ledger holds seg-b's row first: the deduplicated scope must not+ // inherit that order, or facet order - and therefore which facets+ // survive the topic budget - follows mention-row order.+ mention("seg-b", "b1");+ mention("seg-a", "a1");++ const coverage = coverageSessionRecall(vault, {+ entityKey: "SessionStore",+ charBudget: 1_000_000,+ });+ // The mined seed still leads the fan-out; the CLUSTER facets follow in+ // scope order: the chronologically earlier session's first cluster+ // first, whatever order the mention rows hold.+ expect(coverage.diagnostics.topics[0]!.origin).toBe("mined");+ const aNode = listContinuityRecords(vault)+ .filter(+ (record) =>+ record.kind === "session_summary_node" &&+ record.payload["depth"] === 1 &&+ record.payload["session_id"] === "seg-a" &&+ Array.isArray(record.payload["source_record_ids"]) &&+ (record.payload["source_record_ids"] as unknown[]).length === 2,+ )+ .map((record) => record.id)[0]!;+ const clusterKeys = coverage.diagnostics.topics+ .map((topic) => topic.key)+ .filter((key) => key.startsWith("cluster:"));+ expect(clusterKeys[0]).toBe(`cluster:${aNode}`);+ });+});++describe("session-qualified turn identity in the coverage path", () => {+ function importIdenticalIdSessions(): void {+ // Two independent sessions whose transcripts reuse the SAME turn ids:+ // SessionTurn.turnId can repeat across sessions, so a bare turn_id is+ // not a turn identity wherever a multi-session scope can mix them.+ importSessionRecall(vault, {+ sessionId: "dup-a",+ turns: [+ turn("t1", "user", "call `SessionStore` in session A", 1),+ turn("t2", "assistant", "receipt ledger notes in session A", 2),+ ],+ summaryGroupSize: 2,+ createdAt: "2026-07-06T09:00:00.000Z",+ });+ importSessionRecall(vault, {+ sessionId: "dup-b",+ turns: [+ turn("t1", "user", "the migration plan lands in session B", 61),+ turn("t2", "assistant", "more migration detail in session B", 62),+ ],+ summaryGroupSize: 2,+ createdAt: "2026-07-06T09:01:00.000Z",+ });+ }++ /** One mined-mention ledger row, the shape `mineAndRecordTurn` writes. */+ function mention(sessionRef: string, turnId: string): void {+ appendContinuityRecord(vault, {+ kind: "session_entity_mention",+ createdAt: "2026-07-06T09:02:00.000Z",+ sourceRefs: [{ id: `${sessionRef}:${turnId}:symbol:SessionStore` }],+ payload: { family: "symbol", key: "SessionStore", session_ref: sessionRef, turn_id: turnId },+ });+ }++ test("an entity seed resolves per session: a cluster of one dup-id session cannot select the other's turns", () => {+ importIdenticalIdSessions();+ mention("dup-a", "t1");+ mention("dup-b", "t1");++ const coverage = coverageSessionRecall(vault, {+ entityKey: "SessionStore",+ charBudget: 1_000_000,+ });++ // The mined facet counts one establishing turn PER SESSION: the two+ // (session, turn) pairs are two turns, not one bare id counted once.+ expect(coverage.diagnostics.topics[0]).toMatchObject({+ key: "mined:symbol:SessionStore",+ origin: "mined",+ turn_count: 2,+ });+ // dup-b's turns carry none of the mined needle text, so only its own+ // cluster facet can surface them: the cluster of dup-b must resolve+ // to dup-b's turns, never to the same-named turns of dup-a.+ const texts = coverage.turns.map((t) => t.text);+ expect(texts.some((text) => text.includes("in session B"))).toBe(true);+ expect(texts.some((text) => text.includes("in session A"))).toBe(true);+ });++ test("a mention naming only session A's turn does not satisfy a B-scoped seed", () => {+ importIdenticalIdSessions();+ mention("dup-a", "t1");+ let probe: SessionCoverageEntityUnknownError | null = null;+ try {+ coverageSessionRecall(vault, {+ entityKey: "SessionStore",+ sessionId: "dup-b",+ charBudget: 100_000,+ });+ } catch (err) {+ probe = err as SessionCoverageEntityUnknownError;+ }+ // dup-b imports turns named t1/t2 too, but the seed's establishing+ // turn is (dup-a, t1): the bare-id match must not stand in for it.+ expect(probe).not.toBeNull();+ expect(probe).toBeInstanceOf(SessionCoverageEntityUnknownError);+ expect(probe!.reason).toBe("no_imported_turns");+ expect(probe!.mentionRows).toBe(1);+ });+});++describe("typed floor-violation infeasibility", () => {+ test("a budget below the floor-weighted selection raises the typed error, named fields", () => {+ importLineageThread();+ let probe: SessionCoverageInfeasibleError | null = null;+ try {+ coverageSessionRecall(vault, { sessionId: "child-seg", charBudget: 1 });+ } catch (err) {+ probe = err as SessionCoverageInfeasibleError;+ }+ expect(probe).not.toBeNull();+ expect(probe).toBeInstanceOf(SessionCoverageInfeasibleError);+ expect(probe!.name).toBe("SessionCoverageInfeasibleError");+ expect(probe!.topicFloor).toBe(12);+ // Four realized topics; the floor target is all four (min(4, 12)).+ expect(probe!.requestedTopics).toBe(4);+ expect(probe!.keptTopics).toBe(0);+ expect(probe!.requiredChars).toBeGreaterThan(1);+ // The message names requested topics, kept topics and required chars.+ expect(probe!.message).toContain(`required chars ${probe!.requiredChars}`);+ expect(probe!.message).toContain(`kept topics ${probe!.keptTopics}`);+ expect(probe!.message).toContain(`requested topics ${probe!.requestedTopics}`);+ });++ test("a floor topic realizes on any kept turn, not only its top-ranked one", () => {+ // The mined key's top-ranked turn is a pasted log: the most occurrences+ // give it the highest score AND the largest body, so the greedy budget+ // skips it. The topic's small second mention fits - and that is enough+ // to realize the topic. The guard used to demand the TOP-ranked turn+ // and refused a budget the real selection satisfied.+ const logText = `${"SessionStore pinged ".repeat(60)}end of pasted log`;+ importSessionRecall(vault, {+ sessionId: "mined-crowd-seg",+ turns: [+ turn("t1", "user", logText, 1),+ turn("t2", "assistant", "SessionStore noted", 2),+ turn("t3", "user", "unrelated weather chat", 3),+ turn("t4", "assistant", "more unrelated chat", 4),+ ],+ summaryGroupSize: 2,+ createdAt: "2026-07-07T09:00:00.000Z",+ });+ appendContinuityRecord(vault, {+ kind: "session_entity_mention",+ createdAt: "2026-07-07T09:00:01.000Z",+ sourceRefs: [{ id: "mined-crowd-seg:t1:symbol:SessionStore" }],+ payload: {+ family: "symbol",+ key: "SessionStore",+ session_ref: "mined-crowd-seg",+ turn_id: "t1",+ },+ });+ const serialized = listSessionRawTurns(vault, "mined-crowd-seg").map((t) => JSON.stringify(t));+ // The log outranks everything (2 + occurrences) and dwarfs the budget;+ // the small second mention, plus the second cluster's turns, fit.+ const budget =+ [...serialized[1]!].length + [...serialized[2]!].length + [...serialized[3]!].length;+ expect([...serialized[0]!].length).toBeGreaterThan(budget);++ const coverage = coverageSessionRecall(vault, {+ sessionId: "mined-crowd-seg",+ charBudget: budget,+ });+ // Every floor topic keeps evidence; the skipped log is named in the+ // diagnostics, never a refusal.+ expect(coverage.turns.map((t) => t.turn_id)).toEqual(["t2", "t3", "t4"]);+ expect(coverage.diagnostics.dropped_turn_ids).toEqual(["t1"]);+ expect(coverage.diagnostics.topics_realized).toBe(3);+ });++ test("a floor topic with no budget for any of its turns still raises, priced per cheapest turn", () => {+ // Two depth-1 clusters: {t1, t2} serialized long, {t3, t4} short. The+ // selection is rank-ordered, so the long cluster's turns can spend the+ // whole budget before the short cluster's first turn is reached - and+ // the short floor topic keeps zero evidence. The typed error stays for+ // that genuinely impossible budget; requiredChars prices the cheapest+ // turn per floor topic, the honest retry bound.+ const longText = "x".repeat(2400);+ importSessionRecall(vault, {+ sessionId: "crowd-seg",+ turns: [+ turn("t1", "user", longText, 1),+ turn("t2", "assistant", longText, 2),+ turn("t3", "user", "short floor-topic evidence", 3),+ turn("t4", "assistant", "more short floor-topic evidence", 4),+ ],+ summaryGroupSize: 2,+ createdAt: "2026-07-04T09:00:00.000Z",+ });+ const serialized = listSessionRawTurns(vault, "crowd-seg").map((t) => JSON.stringify(t));+ // The budget holds the long cluster's turns exactly plus one char:+ // the greedy rank-order pass keeps t1 and t2 and drops t3 and t4.+ const budget = serialized[0]!.length + serialized[1]!.length + 1;++ let probe: SessionCoverageInfeasibleError | null = null;+ try {+ coverageSessionRecall(vault, { sessionId: "crowd-seg", charBudget: budget });+ } catch (err) {+ probe = err as SessionCoverageInfeasibleError;+ }+ expect(probe).not.toBeNull();+ expect(probe).toBeInstanceOf(SessionCoverageInfeasibleError);+ // requiredChars prices the cheapest turn per floor topic: one long+ // turn for the first cluster, t3 for the short one.+ expect(probe!.requiredChars).toBe([...serialized[0]!].length + [...serialized[2]!].length);+ expect(probe!.charBudget).toBe(budget);+ // The bound is honest: at it the greedy pass keeps one turn per topic+ // and the turns ranked behind them are still dropped, visibly.+ const at = coverageSessionRecall(vault, {+ sessionId: "crowd-seg",+ charBudget: probe!.requiredChars,+ });+ expect(at.turns.map((t) => t.turn_id)).toEqual(["t1", "t3"]);+ expect(at.diagnostics.dropped_turn_ids).toEqual(["t2", "t4"]);+ });++ test("astral-plane turns spend code points: a feasible budget is never falsely refused", () => {+ // Two depth-1 clusters, the long one emoji-heavy: UTF-16 length counts+ // each astral character twice, while the real selection+ // (`applyCharBudget`) spends code points. A budget sized to the+ // code-point requirement through the deepest floor-top rank is+ // feasible by construction, so the floor guard must accept it - the+ // UTF-16 rank-prefix arithmetic refuses the very same budget.+ const emojiText = "\u{1F600}".repeat(200); // 400 UTF-16 units, 200 code points, still inline+ importSessionRecall(vault, {+ sessionId: "astral-seg",+ turns: [+ turn("t1", "user", emojiText, 1),+ turn("t2", "assistant", emojiText, 2),+ turn("t3", "user", "short floor-topic evidence", 3),+ turn("t4", "assistant", "more short floor-topic evidence", 4),+ ],+ summaryGroupSize: 2,+ createdAt: "2026-07-05T09:00:00.000Z",+ });+ const serialized = listSessionRawTurns(vault, "astral-seg").map((t) => JSON.stringify(t));+ const utf16Requirement = serialized[0]!.length + serialized[1]!.length + serialized[2]!.length;+ const codePointRequirement =+ [...serialized[0]!].length + [...serialized[1]!].length + [...serialized[2]!].length;+ // The UTF-16 arithmetic exceeds the budget the real selection needs.+ expect(utf16Requirement).toBeGreaterThan(codePointRequirement);++ const coverage = coverageSessionRecall(vault, {+ sessionId: "astral-seg",+ charBudget: codePointRequirement,+ });+ // Every floor topic keeps its top turn; only the turn ranked behind+ // the floor is dropped, visibly.+ expect(coverage.turns.map((t) => t.turn_id)).toEqual(["t1", "t2", "t3"]);+ expect(coverage.diagnostics.chars_used).toBe(codePointRequirement);+ expect(coverage.diagnostics.dropped_turn_ids).toEqual(["t4"]);+ });++ test("requiredChars speaks the spender's unit: astral turns are priced in code points", () => {+ // The infeasibility diagnostics must price the rank-ordered selection+ // the way applyCharBudget spends it - code points, not UTF-16 units -+ // or the retry bound it reports is not the honest one for astral+ // content: the UTF-16 arithmetic overcounts every astral character+ // twice and reports a bound above the real requirement.+ const emojiText = "\u{1F600}".repeat(200); // 400 UTF-16 units, 200 code points+ importSessionRecall(vault, {+ sessionId: "astral-floor-seg",+ turns: [+ turn("t1", "user", emojiText, 1),+ turn("t2", "assistant", emojiText, 2),+ turn("t3", "user", "short floor-topic evidence", 3),+ turn("t4", "assistant", "more short floor-topic evidence", 4),+ ],+ summaryGroupSize: 2,+ createdAt: "2026-07-05T10:00:00.000Z",+ });+ const serialized = listSessionRawTurns(vault, "astral-floor-seg").map((t) => JSON.stringify(t));+ const utf16Requirement = serialized[0]!.length + serialized[1]!.length + serialized[2]!.length;+ const codePointRequirement =+ [...serialized[0]!].length + [...serialized[1]!].length + [...serialized[2]!].length;+ expect(utf16Requirement).toBeGreaterThan(codePointRequirement);++ let probe: SessionCoverageInfeasibleError | null = null;+ try {+ coverageSessionRecall(vault, { sessionId: "astral-floor-seg", charBudget: 1 });+ } catch (err) {+ probe = err as SessionCoverageInfeasibleError;+ }+ expect(probe).toBeInstanceOf(SessionCoverageInfeasibleError);+ // Cheapest turn per floor topic, priced in code points: one astral+ // turn for the first cluster, the short t3 for the second.+ expect(probe!.requiredChars).toBe([...serialized[0]!].length + [...serialized[2]!].length);+ // The bound stays exact: at it the floor holds, one below it fails.+ const at = coverageSessionRecall(vault, {+ sessionId: "astral-floor-seg",+ charBudget: probe!.requiredChars,+ });+ expect(at.turns.map((t) => t.turn_id)).toEqual(["t1", "t3"]);+ expect(() =>+ coverageSessionRecall(vault, {+ sessionId: "astral-floor-seg",+ charBudget: probe!.requiredChars - 1,+ }),+ ).toThrow(SessionCoverageInfeasibleError);+ });++ test("requiredChars is the exact retry bound: at it, no error; one below, the error", () => {+ // Groups of one: every turn is its own floor topic, so the floor's+ // honest requirement - the cheapest turn of every topic - is the whole+ // thread, and the rank-ordered selection realizes it exactly at the+ // bound and drops the last topic one character below it.+ importSessionRecall(vault, {+ sessionId: "bound-seg",+ turns: [+ turn("t1", "user", "alpha topic evidence", 1),+ turn("t2", "assistant", "beta topic evidence", 2),+ turn("t3", "user", "gamma topic evidence", 3),+ turn("t4", "assistant", "delta topic evidence", 4),+ ],+ summaryGroupSize: 1,+ createdAt: "2026-07-08T09:00:00.000Z",+ });+ let requiredChars: number;+ try {+ coverageSessionRecall(vault, { sessionId: "bound-seg", charBudget: 1 });+ throw new Error("expected the typed infeasibility error");+ } catch (err) {+ requiredChars = (err as SessionCoverageInfeasibleError).requiredChars;+ }+ const at = coverageSessionRecall(vault, {+ sessionId: "bound-seg",+ charBudget: requiredChars,+ });+ // At the requirement every floor topic is represented.+ expect(at.diagnostics.topics_realized).toBe(4);+ expect(at.diagnostics.chars_used).toBeLessThanOrEqual(requiredChars);+ expect(() =>+ coverageSessionRecall(vault, { sessionId: "bound-seg", charBudget: requiredChars - 1 }),+ ).toThrow(SessionCoverageInfeasibleError);+ });++ test("above the floor, drops land in diagnostics and never throw", () => {+ // The long-cluster/short-cluster thread: the floor's honest+ // requirement is one cheapest turn per topic, so a little above it+ // the remaining turns are dropped, visibly - every dropped turn is+ // named, and kept plus dropped still accounts for the whole thread.+ const longText = "x".repeat(2400);+ importSessionRecall(vault, {+ sessionId: "drops-seg",+ turns: [+ turn("t1", "user", longText, 1),+ turn("t2", "assistant", longText, 2),+ turn("t3", "user", "short floor-topic evidence", 3),+ turn("t4", "assistant", "more short floor-topic evidence", 4),+ ],+ summaryGroupSize: 2,+ createdAt: "2026-07-04T10:00:00.000Z",+ });+ let requiredChars: number;+ try {+ coverageSessionRecall(vault, { sessionId: "drops-seg", charBudget: 1 });+ throw new Error("expected the typed infeasibility error");+ } catch (err) {+ requiredChars = (err as SessionCoverageInfeasibleError).requiredChars;+ }+ const coverage = coverageSessionRecall(vault, {+ sessionId: "drops-seg",+ charBudget: requiredChars + 10,+ });+ expect(coverage.turns.length).toBeGreaterThan(0);+ expect(coverage.diagnostics.dropped_turn_ids.length).toBeGreaterThan(0);+ expect(coverage.turns.length + coverage.diagnostics.dropped_turn_ids.length).toBe(4);+ expect(coverage.diagnostics.chars_used).toBeLessThanOrEqual(requiredChars + 10);+ expect(coverage.diagnostics.topics_realized).toBe(2);+ });+});++describe("omitted-operation byte-identity (grep unchanged)", () => {+ function seedFrozen(): void {+ importSessionRecall(vault, {+ sessionId: "session-frozen",+ turns: [+ turn("t1", "user", "Find continuity receipt details.", 1),+ turn("t2", "assistant", "Receipt summary with tests.", 2),+ ],+ summaryGroupSize: 2,+ createdAt: "2026-07-01T09:00:00.000Z",+ });+ }++ test("grep output equals the frozen pre-coverage fixture", () => {+ seedFrozen();+ const result = searchSessionRecall(vault, {+ query: "receipt",+ sessionId: "session-frozen",+ limit: 4,+ });+ // Frozen fixture: the full serialized outcome of the pre-coverage+ // search path, pinned so the coverage lane's arrival cannot perturb+ // the operation it rides beside.+ expect(JSON.parse(JSON.stringify(result))).toEqual({+ hits: [+ {+ id: "ctn_20260701090000_5fae660366cad639",+ kind: "session_summary_node",+ score: 3,+ snippet:+ "t1 user: Find continuity receipt details.\nt2 assistant: Receipt summary with tests.",+ line_start: 1,+ line_end: 1,+ depth: 1,+ source_record_ids: [+ "ctn_20260701090000_ae7c6b3f8780ed24",+ "ctn_20260701090000_e65d39ed24f732ab",+ ],+ },+ {+ id: "ctn_20260701090000_ae7c6b3f8780ed24",+ kind: "session_turn",+ score: 3,+ snippet: "Find continuity receipt details.",+ line_start: 1,+ line_end: 1,+ turn_id: "t1",+ role: "user",+ },+ {+ id: "ctn_20260701090000_e65d39ed24f732ab",+ kind: "session_turn",+ score: 3,+ snippet: "Receipt summary with tests.",+ line_start: 1,+ line_end: 1,+ turn_id: "t2",+ role: "assistant",+ },+ ],+ });+ });+});diff --git a/tests/core/brain/thread-topics.test.ts b/tests/core/brain/thread-topics.test.tsnew file mode 100644index 00000000..8e70d37d--- /dev/null+++ b/tests/core/brain/thread-topics.test.ts@@ -0,0 +1,132 @@+/**+ * Thread topics - pure facet detection and the adaptive topic budget+ * (recall-quality wave, Lane B / t_2c2a883c).+ *+ * Facets are derived from the thread itself (distinct mined entity keys+ * and depth-1 summary clusters), and the topic budget is the corpus-+ * shaped clamp: budget = clamp(distinct facets, floor 12, cap 16). The+ * diagnostics report the realized topic count honestly - a 3-facet+ * thread floors at 12 and says 3 were realized.+ */++import { describe, expect, test } from "bun:test";++import {+ TOPIC_BUDGET_CAP,+ TOPIC_BUDGET_FLOOR,+ clampTopicBudget,+ detectThreadFacets,+ resolveTopicBudget,+} from "../../../src/core/brain/thread-topics.ts";++describe("adaptive topic budget", () => {+ test("the floor and cap are exported constants, floor below cap", () => {+ expect(TOPIC_BUDGET_FLOOR).toBe(12);+ expect(TOPIC_BUDGET_CAP).toBe(16);+ });++ test("budget = clamp(distinct facets, 12, 16) with realized never above facets", () => {+ expect(resolveTopicBudget(40)).toEqual({ budget: 16, realized: 16 });+ expect(resolveTopicBudget(3)).toEqual({ budget: 12, realized: 3 });+ expect(resolveTopicBudget(14)).toEqual({ budget: 14, realized: 14 });+ expect(resolveTopicBudget(0)).toEqual({ budget: 12, realized: 0 });+ expect(resolveTopicBudget(12)).toEqual({ budget: 12, realized: 12 });+ expect(resolveTopicBudget(16)).toEqual({ budget: 16, realized: 16 });+ expect(resolveTopicBudget(100)).toEqual({ budget: 16, realized: 16 });+ });++ test("clampTopicBudget agrees with resolveTopicBudget's budget", () => {+ for (const facets of [0, 1, 3, 11, 12, 13, 16, 17, 40]) {+ expect(clampTopicBudget(facets)).toBe(resolveTopicBudget(facets).budget);+ }+ });++ test("pure and deterministic across repeated calls", () => {+ const first = resolveTopicBudget(3);+ const second = resolveTopicBudget(3);+ expect(first).toEqual(second);+ expect(first).not.toBe(second);+ });+});++describe("facet detection", () => {+ const TURNS = ["t1", "t2", "t3", "t4", "t5"];++ test("mined mentions group into family-scoped facets over in-scope turns", () => {+ const facets = detectThreadFacets({+ turns: TURNS,+ mentions: [+ { family: "symbol", key: "SessionStore", turnId: "t1" },+ { family: "symbol", key: "SessionStore", turnId: "t3" },+ { family: "symbol", key: "sessionstore", turnId: "t2" },+ { family: "path", key: "~/src/store.ts", turnId: "t4" },+ ],+ clusters: [],+ });+ expect(facets.map((f) => f.key)).toEqual([+ "mined:symbol:SessionStore",+ "mined:symbol:sessionstore",+ "mined:path:~/src/store.ts",+ ]);+ expect(facets[0]).toMatchObject({+ origin: "mined",+ needle: "SessionStore",+ turnIds: ["t1", "t3"],+ });+ });++ test("clusters become membership facets holding their in-scope turns", () => {+ const facets = detectThreadFacets({+ turns: TURNS,+ mentions: [],+ clusters: [+ { id: "node-a", turnIds: ["t1", "t2"] },+ { id: "node-b", turnIds: ["t3", "t9"] },+ ],+ });+ expect(facets.map((f) => f.key)).toEqual(["cluster:node-a", "cluster:node-b"]);+ expect(facets[1]!.turnIds).toEqual(["t3"]);+ expect(facets[1]!.needle).toBeNull();+ });++ test("facets order by their chronologically first establishing turn", () => {+ const facets = detectThreadFacets({+ turns: TURNS,+ mentions: [{ family: "symbol", key: "LateKey", turnId: "t4" }],+ clusters: [{ id: "node-early", turnIds: ["t1", "t2"] }],+ });+ expect(facets.map((f) => f.key)).toEqual(["cluster:node-early", "mined:symbol:LateKey"]);+ });++ test("facet ties break by code unit, not locale collation", () => {+ // "B" precedes "a" by code unit; a locale-aware collation would put+ // "a" first, making the facet order host-dependent.+ const facets = detectThreadFacets({+ turns: ["t1"],+ mentions: [+ { family: "symbol", key: "a", turnId: "t1" },+ { family: "symbol", key: "B", turnId: "t1" },+ ],+ clusters: [],+ });+ expect(facets.map((f) => f.key)).toEqual(["mined:symbol:B", "mined:symbol:a"]);+ });++ test("a facet with no in-scope establishing turn is not detected", () => {+ const facets = detectThreadFacets({+ turns: TURNS,+ mentions: [{ family: "url", key: "https://example.test/x", turnId: "t99" }],+ clusters: [{ id: "node-empty", turnIds: ["t42"] }],+ });+ expect(facets).toEqual([]);+ });++ test("deterministic across repeated calls on the same input", () => {+ const input = {+ turns: TURNS,+ mentions: [{ family: "symbol", key: "SessionStore", turnId: "t1" }],+ clusters: [{ id: "node-a", turnIds: ["t2"] }],+ };+ expect(detectThreadFacets(input)).toEqual(detectThreadFacets(input));+ });+});diff --git a/tests/core/search/coverage-targeted-recall.test.ts b/tests/core/search/coverage-targeted-recall.test.tsindex 52d2c042..d74eb8ed 100644--- a/tests/core/search/coverage-targeted-recall.test.ts+++ b/tests/core/search/coverage-targeted-recall.test.ts@@ -11,7 +11,11 @@import { test, expect, beforeEach, afterEach, describe } from "bun:test";-import { buildCoverageReport, planTargetedRetry } from "../../../src/core/search/coverage.ts";+import {+ buildCoverageReport,+ planSubQueryGroups,+ planTargetedRetry,+} from "../../../src/core/search/coverage.ts";import { indexVault } from "../../../src/core/search/indexer.ts";import { search } from "../../../src/core/search/search.ts";import { createTempVault, makeConfig, writeMd } from "../../helpers/search-fixtures.ts";@@ -71,6 +75,97 @@ describe("planTargetedRetry (pure decision)", () => {expect(cov.idfWeightedCoverage).toBe(0);expect(planTargetedRetry(cov).terms).toEqual(["fennel", "warehouse"]);});++ // ----- k-group generalization (recall-quality wave, lane A) ---------------++ /**+ * Three uncovered rare terms in query order with distinct IDF weights:+ * alcor is the most significant (df 1 of 1000), then zubrowka (df 5),+ * then mizar (df 10) - all within the 2% rare share of 20 documents.+ */+ const threeGaps = report(["mizar", "alcor", "zubrowka"], [], 1000, [+ ["mizar", 10],+ ["alcor", 1],+ ["zubrowka", 5],+ ]);++ test("emits one singleton group per uncovered rare term, ordered by significance", () => {+ const plan = planSubQueryGroups(threeGaps, 3);+ expect(plan.fire).toBe(true);+ expect(plan.groups).toHaveLength(3);+ // Most significant term first.+ expect(plan.groups[0]!.terms).toEqual(["alcor"]);+ expect(plan.groups[1]!.terms).toEqual(["zubrowka"]);+ expect(plan.groups[2]!.terms).toEqual(["mizar"]);+ // Significance descends across the ordered groups.+ expect(plan.groups[0]!.significance).toBeGreaterThan(plan.groups[1]!.significance);+ expect(plan.groups[1]!.significance).toBeGreaterThan(plan.groups[2]!.significance);+ });++ test("caps at k groups: the top term earns a singleton, the residual merges in query order", () => {+ const plan = planSubQueryGroups(threeGaps, 2);+ expect(plan.groups).toHaveLength(2);+ // The dedicated singleton goes to the highest-IDF term; the residual+ // keeps the historical merged-group shape (query order).+ expect(plan.groups.map((g) => g.terms)).toEqual([["mizar", "zubrowka"], ["alcor"]]);+ // Groups are ordered by significance: the merged pair outweighs the+ // singleton here (idf(10) + idf(5) > idf(1)).+ expect(plan.groups[0]!.significance).toBeGreaterThan(plan.groups[1]!.significance);+ });++ test("a single group reproduces the frozen round-two shape byte-identically", () => {+ // The k=1 projection IS today's targeted retry: one merged group, all+ // uncovered rare terms in query order, same fire gate.+ const single = planSubQueryGroups(threeGaps, 1);+ expect(single.fire).toBe(true);+ expect(single.groups).toHaveLength(1);+ expect(single.groups[0]!.terms).toEqual(["mizar", "alcor", "zubrowka"]);+ const legacy = planTargetedRetry(threeGaps);+ expect(legacy.fire).toBe(true);+ expect(legacy.terms).toEqual(single.groups[0]!.terms);+ // Frozen fixture: the historical decision on the documented partial+ // miss, unchanged by the generalization.+ const chandelier = report(+ ["warehouse", "rotation", "chandelier"],+ ["warehouse", "rotation"],+ 6,+ [+ ["warehouse", 4],+ ["rotation", 4],+ ["chandelier", 1],+ ],+ );+ expect(planTargetedRetry(chandelier)).toEqual({ fire: true, terms: ["chandelier"] });+ expect(planSubQueryGroups(chandelier, 3).groups[0]!.terms).toEqual(["chandelier"]);+ });++ test("zero groups when the coverage is complete", () => {+ const cov = report(["alpha", "beta"], ["alpha", "beta"], 10, [+ ["alpha", 3],+ ["beta", 3],+ ]);+ const plan = planSubQueryGroups(cov, 4);+ expect(plan.fire).toBe(false);+ expect(plan.groups).toEqual([]);+ });++ test("a maxGroups below one is clamped to the single merged group", () => {+ const plan = planSubQueryGroups(threeGaps, 0);+ expect(plan.groups).toHaveLength(1);+ expect(plan.groups[0]!.terms).toEqual(["mizar", "alcor", "zubrowka"]);+ });++ test("a non-finite coverage fails closed: no fire, no groups", () => {+ // A broken measurement (a non-finite number where the report contract+ // says a finite share or null) must not fire the gap signal. NaN+ // happened to miss the `<` gate on comparison semantics alone, while+ // -Infinity fired on it; the gate now refuses every non-finite report+ // explicitly, so failing closed is a stated rule, not an accident.+ const broken = { ...threeGaps, idfWeightedCoverage: Number.NaN };+ expect(planSubQueryGroups(broken, 4)).toEqual({ fire: false, groups: [] });+ const negative = { ...threeGaps, idfWeightedCoverage: Number.NEGATIVE_INFINITY };+ expect(planSubQueryGroups(negative, 4)).toEqual({ fire: false, groups: [] });+ });});describe("targeted recall on a partial miss (integration)", () => {diff --git a/tests/core/search/coverage-unmeasurable.test.ts b/tests/core/search/coverage-unmeasurable.test.tsindex f236d3ff..bba5cbe1 100644--- a/tests/core/search/coverage-unmeasurable.test.ts+++ b/tests/core/search/coverage-unmeasurable.test.ts@@ -21,6 +21,7 @@ import { test, expect, describe, beforeAll, afterAll } from "bun:test";import { indexVault } from "../../../src/core/search/indexer.ts";import { search } from "../../../src/core/search/search.ts";import { decideRecallInject } from "../../../src/core/brain/recall-inject.ts";+import { buildCoverageReport, planSubQueryGroups } from "../../../src/core/search/coverage.ts";import { createTempVault, writeMd, makeConfig } from "../../helpers/search-fixtures.ts";const { vault, dbPath, cleanup } = createTempVault("coverage-unmeasurable");@@ -102,4 +103,24 @@ describe("unmeasurable match quality", () => {// point of the floor reading quality instead.expect(decision.topScore).toBe(0.99);});++ test("the k-group planner yields zero groups for an unmeasurable coverage", () => {+ // A corpus with no documents gives every term idf ln(1) = 0, so there+ // is no IDF mass to take a share of and the coverage is null - the one+ // state where the gap signal must stay silent, because there is no+ // measurement naming what the sub-queries should aim at.+ const unmeasurable = buildCoverageReport({+ significantTerms: ["fennel", "warehouse"],+ coveredTerms: new Set(),+ documentCount: 0,+ dfByTerm: new Map([+ ["fennel", 0],+ ["warehouse", 0],+ ]),+ });+ expect(unmeasurable.idfWeightedCoverage).toBeNull();+ const plan = planSubQueryGroups(unmeasurable, 4);+ expect(plan.fire).toBe(false);+ expect(plan.groups).toEqual([]);+ });});diff --git a/tests/core/search/decider-step.test.ts b/tests/core/search/decider-step.test.tsnew file mode 100644index 00000000..27c94f82--- /dev/null+++ b/tests/core/search/decider-step.test.ts@@ -0,0 +1,482 @@+/**+ * Decider envelope and commit validators (recall-quality wave, lane A+ * Task 4): the needs-llm-step envelope builds only when measurable+ * coverage gaps remain, the commit phase refuses malformed shapes,+ * over-limit or oversized sub-queries, unknown evidence ids and+ * replayed round tokens with named typed errors, and an accepted+ * payload drives exactly one further round whose pool grows only by+ * the payload's sub-query pulls.+ */++import { test, expect, beforeEach, afterEach, describe } from "bun:test";++import {+ DECIDER_SUB_QUERIES_MAX,+ DECIDER_SUB_QUERY_LENGTH_MAX,+ DECIDER_STEP_NAME,+ DECIDER_STEP_RESUME_TARGET,+ DeciderStepError,+ buildDeciderStep,+ commitDeciderStep,+ makeRoundToken,+ nonceRoundToken,+ pauseStateDigest,+} from "../../../src/core/search/decider-step.ts";+import type { CoverageReport } from "../../../src/core/search/coverage.ts";+import { NEEDS_LLM_STEP } from "../../../src/core/brain/llm-step.ts";+import { ResponseShapeError } from "../../../src/core/brain/response-shape.ts";+import {+ ResponseCheckError,+ SEMANTIC_VIOLATION_CODES,+} from "../../../src/core/brain/response-checks.ts";+import { Store } from "../../../src/core/search/store.ts";+import { runFtsQueryDetailed } from "../../../src/core/search/fts.ts";+import { indexVault } from "../../../src/core/search/indexer.ts";+import { createTempVault, makeConfig, writeMd } from "../../helpers/search-fixtures.ts";+import {+ runDeciderRound,+ runIterativeRecall,+} from "../../../src/core/search/pipeline/iterative-recall.ts";++/** A measurable, partial coverage with named gaps: the envelope's home case. */+function gappedCoverage(): CoverageReport {+ const term = (t: string, covered: boolean, rare = true) => ({+ term: t,+ df: rare ? 1 : 40,+ idf: rare ? 3.2 : 0.1,+ rare,+ covered,+ });+ return Object.freeze({+ terms: Object.freeze([term("warehouse", true, false), term("chandelier", false)]),+ idfWeightedCoverage: 0.5,+ rareTerms: Object.freeze(["chandelier"]),+ uncoveredRareTerms: Object.freeze(["chandelier"]),+ });+}++/** A complete pool: the envelope must refuse it by name. */+function completeCoverage(): CoverageReport {+ const term = (t: string, covered: boolean, rare = false) => ({+ term: t,+ df: 40,+ idf: 0.1,+ rare,+ covered,+ });+ return Object.freeze({+ terms: Object.freeze([term("warehouse", true), term("rotation", true)]),+ idfWeightedCoverage: 0.95,+ rareTerms: Object.freeze([]),+ uncoveredRareTerms: Object.freeze([]),+ });+}++describe("buildDeciderStep", () => {+ test("builds the needs-llm-step envelope over measurable gaps", () => {+ const poolIds = [3, 7, 11];+ const pause = buildDeciderStep({+ query: "warehouse rotation chandelier",+ round: 3,+ coverage: gappedCoverage(),+ poolIds,+ });+ expect(pause.round).toBe(3);+ expect(pause.llmStep.status).toBe(NEEDS_LLM_STEP);+ expect(pause.llmStep.step).toBe(DECIDER_STEP_NAME);+ expect(pause.llmStep.target_path).toBe(DECIDER_STEP_RESUME_TARGET);+ // The envelope names the gaps and the candidate ids, so the answering+ // agent can select evidence and aim sub-queries without another call.+ expect(pause.llmStep.prompt).toContain("chandelier");+ expect(pause.llmStep.prompt).toContain("3,7,11");+ expect(pause.llmStep.schema_hints.length).toBeGreaterThan(0);+ // The token is opaque and round-stamped.+ expect(pause.token).toBe(makeRoundToken("warehouse rotation chandelier", 3, poolIds));+ expect(pause.token.startsWith("drt-3-")).toBe(true);+ });++ test("refuses a complete pool, an unmeasurable pool and an empty pool by name", () => {+ for (const coverage of [+ completeCoverage(),+ { ...gappedCoverage(), idfWeightedCoverage: null },+ ]) {+ expect(() => buildDeciderStep({ query: "q", round: 2, coverage, poolIds: [1] })).toThrow(+ DeciderStepError,+ );+ try {+ buildDeciderStep({ query: "q", round: 2, coverage, poolIds: [1] });+ } catch (error) {+ expect((error as DeciderStepError).code).toBe("no_gaps");+ }+ }+ expect(() =>+ buildDeciderStep({ query: "q", round: 2, coverage: gappedCoverage(), poolIds: [] }),+ ).toThrow(DeciderStepError);+ });++ test("mints through the registry hook and falls back to the deterministic token", () => {+ const poolIds = [3, 7, 11];+ const mints: Array<{ round: number; pauseDigest: string }> = [];+ const nonceToken = nonceRoundToken(3, "5f1e2d3c4b5a69788796a5b4");+ const pause = buildDeciderStep({+ query: "warehouse rotation chandelier",+ round: 3,+ coverage: gappedCoverage(),+ poolIds,+ mintRoundToken: ({ round, pauseDigest }) => {+ mints.push({ round, pauseDigest });+ return nonceToken;+ },+ });+ // The pause hands out the registry-backed nonce token, and the hook+ // saw the exact pause digest a commit recomputes over this state.+ expect(pause.token).toBe(nonceToken);+ expect(mints).toEqual([+ { round: 3, pauseDigest: pauseStateDigest("warehouse rotation chandelier", 3, poolIds) },+ ]);+ // A mint that could not land (null) falls back to the deterministic+ // digest token, keeping the loop alive without a registry row.+ const fallback = buildDeciderStep({+ query: "warehouse rotation chandelier",+ round: 3,+ coverage: gappedCoverage(),+ poolIds,+ mintRoundToken: () => null,+ });+ expect(fallback.token).toBe(makeRoundToken("warehouse rotation chandelier", 3, poolIds));+ // No hook at all (a commit leg's replay) stays deterministic too.+ const replay = buildDeciderStep({+ query: "warehouse rotation chandelier",+ round: 3,+ coverage: gappedCoverage(),+ poolIds,+ });+ expect(replay.token).toBe(makeRoundToken("warehouse rotation chandelier", 3, poolIds));+ });+});++describe("commitDeciderStep", () => {+ const poolIds = [3, 7, 11];+ const scope = (usedTokens: ReadonlySet<string> = new Set()) => ({+ query: "warehouse rotation chandelier",+ round: 3,+ poolIds,+ usedTokens,+ });+ const token = makeRoundToken("warehouse rotation chandelier", 3, poolIds);+ const payload = { evidence: [3, 7], subQueries: ["chandelier handoff"] };++ test("accepts a well-formed payload and returns the validated commit", () => {+ const commit = commitDeciderStep(token, payload, scope());+ expect(commit.evidenceIds).toEqual([3, 7]);+ expect(commit.subQueries).toEqual(["chandelier handoff"]);+ expect(commit.token).toBe(token);+ });++ test("refuses malformed shapes with the shape error", () => {+ for (const bad of [+ null,+ "nope",+ { evidence: [3] },+ { subQueries: ["q"] },+ { evidence: ["3"], subQueries: ["q"] },+ { evidence: [3], subQueries: ["q"], extra: true },+ { evidence: [3], subQueries: [" "] },+ ]) {+ expect(() => commitDeciderStep(token, bad, scope())).toThrow(ResponseShapeError);+ }+ });++ test("refuses over-limit and oversized sub-queries with named semantic violations", () => {+ const tooMany = {+ evidence: [3],+ subQueries: Array.from({ length: DECIDER_SUB_QUERIES_MAX + 1 }, (_, i) => `q${i}`),+ };+ try {+ commitDeciderStep(token, tooMany, scope());+ throw new Error("expected a refusal");+ } catch (error) {+ expect(error).toBeInstanceOf(ResponseCheckError);+ const violations = (error as ResponseCheckError).violations;+ expect(violations.some((v) => v.code === SEMANTIC_VIOLATION_CODES.threshold)).toBe(true);+ }+ const oversized = { evidence: [3], subQueries: ["q".repeat(DECIDER_SUB_QUERY_LENGTH_MAX + 1)] };+ expect(() => commitDeciderStep(token, oversized, scope())).toThrow(ResponseCheckError);+ // An empty evidence list or an empty sub-query list breaks the+ // payload's cardinality, not just its shape.+ for (const empty of [+ { evidence: [], subQueries: ["q"] },+ { evidence: [3], subQueries: [] },+ ]) {+ expect(() => commitDeciderStep(token, empty, scope())).toThrow(ResponseCheckError);+ }+ // A sub-query whose words are all punctuation carries no+ // significant terms and can never drive a retrieval pull: the+ // validators refuse it before the round spends anything on it.+ const punctuationOnly = { evidence: [3], subQueries: ["---"] };+ try {+ commitDeciderStep(token, punctuationOnly, scope());+ throw new Error("expected a refusal");+ } catch (error) {+ expect(error).toBeInstanceOf(ResponseCheckError);+ const violations = (error as ResponseCheckError).violations;+ expect(violations.some((v) => v.code === SEMANTIC_VIOLATION_CODES.threshold)).toBe(true);+ }+ // Duplicate sub-queries are a cross-item refusal.+ const duplicate = { evidence: [3], subQueries: ["chandelier", "chandelier"] };+ try {+ commitDeciderStep(token, duplicate, scope());+ throw new Error("expected a refusal");+ } catch (error) {+ expect(error).toBeInstanceOf(ResponseCheckError);+ const violations = (error as ResponseCheckError).violations;+ expect(violations.some((v) => v.code === SEMANTIC_VIOLATION_CODES.crossItem)).toBe(true);+ }+ });++ test("refuses unknown evidence ids by name", () => {+ try {+ commitDeciderStep(token, { evidence: [3, 999999], subQueries: ["q"] }, scope());+ throw new Error("expected a refusal");+ } catch (error) {+ expect(error).toBeInstanceOf(DeciderStepError);+ expect((error as DeciderStepError).code).toBe("unknown_evidence");+ expect((error as DeciderStepError).message).toContain("999999");+ }+ });++ test("refuses duplicate evidence ids and selections longer than the pool", () => {+ // A selection naming one chunk twice pins nothing extra: a cross-item+ // refusal, mirroring the duplicate sub-query rule.+ const duplicate = { evidence: [3, 7, 3], subQueries: ["q"] };+ try {+ commitDeciderStep(token, duplicate, scope());+ throw new Error("expected a refusal");+ } catch (error) {+ expect(error).toBeInstanceOf(ResponseCheckError);+ const violations = (error as ResponseCheckError).violations;+ expect(violations.some((v) => v.code === SEMANTIC_VIOLATION_CODES.crossItem)).toBe(true);+ expect(+ violations.some((v) => v.path === "$.evidence[2]" && v.message.includes("index 0")),+ ).toBe(true);+ }+ // The evidence budget is the pool itself: the scope's pool holds+ // three candidates, so a four-id selection is refused by name before+ // membership is even checked (the ids are distinct so the registered+ // duplicate rule lets the payload through to the context rule).+ const overPool = { evidence: [1, 2, 5, 8], subQueries: ["q"] };+ try {+ commitDeciderStep(token, overPool, scope());+ throw new Error("expected a refusal");+ } catch (error) {+ expect(error).toBeInstanceOf(DeciderStepError);+ expect((error as DeciderStepError).code).toBe("evidence_over_pool");+ expect((error as DeciderStepError).message).toContain("4 id(s)");+ }+ });++ test("refuses a token minted for another state and an already-used token", () => {+ const other = makeRoundToken("warehouse rotation chandelier", 4, poolIds);+ try {+ commitDeciderStep(other, payload, scope());+ throw new Error("expected a refusal");+ } catch (error) {+ expect((error as DeciderStepError).code).toBe("token_mismatch");+ }+ try {+ commitDeciderStep(token, payload, scope(new Set([token])));+ throw new Error("expected a refusal");+ } catch (error) {+ expect((error as DeciderStepError).code).toBe("token_used");+ }+ });++ test("accepts a registry-minted nonce token whose stored digest matches this state", () => {+ // The plan phase minted a nonce token for this exact state: the+ // commit validates the replayed state against the stored digest+ // instead of re-deriving a token.+ const nonceToken = nonceRoundToken(3, "aa1e2d3c4b5a69788796a5b4");+ const stateDigest = pauseStateDigest("warehouse rotation chandelier", 3, poolIds);+ const commit = commitDeciderStep(nonceToken, payload, {+ ...scope(),+ mintedPauseDigest: stateDigest,+ });+ expect(commit.token).toBe(nonceToken);+ expect(commit.evidenceIds).toEqual([3, 7]);+ });++ test("refuses a nonce token whose stored digest names another round or pool", () => {+ const nonceToken = nonceRoundToken(3, "bb1e2d3c4b5a69788796a5b4");+ // The row was minted for a replay that landed elsewhere: genuine+ // divergence, refused by name.+ try {+ commitDeciderStep(nonceToken, payload, {+ ...scope(),+ mintedPauseDigest: pauseStateDigest("warehouse rotation chandelier", 4, poolIds),+ });+ throw new Error("expected a refusal");+ } catch (error) {+ expect((error as DeciderStepError).code).toBe("token_mismatch");+ }+ // And a nonce token with no registry row behind it at all (expired,+ // swept, or never minted) cannot self-validate.+ try {+ commitDeciderStep(nonceToken, payload, scope());+ throw new Error("expected a refusal");+ } catch (error) {+ expect((error as DeciderStepError).code).toBe("token_mismatch");+ }+ });+});++describe("runDeciderRound (accepted payload drives round N+1)", () => {+ /**+ * Six common-term docs pin the IDF floor; 60 uniquely-termed relic docs+ * are recoverable; 20 ghost terms live only in the query, so their IDF+ * mass keeps the coverage below the completeness threshold no matter+ * how many relics the loop recovers - the pool still has measurable+ * gaps after the deterministic budget is spent, which is what mints a+ * pause.+ */+ let vault: string;+ let dbPath: string;+ let cleanup: () => void;++ beforeEach(() => {+ ({ vault, dbPath, cleanup } = createTempVault("decider-step"));+ });+ afterEach(() => cleanup());++ async function seed(): Promise<void> {+ for (let i = 1; i <= 6; i++) {+ writeMd(+ vault,+ `Brain/notes/wh${i}.md`,+ `# WH${i}\n\nWarehouse rotation schedule, bay ${i}.\n`,+ );+ }+ for (let i = 1; i <= 60; i++) {+ const term = `relic${String(i).padStart(2, "0")}`;+ writeMd(vault, `Brain/notes/${term}.md`, `# ${term}\n\n${term} provenance record.\n`);+ }+ await indexVault(makeConfig({ vault, dbPath, maxHops: 0, mmrLambda: 1 }));+ }++ const GHOSTS = Array.from({ length: 20 }, (_, i) => `wyrm${String(i + 1).padStart(2, "0")}`);+ const wideQuery = () =>+ `warehouse rotation ${Array.from({ length: 60 }, (_, i) => `relic${String(i + 1).padStart(2, "0")}`).join(" ")} ${GHOSTS.join(" ")}`;++ test("the loop pauses with a token when gaps survive the deterministic budget", async () => {+ await seed();+ const config = makeConfig({ vault, dbPath, maxHops: 0, mmrLambda: 1, twoPassEnabled: false });+ const store = await Store.open(config, { mode: "read", loadVec: false });+ try {+ const base = runFtsQueryDetailed(store, "warehouse rotation", { limit: 10 });+ const loop = runIterativeRecall({+ store,+ query: wideQuery(),+ limit: 10,+ pathPrefix: undefined,+ timeRange: null,+ validityWindowFor: () => null,+ keywordHits: base.hits,+ chunkIds: new Set(base.hits.map((h) => h.chunkId)),+ ids: base.hits.map((h) => h.chunkId),+ maxRounds: 1,+ firstRoundNumber: 2,+ isExpired: () => false,+ nowMs: () => 0,+ });+ // Gaps survive the one deterministic round, so the outcome pauses+ // with an envelope and a token instead of pretending completeness.+ expect(loop.stopReason).toBe("round_cap");+ expect(loop.pause).not.toBeNull();+ expect(loop.pause!.round).toBe(3);+ expect(loop.pause!.llmStep.status).toBe(NEEDS_LLM_STEP);+ expect(loop.pause!.token.startsWith("drt-3-")).toBe(true);+ expect(loop.pause!.poolIds.length).toBe(loop.ids.length);+ } finally {+ await store.close();+ }+ });++ test("an accepted payload drives round N+1; the pool grows only by its pulls", async () => {+ await seed();+ const config = makeConfig({ vault, dbPath, maxHops: 0, mmrLambda: 1, twoPassEnabled: false });+ const store = await Store.open(config, { mode: "read", loadVec: false });+ try {+ const base = runFtsQueryDetailed(store, "warehouse rotation", { limit: 10 });+ const input = {+ store,+ query: wideQuery(),+ limit: 10,+ pathPrefix: undefined,+ timeRange: null,+ validityWindowFor: () => null,+ keywordHits: base.hits,+ chunkIds: new Set(base.hits.map((h) => h.chunkId)),+ ids: base.hits.map((h) => h.chunkId),+ maxRounds: 1,+ firstRoundNumber: 2,+ isExpired: () => false,+ nowMs: () => 0,+ };+ const loop = runIterativeRecall(input);+ const pause = loop.pause;+ expect(pause).not.toBeNull();+ const usedTokens = new Set<string>();+ const before = new Set(loop.ids);+ // A decider payload aimed at one specific relic: the pool may grow+ // by exactly the ids that pull recovers, nothing else.+ const after = runDeciderRound({+ ...input,+ keywordHits: loop.keywordHits,+ chunkIds: new Set(loop.ids),+ pause: pause!,+ token: pause!.token,+ payload: {+ evidence: [pause!.poolIds[0]],+ subQueries: ["relic01 relic02 relic60"],+ },+ usedTokens,+ priorRounds: loop.rounds,+ });+ usedTokens.add(after.token);+ expect(after.round.round).toBe(3);+ expect(after.round.author).toBe("decider");+ expect(after.round.subQueries).toEqual(["relic01 relic02 relic60"]);+ expect(after.stopReason).toBe("decider_round");+ expect(after.token).toBe(pause!.token);+ expect(after.rounds).toHaveLength(loop.rounds.length + 1);+ // The pool grew ONLY by the pull: every new id came from the+ // payload's single sub-query and nothing else was fetched.+ const pulled = runFtsQueryDetailed(store, "relic01", {+ expandedTerms: ["relic02", "relic60"],+ limit: 10,+ pathPrefix: null,+ });+ const expectedNew = new Set(+ pulled.hits.map((h) => h.chunkId).filter((id) => !before.has(id)),+ );+ const gained = after.ids.filter((id) => !before.has(id));+ expect(gained.length).toBe(expectedNew.size);+ for (const id of gained) expect(expectedNew.has(id)).toBe(true);+ expect(after.ids.length).toBe(before.size + expectedNew.size);+ // A replayed commit with the same token is refused: single use.+ expect(() =>+ runDeciderRound({+ ...input,+ keywordHits: loop.keywordHits,+ chunkIds: new Set(loop.ids),+ pause: pause!,+ token: pause!.token,+ payload: { evidence: [pause!.poolIds[0]], subQueries: ["relic01"] },+ usedTokens,+ priorRounds: loop.rounds,+ }),+ ).toThrow(DeciderStepError);+ } finally {+ await store.close();+ }+ });+});diff --git a/tests/core/search/iterative-recall.test.ts b/tests/core/search/iterative-recall.test.tsnew file mode 100644index 00000000..3702aa71--- /dev/null+++ b/tests/core/search/iterative-recall.test.ts@@ -0,0 +1,988 @@+/**+ * Bounded iterative recall loop (recall-quality wave, lane A): the+ * single-fire second pass generalized into a bounded N-round driver.+ * With the opt-in knob on, gap-proposal rounds 2..N run deterministic+ * sub-query pulls over the same pool-merging discipline as round 2,+ * bounded by the round cap and the composite deadline; the extracted+ * marginal-value stop retires rounds that stop paying. Knob off (or the+ * request flag absent) the pipeline is byte-identical to the pre-change+ * one, including a mode-on-but-inert comparison.+ */++import { test, expect, beforeEach, afterEach, describe, setSystemTime } from "bun:test";++import {+ ITERATIVE_RECALL_MAX_ROUNDS_CAP,+ ITERATIVE_RECALL_MAX_ROUNDS_DEFAULT,+ runIterativeRecall,+} from "../../../src/core/search/pipeline/iterative-recall.ts";+import { Store } from "../../../src/core/search/store.ts";+import { runFtsQueryDetailed } from "../../../src/core/search/fts.ts";+import { indexVault } from "../../../src/core/search/indexer.ts";+import { resolveSearchConfig } from "../../../src/core/search/index.ts";+import { search } from "../../../src/core/search/search.ts";+import { pauseStateDigest } from "../../../src/core/search/decider-step.ts";+import { probeQueryCache } from "../../../src/core/search/pipeline/cache-slot.ts";+import { SearchError } from "../../../src/core/search/types.ts";+import { TRANSPORT_REACH } from "../../../src/core/graph/transport-reach.ts";+import { createTempVault, makeConfig, writeMd } from "../../helpers/search-fixtures.ts";+import { fakeCredential } from "../../helpers/fake-credentials.ts";+import type {+ ResolvedSearchConfig,+ StructuredRecallQueryDocument,+} from "../../../src/core/search/types.ts";++let vault: string;+let dbPath: string;+let cleanup: () => void;++/** A round token shaped like the ones the loop mints; assembled from parts. */+const KNOB_OFF_TOKEN = fakeCredential("tok", "-knob-off");++/** Six common-term docs give warehouse/rotation a low IDF; the loop's floor stays honest. */+async function seed(): Promise<void> {+ for (let i = 1; i <= 6; i++) {+ writeMd(vault, `Brain/notes/wh${i}.md`, `# WH${i}\n\nWarehouse rotation schedule, bay ${i}.\n`);+ }+ writeMd(+ vault,+ "Brain/notes/chandelier.md",+ "# Chandelier\n\nChandelier handoff log, east hall.\n",+ );+ writeMd(+ vault,+ "Brain/notes/candelabra.md",+ "# Candelabra\n\nCandelabra restoration notes, west hall.\n",+ );+ writeMd(vault, "Brain/notes/zircon.md", "# Zircon\n\nZircon inventory tag, north vault.\n");+ await indexVault(makeConfig({ vault, dbPath, maxHops: 0, mmrLambda: 1 }));+}++/** A vault of 60 uniquely-termed docs, so pulls saturate the pool width before gaps close. */+async function seedWide(): Promise<void> {+ for (let i = 1; i <= 6; i++) {+ writeMd(vault, `Brain/notes/wh${i}.md`, `# WH${i}\n\nWarehouse rotation schedule, bay ${i}.\n`);+ }+ for (let i = 1; i <= 60; i++) {+ const term = `relic${String(i).padStart(2, "0")}`;+ writeMd(vault, `Brain/notes/${term}.md`, `# ${term}\n\n${term} provenance record.\n`);+ }+ await indexVault(makeConfig({ vault, dbPath, maxHops: 0, mmrLambda: 1 }));+}++/** The lex lane is pinned to the common terms, so first-pass pools miss every rare term. */+const structuredFor = (): StructuredRecallQueryDocument =>+ Object.freeze({+ intent: null,+ lex: Object.freeze({+ include: Object.freeze(["warehouse", "rotation"]) as ReadonlyArray<string>,+ exclude: Object.freeze([]) as ReadonlyArray<string>,+ }),+ vec: Object.freeze(["warehouse rotation"]) as ReadonlyArray<string>,+ hyde: Object.freeze([]) as ReadonlyArray<string>,+ });++function withIterative(config: ResolvedSearchConfig, maxRounds?: number): ResolvedSearchConfig {+ return {+ ...config,+ recall: {+ ...config.recall,+ iterativeRecallEnabled: true,+ ...(maxRounds !== undefined ? { iterativeRecallMaxRounds: maxRounds } : {}),+ },+ };+}++const COMMON = ["chandelier", "candelabra", "zircon"];++/**+ * Pin the wall clock for the byte-identity comparisons: the recency boost+ * reads Date.now() per call, so two searches a millisecond apart differ in+ * float noise that has nothing to do with the loop. One pinned instant is+ * the honest "same request" for a full serialized comparison.+ */+function withPinnedClock(run: () => Promise<void>): Promise<void> {+ const restored = Date.now();+ setSystemTime(restored);+ return run().finally(() => setSystemTime());+}++beforeEach(() => {+ ({ vault, dbPath, cleanup } = createTempVault("iterative-recall"));+});+afterEach(() => cleanup());++describe("iterative round driver over a seeded vault", () => {+ test("the knob off and the flag on leave the outcome byte-identical to the flag off", async () => {+ await seed();+ const config = makeConfig({ vault, dbPath, maxHops: 0, mmrLambda: 1, twoPassEnabled: false });+ const query = `warehouse rotation ${COMMON.join(" ")}`;+ const structured = structuredFor();+ await withPinnedClock(async () => {+ const plain = await search(config, { query, structuredQuery: structured });+ const flagged = await search(config, { query, structuredQuery: structured, iterative: true });+ expect(JSON.stringify(plain)).toBe(JSON.stringify(flagged));+ });+ const plain = await search(config, { query, structuredQuery: structured });+ expect(plain.results.map((r) => r.path)).not.toContain("Brain/notes/chandelier.md");+ });++ test("mode on with no gaps is inert and byte-identical to mode off", async () => {+ await seed();+ const config = makeConfig({ vault, dbPath, maxHops: 0, mmrLambda: 1, twoPassEnabled: false });+ const iterative = withIterative(config);+ const query = "warehouse rotation";+ await withPinnedClock(async () => {+ const off = await search(config, { query });+ const on = await search(iterative, { query, iterative: true });+ expect(JSON.stringify(off)).toBe(JSON.stringify(on));+ });+ const on = await search(iterative, { query, iterative: true });+ expect(on.results.length).toBeGreaterThan(0);+ });++ test("bounded rounds merge pools and recover chunks the first pass missed", async () => {+ await seed();+ const config = makeConfig({ vault, dbPath, maxHops: 0, mmrLambda: 1, twoPassEnabled: false });+ const outcome = await search(withIterative(config), {+ query: `warehouse rotation ${COMMON.join(" ")}`,+ structuredQuery: structuredFor(),+ iterative: true,+ });+ const paths = outcome.results.map((r) => r.path);+ expect(paths).toContain("Brain/notes/chandelier.md");+ expect(paths).toContain("Brain/notes/candelabra.md");+ expect(paths).toContain("Brain/notes/zircon.md");+ });++ test("the decider pause pool never names a page the reach rule withholds", async () => {+ // The private twin ranks into the seeded pool (it matches the query+ // terms better than its public sibling), so at local reach the pause+ // names it. At remote reach the same call must name no withheld+ // path: pool_ids is post-reach, so the gap between it and the trail+ // can never count a withheld match - the existence oracle+ // FilteredPool.preVisibility exists to close.+ await seed();+ writeMd(+ vault,+ "Brain/notes/private-chandelier.md",+ "---\nvisibility: private\n---\n\n# Private chandelier\n\nChandelier handoff log, sealed wing.\n",+ );+ await indexVault(makeConfig({ vault, dbPath, maxHops: 0, mmrLambda: 1 }));+ const config = makeConfig({ vault, dbPath, maxHops: 0, mmrLambda: 1, twoPassEnabled: false });+ // Ghost terms the corpus never matches hold the weighted coverage+ // below the completeness threshold at both reaches, so the loop+ // always pauses instead of finishing coverage-complete.+ const query = `chandelier handoff wyrmshade velkriss`;+ const structured: StructuredRecallQueryDocument = Object.freeze({+ intent: null,+ lex: Object.freeze({+ include: Object.freeze(["chandelier", "handoff"]) as ReadonlyArray<string>,+ exclude: Object.freeze([]) as ReadonlyArray<string>,+ }),+ vec: Object.freeze(["chandelier handoff"]) as ReadonlyArray<string>,+ hyde: Object.freeze([]) as ReadonlyArray<string>,+ });++ const poolPathsAt = async (reach: (typeof TRANSPORT_REACH)["remote" | "local"]) => {+ const outcome = await search(withIterative(config), {+ query,+ structuredQuery: structured,+ iterative: true,+ transportReach: reach,+ });+ const plan = outcome.iterative;+ if (plan === undefined || plan.phase !== "needs-llm-step") {+ throw new Error(`expected a decider pause at reach ${reach}`);+ }+ const store = await Store.open(config, { mode: "read", loadVec: false });+ const paths = [...(await store.hydrateChunks([...plan.poolIds])).values()]+ .map((c) => c.path)+ .sort();+ store.close();+ return paths;+ };++ const localPaths = await poolPathsAt(TRANSPORT_REACH.local);+ expect(localPaths).toContain("Brain/notes/private-chandelier.md");++ const remotePaths = await poolPathsAt(TRANSPORT_REACH.remote);+ expect(remotePaths).not.toContain("Brain/notes/private-chandelier.md");+ // The filter removes exactly the withheld candidates; every path a+ // local pause may name is still eligible, and none appears twice.+ expect(new Set(remotePaths).size).toBe(remotePaths.length);+ expect(+ remotePaths.every((p) => localPaths.includes(p) || p === "Brain/notes/private-chandelier.md"),+ ).toBe(true);+ });++ test("a fully-formed commit with the knob off is refused by name", async () => {+ await seed();+ const config = makeConfig({ vault, dbPath, maxHops: 0, mmrLambda: 1, twoPassEnabled: false });+ const query = `warehouse rotation ${COMMON.join(" ")}`;+ const structured = structuredFor();+ let err: unknown = null;+ try {+ await search(config, {+ query,+ structuredQuery: structured,+ iterative: true,+ iterativeToken: KNOB_OFF_TOKEN,+ iterativePayload: { evidence: [1], subQueries: ["warehouse rotation"] },+ });+ } catch (e) {+ err = e;+ }+ expect(err).toBeInstanceOf(SearchError);+ expect((err as SearchError).message).toContain("disabled by operator config");+ });++ test("round accounting counts only candidates the reach rule shows the caller", async () => {+ // The private twin matches the probed sub-query but is withheld at+ // remote reach: the decider round's `added` must count zero there,+ // so probing a withheld term returns no recovery signal - while the+ // same probe at local reach honestly reports the recovery.+ await seed();+ writeMd(+ vault,+ "Brain/notes/private-chandelier.md",+ "---\nvisibility: private\n---\n\n# Private chandelier\n\nSealed wing chandelier handoff notes.\n",+ );+ await indexVault(makeConfig({ vault, dbPath, maxHops: 0, mmrLambda: 1 }));+ const config = makeConfig({ vault, dbPath, maxHops: 0, mmrLambda: 1, twoPassEnabled: false });+ const query = `chandelier handoff wyrmshade velkriss`;+ const structured = structuredFor();+ // The token derives from query+round+pool, and both arms plan over+ // the same vault: a ghost term per arm keeps the two queries - and+ // so the two tokens - distinct.+ const run = async (+ transportReach: (typeof TRANSPORT_REACH)["remote" | "local"],+ ghost: string,+ ) => {+ const armQuery = `${query} ${ghost}`;+ const planBody = await search(withIterative(config), {+ query: armQuery,+ structuredQuery: structured,+ iterative: true,+ transportReach,+ });+ const plan = planBody.iterative;+ if (plan === undefined || plan.phase !== "needs-llm-step") {+ throw new Error(`expected a decider pause at reach ${transportReach}`);+ }+ return search(withIterative(config), {+ query: armQuery,+ structuredQuery: structured,+ iterative: true,+ transportReach,+ iterativeToken: plan.token,+ iterativePayload: { evidence: [plan.poolIds[0]!], subQueries: ["sealed wing"] },+ });+ };++ const remote = await run(TRANSPORT_REACH.remote, "wyrmshade");+ const remoteFinal = remote.iterative;+ if (remoteFinal === undefined || remoteFinal.phase !== "final") {+ throw new Error("expected a final marker at remote reach");+ }+ const deciderRoundRemote = remoteFinal.rounds.at(-1);+ expect(deciderRoundRemote?.author).toBe("decider");+ expect(deciderRoundRemote?.added).toBe(0);++ const local = await run(TRANSPORT_REACH.local, "velkriss");+ const localFinal = local.iterative;+ if (localFinal === undefined || localFinal.phase !== "final") {+ throw new Error("expected a final marker at local reach");+ }+ const deciderRoundLocal = localFinal.rounds.at(-1);+ expect(deciderRoundLocal?.author).toBe("decider");+ expect(deciderRoundLocal?.added).toBeGreaterThan(0);+ });++ test("a second plan call mints a fresh token after one commit spent the first", async () => {+ // The round token must name THIS plan call, not the query's pool: a+ // deterministic token hands every later plan for the same query the+ // already-spent marker, locking the caller (and any other agent asking+ // the same question) out of its decider round until the TTL expires.+ // With the cache on the stale plan row would keep serving the dead+ // token, so the second plan runs against a warm cache row on purpose.+ await seed();+ const config = makeConfig({+ vault,+ dbPath,+ maxHops: 0,+ mmrLambda: 1,+ twoPassEnabled: false,+ cacheEnabled: true,+ });+ const iterative = withIterative(config);+ const query = `warehouse rotation ${COMMON.join(" ")} wyrmshade velkriss`;+ const structured = structuredFor();+ const planArgs = { query, structuredQuery: structured, iterative: true, limit: 5 };+ const commitArgs = (token: string, evidence: number) => ({+ ...planArgs,+ iterativeToken: token,+ iterativePayload: { evidence: [evidence], subQueries: ["chandelier handoff"] },+ });+ const pauseOf = (outcome: Awaited<ReturnType<typeof search>>) => {+ const marker = outcome.iterative;+ if (marker === undefined || marker.phase !== "needs-llm-step") {+ throw new Error("expected a decider pause");+ }+ return marker;+ };++ const pause1 = pauseOf(await search(iterative, planArgs));+ const spent1 = await search(iterative, commitArgs(pause1.token, pause1.poolIds[0]!));+ expect(spent1.iterative?.phase).toBe("final");++ // The second plan for the SAME query over the SAME pool must carry a+ // token the first commit never touched.+ const pause2 = pauseOf(await search(iterative, planArgs));+ expect(pause2.token).not.toBe(pause1.token);+ expect(pause2.token).toMatch(/^drt-\d+-[0-9a-f]+$/);+ const spent2 = await search(iterative, commitArgs(pause2.token, pause2.poolIds[0]!));+ expect(spent2.iterative?.phase).toBe("final");+ });++ test("a commit replays the plan's recorded rounds even when its own clock runs slow", async () => {+ // The commit leg re-runs the deterministic rounds and expects to+ // arrive at the pause the plan recorded. The marginal-value stop is+ // fed elapsed time, so a replay on a loaded host retires a round the+ // plan itself ran and lands on a different state - the commit then+ // fails against a plan the caller answered honestly. With the plan's+ // recorded round count in the token's registry row, the replay runs+ // exactly that many rounds and skips its own clock's verdicts.+ for (let i = 1; i <= 6; i++) {+ writeMd(+ vault,+ `Brain/notes/wh${i}.md`,+ `# WH${i}\n\nWarehouse rotation schedule, bay ${i}.\n`,+ );+ }+ for (let i = 1; i <= 80; i++) {+ const term = `relic${String(i).padStart(2, "0")}`;+ writeMd(vault, `Brain/notes/${term}.md`, `# ${term}\n\n${term} provenance record.\n`);+ }+ await indexVault(makeConfig({ vault, dbPath, maxHops: 0, mmrLambda: 1 }));+ const config = makeConfig({ vault, dbPath, maxHops: 0, mmrLambda: 1, twoPassEnabled: false });+ const iterative = withIterative(config, 3);+ const ghosts = Array.from({ length: 30 }, (_, i) => `wyrm${String(i + 1).padStart(2, "0")}`);+ const query = `warehouse rotation ${Array.from({ length: 80 }, (_, i) => `relic${String(i + 1).padStart(2, "0")}`).join(" ")} ${ghosts.join(" ")}`;+ const structured = structuredFor();+ const plan = await search(iterative, { query, structuredQuery: structured, iterative: true });+ const pause = plan.iterative;+ if (pause === undefined || pause.phase !== "needs-llm-step") {+ throw new Error("expected a decider pause");+ }+ expect(pause.rounds.length).toBeGreaterThanOrEqual(2);++ // The replay's clock: every read a second and a half after the one+ // before, so the stop's elapsed term inflates until a slower replay+ // would retire the last partial round the plan ran.+ const realNow = Date.now;+ let ticks = 0;+ Date.now = () => realNow.call(Date) + 1500 * ++ticks;+ let commit: Awaited<ReturnType<typeof search>>;+ try {+ commit = await search(iterative, {+ query,+ structuredQuery: structured,+ iterative: true,+ iterativeToken: pause.token,+ iterativePayload: { evidence: [pause.poolIds[0]], subQueries: ["relic01 relic02"] },+ });+ } finally {+ Date.now = realNow;+ }+ expect(Date.now).toBe(realNow);+ const final = commit.iterative;+ if (final === undefined || final.phase !== "final") {+ throw new Error(`expected a final marker, got ${pause.phase}`);+ }+ const deciderRound = final.rounds.at(-1);+ expect(deciderRound?.author).toBe("decider");+ expect(deciderRound?.round).toBe(pause.round);+ });++ test("a committed evidence id that would fall outside the limit reaches the results", async () => {+ // The decider's evidence selection was validated and then discarded:+ // the ranking never saw it, and a core-evidence chunk could fall out+ // of the top `limit`. The committed evidence ids must matter twice -+ // carried on the final marker, and given a deterministic preference+ // strong enough that one which would rank outside the limit window+ // still lands in the final results. The structured query excludes a+ // term (an ordinary caller shape), which widens the ranked pool past+ // the limit the way every filtered real call is - without it the+ // rank cap IS the limit and nothing outside the window ever reaches+ // the window cut to be pinned into it.+ await seed();+ const config = makeConfig({ vault, dbPath, maxHops: 0, mmrLambda: 1, twoPassEnabled: false });+ const iterative = withIterative(config);+ const query = `warehouse rotation ${COMMON.join(" ")} wyrmshade velkriss`;+ const structured: StructuredRecallQueryDocument = Object.freeze({+ intent: null,+ lex: Object.freeze({+ include: Object.freeze(["warehouse", "rotation"]) as ReadonlyArray<string>,+ exclude: Object.freeze(["sealedwing"]) as ReadonlyArray<string>,+ }),+ vec: Object.freeze(["warehouse rotation"]) as ReadonlyArray<string>,+ hyde: Object.freeze([]) as ReadonlyArray<string>,+ });+ // limit 1: the plan's own window is the single top-ranked row, so+ // every OTHER pool id is evidence that would fall outside the limit.+ const plan = await search(iterative, {+ query,+ structuredQuery: structured,+ iterative: true,+ limit: 1,+ });+ const pause = plan.iterative;+ if (pause === undefined || pause.phase !== "needs-llm-step") {+ throw new Error("expected a decider pause");+ }+ const store = await Store.open(config, { mode: "read", loadVec: false });+ let evidenceId: number;+ let evidencePath: string;+ try {+ const hydrated = await store.hydrateChunks([...pause.poolIds]);+ const topPath = plan.results[0]?.path;+ const outside = [...hydrated.entries()].find(([, chunk]) => chunk.path !== topPath);+ if (outside === undefined) throw new Error("expected a pool id outside the plan window");+ evidenceId = outside[0];+ evidencePath = outside[1].path;+ } finally {+ await store.close();+ }+ const commit = await search(iterative, {+ query,+ structuredQuery: structured,+ iterative: true,+ limit: 1,+ iterativeToken: pause.token,+ iterativePayload: { evidence: [evidenceId], subQueries: ["chandelier handoff"] },+ });+ const final = commit.iterative;+ if (final === undefined || final.phase !== "final") {+ throw new Error("expected a final marker");+ }+ // The marker carries the pinned set ...+ expect(final.evidenceIds).toEqual([evidenceId]);+ // ... and the pinned id is IN the limit window, not ranked out of it.+ expect(commit.results.map((r) => r.path)).toEqual([evidencePath]);+ });++ test("an expired deadline degrades the looped search exactly like the plain one", async () => {+ await seed();+ const config = {+ ...makeConfig({ vault, dbPath, maxHops: 0, mmrLambda: 1, twoPassEnabled: false }),+ hybridDeadlineMs: 1,+ } as ResolvedSearchConfig;+ const query = `warehouse rotation ${COMMON.join(" ")}`;+ const structured = structuredFor();+ // Both runs see a clock 10 seconds past the 1 ms budget at every+ // deadline check, by construction: Date.now is shifted for the calls+ // and restored after. A real 1 ms budget raced wall time instead,+ // and under load the two runs degraded at different phase boundaries+ // (the plain run skipped the semantic lanes, the looped one did not).+ const realNow = Date.now;+ Date.now = () => realNow.call(Date) + 10_000;+ let off: Awaited<ReturnType<typeof search>>;+ let on: Awaited<ReturnType<typeof search>>;+ try {+ off = await search(config, { query, structuredQuery: structured });+ on = await search(withIterative(config), {+ query,+ structuredQuery: structured,+ iterative: true,+ });+ } finally {+ Date.now = realNow;+ }+ // Same keyword-only answer, same named degradation, and no loop round.+ expect(on.results.map((r) => r.path)).toEqual(off.results.map((r) => r.path));+ expect(on.warnings.some((w) => w.startsWith("hybrid deadline 1ms exceeded"))).toBe(true);+ // The trail is judged by its degradation vocabulary and the configured+ // budget, never by bytes: the hybrid-deadline degradation carries+ // `detail.elapsedMs`, measured wall time, so a byte-compare of two+ // trails pins scheduler jitter and flakes. Codes and budgetMs are the+ // deterministic content; `pool`/`retrieved` are pinned by the results+ // equality above.+ const degradedOf = (t: typeof on.retrievalTrail): Array<string> =>+ (t?.degraded ?? []).map((d) => {+ const budget = (d.detail as { budgetMs?: number } | undefined)?.budgetMs;+ return budget === undefined ? d.code : `${d.code}:${budget}`;+ });+ // Both runs name the expired budget. Which side also carries the+ // structural semantic-skip note depends on which deadline check+ // fires first inside the run - a diagnostics-order coin flip under+ // an always-expired clock - so the lists are compared as+ // vocabularies: the coin-flip note is dropped from both, the+ // deadline entry is required on both, and the remaining+ // vocabularies must agree as sets, never byte-for-byte nor in a+ // fixed subset direction.+ const STRUCTURED_SKIP_NOTE = "semantic-structured-lanes-skipped";+ const onDegraded = degradedOf(on.retrievalTrail).filter((d) => d !== STRUCTURED_SKIP_NOTE);+ const offDegraded = degradedOf(off.retrievalTrail).filter((d) => d !== STRUCTURED_SKIP_NOTE);+ expect(onDegraded).toContain("hybrid-deadline-exceeded:1");+ expect(offDegraded).toContain("hybrid-deadline-exceeded:1");+ expect(new Set(onDegraded)).toEqual(new Set(offDegraded));+ expect(onDegraded.length).toBeGreaterThan(0);+ // A deadline exit never mints a pause: the looped answer carries no+ // decider envelope, so the flag added nothing observable.+ expect(on.iterative).toBeUndefined();+ expect(pathsMissing(on, COMMON)).toBe(true);+ });++ test("a commit whose clock died before the loop block is refused by name", async () => {+ await seed();+ const config = {+ ...makeConfig({ vault, dbPath, maxHops: 0, mmrLambda: 1, twoPassEnabled: false }),+ hybridDeadlineMs: 5_000,+ } as ResolvedSearchConfig;+ const iterative = withIterative(config);+ // Ghost terms hold the coverage below the completeness threshold, so+ // the plan leg pauses with a token instead of finishing.+ const query = `chandelier handoff wyrmshade velkriss`;+ const structured: StructuredRecallQueryDocument = Object.freeze({+ intent: null,+ lex: Object.freeze({+ include: Object.freeze(["chandelier", "handoff"]) as ReadonlyArray<string>,+ exclude: Object.freeze([]) as ReadonlyArray<string>,+ }),+ vec: Object.freeze(["chandelier handoff"]) as ReadonlyArray<string>,+ hyde: Object.freeze([]) as ReadonlyArray<string>,+ });+ const plan = await search(iterative, { query, structuredQuery: structured, iterative: true });+ const pause = plan.iterative;+ if (pause === undefined || pause.phase !== "needs-llm-step") {+ throw new Error("expected a decider pause");+ }++ // The request clock cannot be pinned (a frozen Date.now() never+ // expires the deadline it just minted), so the clock is stepped+ // instead: the request-resolution read keeps the live instant - the+ // deadline is created with the full 5 s budget still ahead - and+ // every later read in the same call reports the budget long spent.+ // The commit then reaches the block with a dead clock, exactly the+ // state a slow caller's commit lands in.+ const realNow = Date.now;+ const base = realNow();+ let reads = 0;+ Date.now = () => (reads++ === 0 ? base : base + 60_000);+ let err: unknown = null;+ try {+ await search(iterative, {+ query,+ structuredQuery: structured,+ iterative: true,+ iterativeToken: pause.token,+ iterativePayload: { evidence: [0], subQueries: [query] },+ });+ } catch (e) {+ err = e;+ } finally {+ Date.now = realNow;+ }+ expect(Date.now).toBe(realNow);+ // Silence here would return a plain answer the caller would read as+ // its commit's outcome; the refusal is the named one.+ expect(err).toBeInstanceOf(SearchError);+ expect((err as SearchError).message).toContain("no decider round is pending");+ });+});++function pathsMissing(+ outcome: { results: ReadonlyArray<{ path: string }> },+ rare: ReadonlyArray<string>,+): boolean {+ return rare.every((term) => !outcome.results.some((r) => r.path.includes(term)));+}++describe("runIterativeRecall (driver, over an open store)", () => {+ /**+ * 60 seeded relic docs plus 20 query-only ghost terms (in the query,+ * nowhere in the corpus): the relics are recoverable, the ghosts are+ * not, and their IDF mass holds the weighted coverage below the+ * completeness threshold no matter how many relics the loop recovers -+ * which is what lets these tests observe the cap and the marginal stop+ * rather than an early coverage-complete exit.+ */+ const GHOSTS = Array.from({ length: 20 }, (_, i) => `wyrm${String(i + 1).padStart(2, "0")}`);+ const wideQuery = () =>+ `warehouse rotation ${Array.from({ length: 60 }, (_, i) => `relic${String(i + 1).padStart(2, "0")}`).join(" ")} ${GHOSTS.join(" ")}`;++ /**+ * 80 recoverable relic docs plus 30 query-only ghost terms: round 2+ * saturates the pull width (50), round 3 recovers a partial yield (30)+ * that sits between the fast floor (0.25 of the top yield) and the+ * slow floor (up to 0.75), and round 4 recovers nothing - the exact+ * yield curve a slower replay's marginal-value stop retires early.+ */+ async function seedDivergence(): Promise<void> {+ for (let i = 1; i <= 6; i++) {+ writeMd(+ vault,+ `Brain/notes/wh${i}.md`,+ `# WH${i}\n\nWarehouse rotation schedule, bay ${i}.\n`,+ );+ }+ for (let i = 1; i <= 80; i++) {+ const term = `relic${String(i).padStart(2, "0")}`;+ writeMd(vault, `Brain/notes/${term}.md`, `# ${term}\n\n${term} provenance record.\n`);+ }+ await indexVault(makeConfig({ vault, dbPath, maxHops: 0, mmrLambda: 1 }));+ }++ const divergenceQuery = () =>+ `warehouse rotation ${Array.from({ length: 80 }, (_, i) => `relic${String(i + 1).padStart(2, "0")}`).join(" ")} ${Array.from({ length: 30 }, (_, i) => `wyrm${String(i + 1).padStart(2, "0")}`).join(" ")}`;++ test("respects the round cap and merges each round's pulls into one pool", async () => {+ await seedWide();+ const config = makeConfig({ vault, dbPath, maxHops: 0, mmrLambda: 1, twoPassEnabled: false });+ const store = await Store.open(config, { mode: "read", loadVec: false });+ try {+ const query = wideQuery();+ const base = runFtsQueryDetailed(store, "warehouse rotation", { limit: 10 });+ const chunkIds = new Set(base.hits.map((h) => h.chunkId));+ const loop = (maxRounds: number) =>+ runIterativeRecall({+ store,+ query,+ limit: 10,+ pathPrefix: undefined,+ timeRange: null,+ validityWindowFor: () => null,+ keywordHits: base.hits,+ chunkIds: new Set(chunkIds),+ ids: [...chunkIds],+ maxRounds,+ firstRoundNumber: 2,+ isExpired: () => false,+ nowMs: () => 0,+ });+ const one = loop(1);+ expect(one.rounds).toHaveLength(1);+ expect(one.stopReason).toBe("round_cap");+ const two = loop(2);+ expect(two.rounds).toHaveLength(2);+ // The ghosts keep the coverage below the completeness threshold, so+ // the second run stops because the cap said so, not because the+ // gaps closed.+ expect(two.stopReason).toBe("round_cap");+ // Each round only ever ADDS candidates.+ expect(two.ids.length).toBeGreaterThan(one.ids.length);+ expect(two.keywordHits.length).toBeGreaterThanOrEqual(one.keywordHits.length);+ for (const round of two.rounds) {+ expect(round.round).toBe(2 + two.rounds.indexOf(round));+ expect(round.author).toBe("deterministic");+ expect(round.added).toBeGreaterThan(0);+ }+ } finally {+ await store.close();+ }+ });++ test("the marginal-value stop retires rounds that stop paying", async () => {+ await seedWide();+ const config = makeConfig({ vault, dbPath, maxHops: 0, mmrLambda: 1, twoPassEnabled: false });+ const store = await Store.open(config, { mode: "read", loadVec: false });+ try {+ const query = wideQuery();+ const base = runFtsQueryDetailed(store, "warehouse rotation", { limit: 10 });+ // Round 2 saturates the pull width; round 3 recovers the relic tail,+ // a yield far below the 0.25 floor fraction of round 2's, so the+ // extracted stop retires round 4 even though ghosts keep the+ // coverage incomplete and the cap allows more rounds.+ const loop = runIterativeRecall({+ store,+ query,+ limit: 10,+ pathPrefix: undefined,+ timeRange: null,+ validityWindowFor: () => null,+ keywordHits: base.hits,+ chunkIds: new Set(base.hits.map((h) => h.chunkId)),+ ids: base.hits.map((h) => h.chunkId),+ maxRounds: 4,+ firstRoundNumber: 2,+ isExpired: () => false,+ nowMs: () => 0,+ });+ expect(loop.stopReason).toBe("marginal_value");+ expect(loop.rounds).toHaveLength(2);+ expect(loop.lastCoverage).not.toBeNull();+ expect(loop.lastCoverage!.uncoveredRareTerms.length).toBeGreaterThan(0);+ } finally {+ await store.close();+ }+ });++ test("a recorded replay runs the plan's rounds regardless of its own clock", async () => {+ await seedDivergence();+ const config = makeConfig({ vault, dbPath, maxHops: 0, mmrLambda: 1, twoPassEnabled: false });+ const store = await Store.open(config, { mode: "read", loadVec: false });+ try {+ const query = divergenceQuery();+ const base = runFtsQueryDetailed(store, "warehouse rotation", { limit: 10 });+ const input = () => ({+ store,+ query,+ limit: 10,+ pathPrefix: undefined,+ timeRange: null,+ validityWindowFor: () => null,+ keywordHits: base.hits,+ chunkIds: new Set(base.hits.map((h) => h.chunkId)),+ ids: base.hits.map((h) => h.chunkId),+ maxRounds: 3,+ firstRoundNumber: 2,+ isExpired: () => false,+ });+ // The plan leg on a fast host: saturate, partial, zero-yield - the+ // third round ran even though its yield was zero, and the pause+ // was minted over THAT state.+ const plan = runIterativeRecall({ ...input(), nowMs: () => 0 });+ expect(plan.rounds.map((r) => r.added)).toEqual([50, 30, 0]);+ expect(plan.stopReason).toBe("no_progress");+ expect(plan.pause).not.toBeNull();+ // The commit leg's replay on a slow host: its own marginal-value+ // verdict, fed the inflated elapsed term, would retire the third+ // round and arrive a round early. With the plan's recorded count+ // in the replay brief, it runs exactly that many rounds, skips its+ // own stop predicates, and lands on the pause state the registry+ // row digests.+ let ticks = 0;+ const replay = runIterativeRecall({+ ...input(),+ replayRounds: plan.rounds.length,+ nowMs: () => 1500 * ++ticks,+ });+ expect(replay.rounds.map((r) => r.added)).toEqual([50, 30, 0]);+ expect(replay.stopReason).toBe(plan.stopReason);+ expect(replay.pause?.round).toBe(plan.pause?.round);+ expect(pauseStateDigest(query, replay.pause!.round, replay.pause!.poolIds)).toBe(+ pauseStateDigest(query, plan.pause!.round, plan.pause!.poolIds),+ );+ // And the pool itself is the plan's, byte for byte.+ expect(replay.ids).toEqual(plan.ids);+ } finally {+ await store.close();+ }+ });++ test("a zero-yield round stops the loop as no progress", async () => {+ await seed();+ const config = makeConfig({ vault, dbPath, maxHops: 0, mmrLambda: 1, twoPassEnabled: false });+ const store = await Store.open(config, { mode: "read", loadVec: false });+ try {+ const base = runFtsQueryDetailed(store, "warehouse rotation", { limit: 10 });+ const loop = runIterativeRecall({+ store,+ query: "warehouse rotation ghostterm",+ limit: 10,+ pathPrefix: undefined,+ timeRange: null,+ validityWindowFor: () => null,+ keywordHits: base.hits,+ chunkIds: new Set(base.hits.map((h) => h.chunkId)),+ ids: base.hits.map((h) => h.chunkId),+ maxRounds: 3,+ firstRoundNumber: 2,+ isExpired: () => false,+ nowMs: () => 0,+ });+ expect(loop.rounds).toHaveLength(1);+ expect(loop.stopReason).toBe("no_progress");+ } finally {+ await store.close();+ }+ });++ test("a withheld first-pass candidate cannot close a rare term's gap at remote reach", async () => {+ // The private twin is the corpus's ONLY match for the rare term, and+ // the first pass ranked it in: the raw pool the loop receives carries+ // a withheld candidate, so coverage measured over the raw set would+ // close the term's gap the visible pool never closes - the loop could+ // end coverage-complete over a term the caller cannot see a single+ // candidate for. With a reach rule present, the pool is post-reach+ // from the first measurement on.+ await seed();+ writeMd(+ vault,+ "Brain/notes/private-wyrmshade.md",+ "---\nvisibility: private\n---\n\n# Wyrmshade\n\nWyrmshade inventory tag, sealed wing.\n",+ );+ await indexVault(makeConfig({ vault, dbPath, maxHops: 0, mmrLambda: 1 }));+ const config = makeConfig({ vault, dbPath, maxHops: 0, mmrLambda: 1, twoPassEnabled: false });+ const store = await Store.open(config, { mode: "read", loadVec: false });+ try {+ const base = runFtsQueryDetailed(store, "warehouse rotation", { limit: 10 });+ const withheldIds = runFtsQueryDetailed(store, "wyrmshade", { limit: 10 })+ .hits.map((hit) => hit.chunkId)+ .filter(+ (id) => store.hydrateChunks([id]).get(id)?.path === "Brain/notes/private-wyrmshade.md",+ );+ expect(withheldIds.length).toBeGreaterThan(0);+ const pool = new Set([...base.hits.map((hit) => hit.chunkId), ...withheldIds]);+ const filterReachableIds = (ids: ReadonlyArray<number>): ReadonlyArray<number> =>+ ids.filter((id) => !withheldIds.includes(id));+ const loop = runIterativeRecall({+ store,+ query: "warehouse rotation wyrmshade",+ limit: 10,+ pathPrefix: undefined,+ timeRange: null,+ validityWindowFor: () => null,+ keywordHits: base.hits,+ chunkIds: pool,+ ids: [...pool],+ maxRounds: 3,+ firstRoundNumber: 2,+ isExpired: () => false,+ nowMs: () => 0,+ filterReachableIds,+ });+ // The rare term has no visible candidate anywhere in the corpus, so+ // the loop must not claim coverage over it: the stop is honest about+ // the pool's incompleteness and the term stays a reported gap.+ expect(loop.stopReason).not.toBe("coverage_complete");+ expect(loop.lastCoverage?.uncoveredRareTerms).toContain("wyrmshade");+ // No withheld candidate survives in the pool the loop reports.+ const poolPaths = [...store.hydrateChunks(loop.ids).values()].map((chunk) => chunk.path);+ expect(poolPaths).not.toContain("Brain/notes/private-wyrmshade.md");+ } finally {+ await store.close();+ }+ });++ test("a complete pool needs no round and an expired clock never starts one", async () => {+ await seed();+ const config = makeConfig({ vault, dbPath, maxHops: 0, mmrLambda: 1, twoPassEnabled: false });+ const store = await Store.open(config, { mode: "read", loadVec: false });+ try {+ const base = runFtsQueryDetailed(store, "warehouse rotation", { limit: 10 });+ const complete = runIterativeRecall({+ store,+ query: "warehouse rotation",+ limit: 10,+ pathPrefix: undefined,+ timeRange: null,+ validityWindowFor: () => null,+ keywordHits: base.hits,+ chunkIds: new Set(base.hits.map((h) => h.chunkId)),+ ids: base.hits.map((h) => h.chunkId),+ maxRounds: 3,+ firstRoundNumber: 2,+ isExpired: () => false,+ nowMs: () => 0,+ });+ expect(complete.rounds).toHaveLength(0);+ expect(complete.stopReason).toBe("coverage_complete");+ const expired = runIterativeRecall({+ store,+ query: "warehouse rotation chandelier",+ limit: 10,+ pathPrefix: undefined,+ timeRange: null,+ validityWindowFor: () => null,+ keywordHits: base.hits,+ chunkIds: new Set(base.hits.map((h) => h.chunkId)),+ ids: base.hits.map((h) => h.chunkId),+ maxRounds: 3,+ firstRoundNumber: 2,+ isExpired: () => true,+ nowMs: () => 0,+ });+ expect(expired.rounds).toHaveLength(0);+ expect(expired.stopReason).toBe("deadline");+ } finally {+ await store.close();+ }+ });+});++describe("iterative knob resolution", () => {+ test("defaults off and resolves the env pair, refusing an out-of-range cap by name", () => {+ const config = resolveSearchConfig({ vault });+ expect(config.recall.iterativeRecallEnabled ?? false).toBe(false);+ // Snapshot the twins themselves, not the whole env: keys this test+ // ADDS are absent from a whole-env snapshot, so a keys-of-saved+ // restore loop can never delete them and they leak into every later+ // file of a same-process directory run.+ const savedIterative = process.env["OPEN_SECOND_BRAIN_SEARCH_ITERATIVE"];+ const savedMaxRounds = process.env["OPEN_SECOND_BRAIN_SEARCH_ITERATIVE_MAX_ROUNDS"];+ try {+ process.env["OPEN_SECOND_BRAIN_SEARCH_ITERATIVE"] = "true";+ process.env["OPEN_SECOND_BRAIN_SEARCH_ITERATIVE_MAX_ROUNDS"] = "4";+ const on = resolveSearchConfig({ vault });+ expect(on.recall.iterativeRecallEnabled).toBe(true);+ expect(on.recall.iterativeRecallMaxRounds).toBe(4);+ expect(ITERATIVE_RECALL_MAX_ROUNDS_DEFAULT).toBe(2);+ expect(ITERATIVE_RECALL_MAX_ROUNDS_CAP).toBe(8);+ // The resolver refuses rather than clamps, like every knob bound.+ process.env["OPEN_SECOND_BRAIN_SEARCH_ITERATIVE_MAX_ROUNDS"] = "99";+ expect(() => resolveSearchConfig({ vault })).toThrow(/search_iterative_recall_max_rounds/);+ process.env["OPEN_SECOND_BRAIN_SEARCH_ITERATIVE_MAX_ROUNDS"] = "0";+ expect(() => resolveSearchConfig({ vault })).toThrow(/search_iterative_recall_max_rounds/);+ } finally {+ if (savedIterative === undefined) {+ delete process.env["OPEN_SECOND_BRAIN_SEARCH_ITERATIVE"];+ } else {+ process.env["OPEN_SECOND_BRAIN_SEARCH_ITERATIVE"] = savedIterative;+ }+ if (savedMaxRounds === undefined) {+ delete process.env["OPEN_SECOND_BRAIN_SEARCH_ITERATIVE_MAX_ROUNDS"];+ } else {+ process.env["OPEN_SECOND_BRAIN_SEARCH_ITERATIVE_MAX_ROUNDS"] = savedMaxRounds;+ }+ }+ });++ test("the plan-leg cache key names the round cap, so a raised cap re-keys plans", async () => {+ // A cached plan row records the round count it ran under: with the+ // cap absent from the key, raising `iterativeRecallMaxRounds` served+ // the cached plan - and its token - under the OLD budget until the+ // TTL expired. The suffix is `itv:plan:r<cap>`, so the keys must+ // partition by cap while commit keys stay token-partitioned (the cap+ // never changes what a committed payload means).+ await seed();+ const base = makeConfig({ vault, dbPath, maxHops: 0, mmrLambda: 1, twoPassEnabled: false });+ const keyFor = async (maxRounds?: number, commitToken?: string): Promise<string> => {+ const config = withIterative(base, maxRounds);+ const store = await Store.open(config, { mode: "read", loadVec: false });+ try {+ const probe = probeQueryCache({+ store,+ config,+ opts: {+ query: "warehouse rotation",+ iterative: true,+ ...(commitToken !== undefined ? { iterativeToken: commitToken } : {}),+ } as Parameters<typeof probeQueryCache>[0]["opts"],+ limit: 10,+ policy: { explicit: false, wantSemantic: false },+ sessionFocus: null,+ tuned: null,+ planHash: "plan-hash-stable",+ });+ if (probe.slot === null) throw new Error("cache probe returned no slot");+ return probe.slot.key;+ } finally {+ await store.close();+ }+ };+ const planDefault = await keyFor();+ const planRaised = await keyFor(4);+ expect(planRaised).not.toBe(planDefault);+ // The cap-lowered key is distinct too, and the commit partition is+ // indifferent to the cap: one token, one commit key at every cap.+ const planLowered = await keyFor(1);+ expect(planLowered).not.toBe(planDefault);+ expect(planLowered).not.toBe(planRaised);+ const commitAtDefault = await keyFor(undefined, KNOB_OFF_TOKEN);+ const commitAtRaised = await keyFor(4, KNOB_OFF_TOKEN);+ expect(commitAtRaised).toBe(commitAtDefault);+ expect(commitAtDefault).not.toBe(planDefault);+ });+});diff --git a/tests/core/search/surfacing-gate.test.ts b/tests/core/search/surfacing-gate.test.tsindex 8ba0d046..89241b9c 100644--- a/tests/core/search/surfacing-gate.test.ts+++ b/tests/core/search/surfacing-gate.test.ts@@ -1,6 +1,16 @@import { expect, test } from "bun:test";-import { evaluateSurfacingGate } from "../../../src/core/search/surfacing-gate.ts";+import { RECALL_INJECT_CONFIDENCE_FLOOR } from "../../../src/core/brain/recall-inject.ts";+import { RECALL_CHANNEL, RECALL_CHANNELS } from "../../../src/core/brain/recall-telemetry.ts";+import {+ evaluateGradedSurfacing,+ evaluateSurfacingGate,+} from "../../../src/core/search/surfacing-gate.ts";+import {+ computeSurfacingKey,+ SURFACING_ADMISSION_FLOORS,+ SurfacingKeyError,+} from "../../../src/core/search/surfacing-key.ts";test("evaluateSurfacingGate suppresses only structural non-recall prompts", () => {expect(evaluateSurfacingGate({ prompt: "" }).reason).toBe("empty");@@ -60,3 +70,141 @@ test("evaluateSurfacingGate admits a multi-line prompt that starts with a comman"shell_command",);});++// ----- graded surfacing key (t_107a3249, lane C Task 12) ---------------------++test("SURFACING_ADMISSION_FLOORS pins one constant per recall channel, hook at the inject floor", () => {+ for (const channel of RECALL_CHANNELS) {+ expect(SURFACING_ADMISSION_FLOORS[channel]).toBe(RECALL_INJECT_CONFIDENCE_FLOOR);+ }+});++test("computeSurfacingKey grades measurable match quality into admission tiers", () => {+ const floor = SURFACING_ADMISSION_FLOORS[RECALL_CHANNEL.mcp];+ expect(computeSurfacingKey({ matchQuality: floor, channel: RECALL_CHANNEL.mcp })).toEqual({+ key: floor,+ tier: "admitted",+ admit: true,+ reason: "admitted",+ });+ const weak = floor - 0.01;+ expect(computeSurfacingKey({ matchQuality: weak, channel: RECALL_CHANNEL.mcp })).toEqual({+ key: weak,+ tier: "below_floor",+ admit: false,+ reason: "below_floor",+ });+ expect(computeSurfacingKey({ matchQuality: null, channel: RECALL_CHANNEL.mcp })).toEqual({+ key: null,+ tier: "unmeasurable_quality",+ admit: false,+ reason: "unmeasurable_quality",+ });+});++test("computeSurfacingKey honours a caller-supplied floor over the channel constant", () => {+ // The hook's configurable confidence floor rides this override; the env+ // mirror is pinned in config tests, this pins the calculator's precedence.+ expect(+ computeSurfacingKey({ matchQuality: 0.4, channel: RECALL_CHANNEL.hook, floor: 0.5 }).admit,+ ).toBe(false);+ expect(+ computeSurfacingKey({ matchQuality: 0.5, channel: RECALL_CHANNEL.hook, floor: 0.5 }).admit,+ ).toBe(true);+});++test("computeSurfacingKey refuses an unmeasurable-shaped quality that is not null, by name", () => {+ expect(() => computeSurfacingKey({ matchQuality: 1.5, channel: RECALL_CHANNEL.mcp })).toThrow(+ SurfacingKeyError,+ );+ expect(() =>+ computeSurfacingKey({ matchQuality: Number.NaN, channel: RECALL_CHANNEL.mcp }),+ ).toThrow(SurfacingKeyError);+});++test("evaluateGradedSurfacing keeps the structural suppressions as named short-circuits above any quality", () => {+ // A suppressed prompt is never ranked, so the key stays null no matter+ // what quality a caller reports alongside it.+ expect(evaluateGradedSurfacing({ prompt: "/help", matchQuality: 0.9 })).toEqual({+ key: null,+ tier: "suppressed",+ admit: false,+ reason: "slash_command",+ });+ expect(evaluateGradedSurfacing({ prompt: "", matchQuality: 0.9 }).reason).toBe("empty");+ expect(evaluateGradedSurfacing({ prompt: "git status", matchQuality: 0.9 }).tier).toBe(+ "suppressed",+ );+ expect(+ evaluateGradedSurfacing({ prompt: "again", previousPrompt: "again", matchQuality: 0.9 }).tier,+ ).toBe("suppressed");+});++test("evaluateGradedSurfacing grades a fail-open prompt through the shared calculator", () => {+ const prompt = "what did we decide about recall diagnostics?";+ const weak = SURFACING_ADMISSION_FLOORS[RECALL_CHANNEL.mcp] - 0.1;+ expect(evaluateGradedSurfacing({ prompt, matchQuality: weak })).toEqual({+ key: weak,+ tier: "below_floor",+ admit: false,+ reason: "below_floor",+ });+ const strong = SURFACING_ADMISSION_FLOORS[RECALL_CHANNEL.mcp] + 0.1;+ expect(evaluateGradedSurfacing({ prompt, matchQuality: strong }).admit).toBe(true);+ // Explicit recall admits regardless of quality and carries the measurement.+ expect(evaluateGradedSurfacing({ prompt: "hello", explicit: true, matchQuality: 0.1 })).toEqual({+ key: 0.1,+ tier: "explicit",+ admit: true,+ reason: "explicit",+ });+ // Explicit with no measurement still admits; the key is honestly absent.+ expect(evaluateGradedSurfacing({ prompt: "hello", explicit: true })).toEqual({+ key: null,+ tier: "explicit",+ admit: true,+ reason: "explicit",+ });+});++test("an explicit request grades a measured null report as a null key, not an error", () => {+ // null is a legitimate measurement ("nothing was measurable"); the+ // explicit branch grades it like the default branch does instead of+ // handing it to the validator as a shape violation.+ expect(evaluateGradedSurfacing({ prompt: "hello", explicit: true, matchQuality: null })).toEqual({+ key: null,+ tier: "explicit",+ admit: true,+ reason: "explicit",+ });+});++test("evaluateGradedSurfacing without a measurement fails open as default_retrieve", () => {+ // Absent quality is not an unmeasurable report: the structural+ // projection failed open, and the reason records that it was a default.+ expect(evaluateGradedSurfacing({ prompt: "what did we decide?" })).toEqual({+ key: null,+ tier: "admitted",+ admit: true,+ reason: "default_retrieve",+ });+ // A measured `null` is an unmeasurable report, graded as one.+ expect(evaluateGradedSurfacing({ prompt: "what did we decide?", matchQuality: null })).toEqual({+ key: null,+ tier: "unmeasurable_quality",+ admit: false,+ reason: "unmeasurable_quality",+ });+});++test("evaluateGradedSurfacing routes admission through the requested channel", () => {+ for (const channel of RECALL_CHANNELS) {+ const floor = SURFACING_ADMISSION_FLOORS[channel];+ expect(evaluateGradedSurfacing({ prompt: "q", channel, matchQuality: floor })).toEqual({+ key: floor,+ tier: "admitted",+ admit: true,+ reason: "admitted",+ });+ }+});diff --git a/tests/core/search/two-pass.test.ts b/tests/core/search/two-pass.test.tsindex 731bfe59..8ecc09df 100644--- a/tests/core/search/two-pass.test.ts+++ b/tests/core/search/two-pass.test.ts@@ -5,7 +5,7 @@* in an abstention.*/-import { test, expect, beforeEach, afterEach, describe } from "bun:test";+import { test, expect, beforeEach, afterEach, describe, setSystemTime } from "bun:test";import { indexVault } from "../../../src/core/search/indexer.ts";import { search } from "../../../src/core/search/search.ts";@@ -91,3 +91,100 @@ describe("two-pass recall", () => {).toBe(true);});});++// ----- Iterative outcome observability (recall-quality wave, lane A) ------++describe("iterative outcome observability", () => {+ // A pinned clock must never outlive the test that pinned it: this file+ // runs in the same process as every other suite, and a shifted wall+ // clock would poison theirs.+ afterEach(() => setSystemTime());+ /** Six common docs anchor the match; the relic docs are the loop's recoverable mass. */+ async function seedRelic(): Promise<void> {+ for (let i = 1; i <= 6; i++) {+ writeMd(+ vault,+ `Brain/notes/wh${i}.md`,+ `# WH${i}\n\nWarehouse rotation schedule, bay ${i}.\n`,+ );+ }+ for (const term of ["relic01", "relic02", "relic03", "relic04"]) {+ writeMd(vault, `Brain/notes/${term}.md`, `# ${term}\n\n${term} provenance record.\n`);+ }+ const base = makeConfig({ vault, dbPath, maxHops: 0, mmrLambda: 1, twoPassEnabled: false });+ await indexVault(base);+ }++ const STOP_REASONS = new Set([+ "coverage_complete",+ "no_sub_query",+ "no_progress",+ "round_cap",+ "marginal_value",+ "deadline",+ "decider_round",+ ]);++ test("a loop that ran rounds reports per-round counts and a stop reason on the outcome", async () => {+ await seedRelic();+ const base = makeConfig({ vault, dbPath, maxHops: 0, mmrLambda: 1, twoPassEnabled: false });+ const config = {+ ...base,+ recall: { ...base.recall, iterativeRecallEnabled: true, iterativeRecallMaxRounds: 1 },+ } as typeof base;+ const outcome = await search(config, {+ query: "warehouse rotation relic01 relic02 relic03 relic04",+ iterative: true,+ });+ const iterative = outcome.iterative;+ expect(iterative).toBeDefined();+ if (iterative === undefined) throw new Error("unreachable");+ expect(iterative.phase).toBe("final");+ if (iterative.phase !== "final") throw new Error("unreachable");+ // The loop's rounds ride the field with their honest accounting.+ expect(iterative.rounds.length).toBeGreaterThanOrEqual(1);+ for (const [index, round] of iterative.rounds.entries()) {+ expect(round.round).toBe(2 + index);+ expect(round.author).toBe("deterministic");+ expect(Array.isArray(round.terms)).toBe(true);+ expect(round.groups).toBeGreaterThanOrEqual(1);+ expect(typeof round.added).toBe("number");+ expect(typeof round.elapsedMs).toBe("number");+ }+ expect(STOP_REASONS.has(iterative.stopReason)).toBe(true);+ // The observability rides the FIELD: no new attribution reason string.+ for (const r of outcome.results) {+ for (const reason of r.reasons) {+ expect(reason.startsWith("iterative")).toBe(false);+ }+ }+ // Mode off: the same query carries no marker at all.+ const off = await search(base, {+ query: "warehouse rotation relic01 relic02 relic03 relic04",+ });+ expect(off.iterative).toBeUndefined();+ });++ test("an inert loop adds no field, byte-identical to the mode-off outcome", async () => {+ await seedRelic();+ const base = makeConfig({ vault, dbPath, maxHops: 0, mmrLambda: 1, twoPassEnabled: false });+ const config = {+ ...base,+ recall: { ...base.recall, iterativeRecallEnabled: true },+ } as typeof base;+ const query = "warehouse rotation";+ // Pin the wall clock: the recency boost reads Date.now() per call, so+ // two searches a millisecond apart differ in float noise that has+ // nothing to do with the mode.+ try {+ setSystemTime(1_750_000_000_000);+ const off = await search(base, { query });+ setSystemTime(1_750_000_000_000);+ const on = await search(config, { query, iterative: true });+ expect(on.iterative).toBeUndefined();+ expect(JSON.stringify(on)).toBe(JSON.stringify(off));+ } finally {+ setSystemTime();+ }+ });+});diff --git a/tests/fixtures/bench/longmemeval-official-sample.json b/tests/fixtures/bench/longmemeval-official-sample.jsonnew file mode 100644index 00000000..4a911d35--- /dev/null+++ b/tests/fixtures/bench/longmemeval-official-sample.json@@ -0,0 +1,102 @@+[+ {+ "question_id": "single-session-user_1",+ "question_type": "single-session-user",+ "question": "What codename did we pick for the spring launch?",+ "answer": "Blue Heron",+ "question_date": "2023/05/20 (Sat) 02:21",+ "haystack_session_ids": ["answer_1", "noans_1"],+ "haystack_dates": ["2023/05/01 (Mon) 09:15", "2023/05/02 (Tue) 10:30"],+ "haystack_sessions": [+ [+ {+ "role": "user",+ "content": "We picked Blue Heron as the codename for the spring launch."+ },+ { "role": "assistant", "content": "Noted: the spring launch codename is Blue Heron." }+ ],+ [+ {+ "role": "user",+ "content": "I booked a cabin near Lake Alpine for the August hiking trip."+ },+ {+ "role": "assistant",+ "content": "Sounds great - the Lake Alpine cabin is booked for August."+ }+ ]+ ],+ "answer_session_ids": ["answer_1"]+ },+ {+ "question_id": "multi-session_2",+ "question_type": "multi-session",+ "question": "Which password manager did we settle on for the team?",+ "answer": "Vaultwarden",+ "question_date": "2023/05/20 (Sat) 02:25",+ "haystack_session_ids": ["answer_2a", "answer_2b", "noans_2"],+ "haystack_dates": [+ "2023/05/03 (Wed) 11:00",+ "2023/05/04 (Thu) 12:30",+ "2023/05/05 (Fri) 13:45"+ ],+ "haystack_sessions": [+ [+ {+ "role": "user",+ "content": "We evaluated Vaultwarden and Keeweb for the team password vault."+ },+ {+ "role": "assistant",+ "content": "Comparison saved: Vaultwarden self-hosting versus Keeweb portable."+ }+ ],+ [+ { "role": "user", "content": "We settled on Vaultwarden for the team password vault." },+ { "role": "assistant", "content": "Decided: Vaultwarden is the team password manager." }+ ],+ [+ {+ "role": "user",+ "content": "The book club picked a novel about lighthouse keepers this month."+ },+ {+ "role": "assistant",+ "content": "Noted: this month's book club novel features lighthouse keepers."+ }+ ]+ ],+ "answer_session_ids": ["answer_2a", "answer_2b"]+ },+ {+ "question_id": "single-session-user_3_abs",+ "question_type": "single-session-user",+ "question": "What is my sister's favorite coffee order?",+ "question_date": "2023/05/20 (Sat) 02:30",+ "haystack_session_ids": ["noans_1", "noans_2"],+ "haystack_dates": ["2023/05/02 (Tue) 10:30", "2023/05/05 (Fri) 13:45"],+ "haystack_sessions": [+ [+ {+ "role": "user",+ "content": "I booked a cabin near Lake Alpine for the August hiking trip."+ },+ {+ "role": "assistant",+ "content": "Sounds great - the Lake Alpine cabin is booked for August."+ }+ ],+ [+ {+ "role": "user",+ "content": "The book club picked a novel about lighthouse keepers this month."+ },+ {+ "role": "assistant",+ "content": "Noted: this month's book club novel features lighthouse keepers."+ }+ ]+ ],+ "answer_session_ids": []+ }+]diff --git a/tests/fixtures/bench/longmemeval-sample.json b/tests/fixtures/bench/longmemeval-sample.jsonnew file mode 100644index 00000000..85d84bd9--- /dev/null+++ b/tests/fixtures/bench/longmemeval-sample.json@@ -0,0 +1,99 @@+{+ "name": "sample",+ "questions": [+ {+ "q_id": "lm-q1",+ "question_type": "single-hop",+ "question": "launch codename",+ "answer": "Blue Heron",+ "haystack_session_id": ["sess-alpha", "sess-beta"],+ "haystack_dates": ["2026-03-02T10:00:00Z", "2026-03-03T10:00:00Z"],+ "haystack_session": [+ [+ {+ "role": "user",+ "content": "We picked Blue Heron as the launch codename for the spring release."+ },+ { "role": "assistant", "content": "Noted: the launch codename is Blue Heron." }+ ],+ [+ {+ "role": "user",+ "content": "The retro meeting moved to Thursday, and the demo script is due Wednesday."+ },+ {+ "role": "assistant",+ "content": "Got it: retro on Thursday, demo script due Wednesday, and the Blue Heron launch is on the agenda."+ }+ ]+ ],+ "answer_session_ids": ["sess-alpha"]+ },+ {+ "q_id": "lm-q2",+ "question_type": "multi-hop",+ "question": "heron",+ "answer": "Blue Heron",+ "haystack_session_id": ["sess-alpha", "sess-beta"],+ "haystack_dates": ["2026-03-02T10:00:00Z", "2026-03-03T10:00:00Z"],+ "haystack_session": [+ [+ {+ "role": "user",+ "content": "We picked Blue Heron as the launch codename for the spring release."+ },+ { "role": "assistant", "content": "Noted: the launch codename is Blue Heron." }+ ],+ [+ {+ "role": "user",+ "content": "The retro meeting moved to Thursday, and the demo script is due Wednesday."+ },+ {+ "role": "assistant",+ "content": "Got it: retro on Thursday, demo script due Wednesday, and the Blue Heron launch is on the agenda."+ }+ ]+ ],+ "answer_session_ids": ["sess-alpha", "sess-beta"]+ },+ {+ "q_id": "lm-q3",+ "question_type": "temporal-reasoning",+ "question": "retro thursday",+ "answer": "Thursday",+ "haystack_session_id": ["sess-beta"],+ "haystack_dates": ["2026-03-03T10:00:00Z"],+ "haystack_session": [+ [+ {+ "role": "user",+ "content": "The retro meeting moved to Thursday, and the demo script is due Wednesday."+ },+ {+ "role": "assistant",+ "content": "Got it: retro on Thursday, demo script due Wednesday, and the Blue Heron launch is on the agenda."+ }+ ]+ ],+ "answer_session_ids": ["sess-beta"]+ },+ {+ "q_id": "lm-q4",+ "question_type": "abstention",+ "question": "what color is the accountant's car",+ "haystack_session_id": ["sess-alpha"],+ "haystack_dates": ["2026-03-02T10:00:00Z"],+ "haystack_session": [+ [+ {+ "role": "user",+ "content": "We picked Blue Heron as the launch codename for the spring release."+ },+ { "role": "assistant", "content": "Noted: the launch codename is Blue Heron." }+ ]+ ],+ "answer_session_ids": []+ }+ ]+}diff --git a/tests/fixtures/bench/surfacing-replay-sample.json b/tests/fixtures/bench/surfacing-replay-sample.jsonnew file mode 100644index 00000000..c56f2042--- /dev/null+++ b/tests/fixtures/bench/surfacing-replay-sample.json@@ -0,0 +1,40 @@+{+ "name": "sample",+ "description": "Tiny committed surfacing-replay session: two prompts memory should speak up about, one weak-match prompt it must stay quiet about, and one structural non-prompt. The weak turn's only term is hyphenated ('billing-migration'), so the keyword lane retrieves the billing rows while the graded key reads zero substring coverage - the calibrated floor abstains and a permissive zero floor false-fires. Note paths stay under Brain/ because that is the tree the shipped indexer walks.",+ "notes": [+ {+ "path": "Brain/_brain.yaml",+ "body": "schema_version: 1\n"+ },+ {+ "path": "Brain/notes/launch.md",+ "body": "The Atlas launch checklist is owned by Marco. The billing migration finishes before the launch freeze in March."+ },+ {+ "path": "Brain/notes/pivot.md",+ "body": "The pivot review paused the mobile app and moved the team to the data pipeline. Priya owns the billing migration."+ }+ ],+ "turns": [+ {+ "id": "turn-1",+ "text": "billing migration",+ "expect": "inject"+ },+ {+ "id": "turn-2",+ "text": "mobile app",+ "expect": "inject"+ },+ {+ "id": "turn-3",+ "text": "billing-migration",+ "expect": "abstain"+ },+ {+ "id": "turn-4",+ "text": "/help",+ "expect": "abstain"+ }+ ]+}diff --git a/tests/helpers/tool-probe-catalogue.ts b/tests/helpers/tool-probe-catalogue.tsindex ae0ccdf7..e32de062 100644--- a/tests/helpers/tool-probe-catalogue.ts+++ b/tests/helpers/tool-probe-catalogue.ts@@ -297,7 +297,7 @@ export const REASONS_REACHING_OWNER_CONTENT: ReadonlySet<string> = new Set([REAS* test that reads them.*/export const PROBE_ENTRY_COUNT = 101;-export const PROBE_RECIPE_COUNT = 234;+export const PROBE_RECIPE_COUNT = 235;export const PROBE_TWO_SIDED_COUNT = 32;/**@@ -364,7 +364,19 @@ export const UNSCOPED_CONTENT: ReadonlyArray<ProbeEntry> = [},],},- { name: "brain_session_grep", calls: one({ query: QUERY }, REASON.sessionLane) },+ {+ name: "brain_session_grep",+ calls: [+ { args: { query: QUERY }, reason: REASON.sessionLane },+ {+ // The coverage operation (t_2c2a883c): a whole-scope selection over+ // a fixture with no imported sessions, so it must answer empty+ // rather than leak or throw.+ args: { operation: "coverage", char_budget: 100_000 },+ reason: REASON.sessionLane,+ },+ ],+ },{ name: "brain_session_expand", calls: one({ id: "sess-probe:0" }, REASON.sessionLane) },{name: "brain_session_summary",diff --git a/tests/mcp/brain-search-reasons.test.ts b/tests/mcp/brain-search-reasons.test.tsindex 9a8953bc..6dcf5746 100644--- a/tests/mcp/brain-search-reasons.test.ts+++ b/tests/mcp/brain-search-reasons.test.ts@@ -12,6 +12,10 @@ import { join } from "node:path";import { SEARCH_TOOLS } from "../../src/mcp/search-tools.ts";import { indexVault, resolveSearchConfig } from "../../src/core/search/index.ts";import { atomicWriteFileSync } from "../../src/core/fs-atomic.ts";+import { fakeCredential } from "../helpers/fake-credentials.ts";++/** A round commit token shared by the partition probes; assembled from parts. */+const COMMIT_TOKEN = fakeCredential("drt", "-3-abc");let vault: string;let configHome: string;@@ -28,7 +32,7 @@ beforeEach(async () => {"---\ntitle: Alpha\n---\n\nThe quick brown fox jumps over the lazy dog.\n",);ctx = { vault, configPath };- const config = resolveSearchConfig({ vault, configPath });+ const config = resolveSearchConfig({ vault, configPath: ctx.configPath });await indexVault(config, {});});@@ -55,3 +59,154 @@ describe("brain_search reasons", () => {}});});++// ----- Iterative cache-key compatibility (recall-quality wave, lane A) ----++/**+ * The query-cache key composition is a documented compatibility surface+ * (cache-slot.ts header): the iterative fields may join ONLY as a+ * mode-on suffix appended to the config fingerprint, so plain rows keep+ * their pre-wave keys byte-identical, a plan leg and a commit leg never+ * collide with each other or with a plain row, and a flag-without-knob+ * request stays keyed exactly like a plain one. The single-use token+ * registry rides the same table with its own TTL.+ */+describe("brain_search iterative cache keys", () => {+ const planHash = "plan-hash-stable";+ const policy = { explicit: false, wantSemantic: false };++ async function keyFor(opts: Record<string, unknown>): Promise<string> {+ const { Store } = await import("../../src/core/search/store.ts");+ const { probeQueryCache } = await import("../../src/core/search/pipeline/cache-slot.ts");+ const config = resolveSearchConfig({ vault, configPath: ctx.configPath });+ const store = await Store.open(config, { mode: "read", loadVec: false });+ try {+ const probe = probeQueryCache({+ store,+ config,+ opts: opts as unknown as Parameters<typeof probeQueryCache>[0]["opts"],+ limit: 10,+ policy,+ sessionFocus: null,+ tuned: null,+ planHash,+ });+ if (probe.slot === null) throw new Error("cache probe returned no slot");+ return probe.slot.key;+ } finally {+ await store.close();+ }+ }++ test("the mode-on suffix partitions plan, commit and plain rows; off-mode keys are unchanged", async () => {+ // The suffix exists only when the mode is actually on, so this test+ // runs with the operator's knob on (env-mirrored like its siblings).+ const saved = process.env["OPEN_SECOND_BRAIN_SEARCH_ITERATIVE"];+ process.env["OPEN_SECOND_BRAIN_SEARCH_ITERATIVE"] = "true";+ try {+ await partitionedKeys();+ } finally {+ if (saved === undefined) delete process.env["OPEN_SECOND_BRAIN_SEARCH_ITERATIVE"];+ else process.env["OPEN_SECOND_BRAIN_SEARCH_ITERATIVE"] = saved;+ }+ });++ async function partitionedKeys(): Promise<void> {+ const base = { query: "quick fox", iterative: false };+ const plain = await keyFor({ query: "quick fox" });+ // Flag off and flag-absent key identically: no suffix bytes exist.+ expect(await keyFor(base)).toBe(plain);+ const plan = await keyFor({ query: "quick fox", iterative: true });+ const commit = await keyFor({+ query: "quick fox",+ iterative: true,+ iterativeToken: COMMIT_TOKEN,+ iterativePayload: { evidence: [1], subQueries: ["q"] },+ });+ const commitOtherPayload = await keyFor({+ query: "quick fox",+ iterative: true,+ iterativeToken: COMMIT_TOKEN,+ iterativePayload: { evidence: [2], subQueries: ["q"] },+ });+ // Three disjoint rows: plain, plan, commit - and a different payload+ // is a different commit key.+ expect(plan).not.toBe(plain);+ expect(commit).not.toBe(plain);+ expect(commit).not.toBe(plan);+ expect(commitOtherPayload).not.toBe(commit);+ }++ test("a flag without the operator's knob is keyed exactly like a plain row", async () => {+ // The default config has the iterative knob OFF, so the mode is inert+ // end to end: no suffix, the plain key.+ const plain = await keyFor({ query: "quick fox" });+ const flagged = await keyFor({ query: "quick fox", iterative: true });+ expect(flagged).toBe(plain);+ });++ test("a minted round token validates, claims once, and releases back to retryable", async () => {+ const { Store } = await import("../../src/core/search/store.ts");+ const {+ claimIterativeToken,+ iterativeTokenSpent,+ mintIterativeToken,+ readIterativeTokenRecord,+ releaseIterativeToken,+ } = await import("../../src/core/search/pipeline/cache-slot.ts");+ const config = resolveSearchConfig({ vault, configPath: ctx.configPath });+ const store = await Store.open(config, { mode: "read", loadVec: false });+ try {+ const now = 1_750_000_000_000;+ // A nonce-mint-shaped token, assembled from parts (never a literal).+ const token = fakeCredential("drt-3-", "5f1e", "2d3c4b5a69788796a5b4");+ expect(iterativeTokenSpent(store, config, token, now)).toBe(false);+ expect(readIterativeTokenRecord(store, config, token, now)).toBeNull();+ // The plan phase files the pause digest and the recorded round+ // count under the nonce token; the commit reads the row back and+ // validates its replayed state against the digest, then replays+ // exactly the recorded rounds.+ expect(+ mintIterativeToken(+ store,+ config,+ token,+ { pauseDigest: "pausedigest-01", rounds: 2, stopReason: "round_cap" },+ now,+ ),+ ).toBe(true);+ expect(readIterativeTokenRecord(store, config, token, now)).toEqual({+ pauseDigest: "pausedigest-01",+ rounds: 2,+ stopReason: "round_cap",+ });+ expect(iterativeTokenSpent(store, config, token, now)).toBe(false);+ // The claim is insert-once: the second racing commit's claim loses,+ // and the spent marker outrides the mint row it sits beside.+ expect(claimIterativeToken(store, config, token, now)).toBe(true);+ expect(claimIterativeToken(store, config, token, now)).toBe(false);+ expect(iterativeTokenSpent(store, config, token, now)).toBe(true);+ expect(readIterativeTokenRecord(store, config, token, now)).toEqual({+ pauseDigest: "pausedigest-01",+ rounds: 2,+ stopReason: "round_cap",+ });+ // A failed round releases its own claim: the token reads unspent+ // and its mint row (the retry's validation source) survives.+ releaseIterativeToken(store, token);+ expect(iterativeTokenSpent(store, config, token, now)).toBe(false);+ expect(readIterativeTokenRecord(store, config, token, now)).toEqual({+ pauseDigest: "pausedigest-01",+ rounds: 2,+ stopReason: "round_cap",+ });+ // Every registry row dies with the TTL: a token whose plan phase+ // expired can be neither validated nor replayed.+ const ttlMs = config.recall.cacheTtlSeconds * 1000;+ expect(iterativeTokenSpent(store, config, token, now + ttlMs + 1)).toBe(false);+ expect(readIterativeTokenRecord(store, config, token, now + ttlMs + 1)).toBeNull();+ } finally {+ await store.close();+ }+ });+});diff --git a/tests/mcp/recall-gate-telemetry.test.ts b/tests/mcp/recall-gate-telemetry.test.tsindex d2fb8cc4..6477c5a3 100644--- a/tests/mcp/recall-gate-telemetry.test.ts+++ b/tests/mcp/recall-gate-telemetry.test.ts@@ -148,7 +148,10 @@ test("with the opt-in on, a negative verdict lands as a continuity record", asynexpect(JSON.stringify(records[0]!.payload)).not.toContain("reactor coolant");expect(typeof records[0]!.payload["prompt_hash"]).toBe("string");// A host filesystem path is not vault content and must not replicate.- expect(JSON.stringify(records[0]!.payload)).not.toContain(tmp);+ // Judge the JSON-escaped form: on win32 hosts a leaked path serializes+ // with doubled backslashes, so the raw tmp string can never match and+ // the invariant would silently stop being enforced.+ expect(JSON.stringify(records[0]!.payload)).not.toContain(JSON.stringify(tmp).slice(1, -1));});test("a usable-score call writes no negative record even with the opt-in on", async () => {@@ -160,3 +163,145 @@ test("a usable-score call writes no negative record even with the opt-in on", as});expect(negativeRecallRecords()).toHaveLength(0);});++// ----- graded surfacing telemetry (t_107a3249, lane C Task 14) ---------------++test("a measured call grades the verdict: below_floor refuses and records a skip", async () => {+ writeFileSync(configPath, `vault: "${vault}"\nrecall_gate_telemetry: "true"\n`);+ const out = (await tool("brain_recall_gate").handler(ctx(), {+ prompt: "what did we decide about the index?",+ scores: [0.9],+ match_quality: 0.2,+ })) as Record<string, unknown>;+ // The graded admission decides the binary verdict when a measurement+ // rides the call: a below-floor quality is a refusal, so `retrieve`+ // and `admit` agree with the tier instead of contradicting it.+ expect(out["retrieve"]).toBe(false);+ expect(out["admit"]).toBe(false);+ expect(out["key"]).toBe(0.2);+ expect(out["tier"]).toBe("below_floor");+ const records = listGateTelemetry(vault);+ expect(records).toHaveLength(1);+ // The record's decision agrees with the admission: a below-floor call+ // is a skip, never a retrieved one.+ expect(records[0]!.payload["decision"]).toBe("skip");+ expect(records[0]!.payload["key"]).toBe(0.2);+ expect(records[0]!.payload["tier"]).toBe("below_floor");+ expect(records[0]!.payload["channel"]).toBe("mcp");+ // The privacy invariant holds for the graded payload: numbers land, the+ // prompt never does.+ expect(JSON.stringify(records[0]!.payload)).not.toContain("what did we decide");+ // The summary agrees: a below-floor measured call is not counted as+ // retrieved.+ const summary = (await tool("brain_recall_telemetry").handler(ctx(), {+ operation: "gate_summary",+ })) as { retrieved: number; skipped: number };+ expect(summary.retrieved).toBe(0);+ expect(summary.skipped).toBe(1);+});++test("a measured admitted call retrieves, admits and records a retrieve", async () => {+ writeFileSync(configPath, `vault: "${vault}"\nrecall_gate_telemetry: "true"\n`);+ const out = (await tool("brain_recall_gate").handler(ctx(), {+ prompt: "what did we decide about the index?",+ scores: [0.9],+ match_quality: 0.8,+ })) as Record<string, unknown>;+ expect(out["retrieve"]).toBe(true);+ expect(out["admit"]).toBe(true);+ expect(out["tier"]).toBe("admitted");+ const records = listGateTelemetry(vault);+ expect(records[0]!.payload["decision"]).toBe("retrieve");+});++test("an unmeasured call records no key or tier and keeps the structural verdict", async () => {+ writeFileSync(configPath, `vault: "${vault}"\nrecall_gate_telemetry: "true"\n`);+ const out = (await tool("brain_recall_gate").handler(ctx(), {+ prompt: "what did we decide about the index?",+ })) as Record<string, unknown>;+ expect("key" in out).toBe(false);+ expect("tier" in out).toBe(false);+ // Without a measurement the structural fail-open stands and `admit`+ // names it: the binary verdict is the structural one, unchanged.+ expect(out["retrieve"]).toBe(true);+ expect(out["admit"]).toBe(true);+ const records = listGateTelemetry(vault);+ expect(records).toHaveLength(1);+ expect("key" in records[0]!.payload).toBe(false);+ expect("tier" in records[0]!.payload).toBe(false);+ expect(records[0]!.payload["decision"]).toBe("retrieve");+ // The transport is recorded only on measured decisions: an unmeasured+ // structural verdict is already described by decision and reason.+ expect("channel" in records[0]!.payload).toBe(false);+});++test("a boundary quality grades admitted through the mcp channel constant", async () => {+ writeFileSync(configPath, `vault: "${vault}"\nrecall_gate_telemetry: "true"\n`);+ await tool("brain_recall_gate").handler(ctx(), {+ prompt: "what did we decide about the index?",+ scores: [0.5],+ match_quality: 0.35,+ });+ const records = listGateTelemetry(vault);+ expect(records[0]!.payload["tier"]).toBe("admitted");+});++test("a suppressed prompt grades suppressed with a null key, never a measured one", async () => {+ writeFileSync(configPath, `vault: "${vault}"\nrecall_gate_telemetry: "true"\n`);+ await tool("brain_recall_gate").handler(ctx(), {+ prompt: "git status",+ scores: [0.9],+ match_quality: 0.9,+ });+ const records = listGateTelemetry(vault);+ expect(records[0]!.payload["tier"]).toBe("suppressed");+ expect(records[0]!.payload["key"]).toBeNull();+ expect(records[0]!.payload["decision"]).toBe("skip");+});++test("gate_summary summarizes counts by tier", async () => {+ writeFileSync(configPath, `vault: "${vault}"\nrecall_gate_telemetry: "true"\n`);+ await tool("brain_recall_gate").handler(ctx(), {+ prompt: "what did we decide about the index?",+ scores: [0.9],+ match_quality: 0.2,+ });+ await tool("brain_recall_gate").handler(ctx(), {+ prompt: "what did we decide about the index?",+ scores: [0.9],+ match_quality: 0.8,+ });+ // Unmeasured: counted in by_reason as always, absent from by_tier.+ await tool("brain_recall_gate").handler(ctx(), { prompt: "/help" });+ const summary = (await tool("brain_recall_telemetry").handler(ctx(), {+ operation: "gate_summary",+ })) as {+ total: number;+ retrieved: number;+ skipped: number;+ by_reason: Record<string, number>;+ by_tier: Record<string, number>;+ };+ expect(summary.total).toBe(3);+ expect(summary.by_tier).toEqual({ below_floor: 1, admitted: 1 });+ expect(summary.by_reason["slash_command"]).toBe(1);+ // The below-floor measured call is a skip under the graded verdict:+ // only the admitted call counts as retrieved.+ expect(summary.retrieved).toBe(1);+ expect(summary.skipped).toBe(2);+});++test("fail-open: a broken store never breaks the graded response", async () => {+ writeFileSync(configPath, `vault: "${vault}"\nrecall_gate_telemetry: "true"\n`);+ mkdirSync(join(vault, "Brain", "log"), { recursive: true });+ writeFileSync(join(vault, "Brain", "log", "continuity"), "not a directory");+ const decision = (await tool("brain_recall_gate").handler(ctx(), {+ prompt: "what did we decide about the index?",+ scores: [0.9],+ match_quality: 0.2,+ })) as Record<string, unknown>;+ expect(typeof decision["retrieve"]).toBe("boolean");+ expect(decision["admit"]).toBe(false);+ expect(decision["key"]).toBe(0.2);+ expect(decision["tier"]).toBe("below_floor");+});diff --git a/tests/mcp/search-global.test.ts b/tests/mcp/search-global.test.tsindex 226a5b92..84460ecd 100644--- a/tests/mcp/search-global.test.ts+++ b/tests/mcp/search-global.test.ts@@ -11,6 +11,7 @@ import { join } from "node:path";import { addRecallSource } from "../../src/core/brain/portability/recall-sources.ts";import { indexVault } from "../../src/core/search/indexer.ts";import { resolveSearchConfig } from "../../src/core/search/index.ts";+import { INVALID_PARAMS, MCPError } from "../../src/mcp/protocol.ts";import { buildToolTable, findTool } from "../../src/mcp/tools.ts";import type { ServerContext } from "../../src/mcp/tool-contract.ts";import { writeMd } from "../helpers/search-fixtures.ts";@@ -49,6 +50,34 @@ function searchTool() {return findTool(buildToolTable("full"), "brain_search");}+test("the iterative round-trip is refused on the cross-vault union by name", async () => {+ let error: unknown;+ try {+ await searchTool().handler(ctx, { query: "chimera", global: true, iterative: true });+ } catch (e) {+ error = e;+ }+ expect(error).toBeInstanceOf(MCPError);+ expect((error as MCPError).code).toBe(INVALID_PARAMS);+ expect((error as MCPError).message).toContain("global");+ // The commit leg's fields are refused under the same named error, so+ // a token can never mark a per-origin pause spent through the union.+ let commitError: unknown;+ try {+ await searchTool().handler(ctx, {+ query: "chimera",+ global: true,+ iterative: true,+ iterative_token: "tok",+ iterative_payload: { evidence: [1], subQueries: ["chimera"] },+ });+ } catch (e) {+ commitError = e;+ }+ expect(commitError).toBeInstanceOf(MCPError);+ expect((commitError as MCPError).code).toBe(INVALID_PARAMS);+});+test("global search returns origin-labelled results from both vaults", async () => {const result = (await searchTool().handler(ctx, { query: "chimera", global: true })) as {results: Array<{ origin?: string; reasons: string[] }>;diff --git a/tests/mcp/search.test.ts b/tests/mcp/search.test.tsindex 15ca10e2..e2121db2 100644--- a/tests/mcp/search.test.ts+++ b/tests/mcp/search.test.ts@@ -7,7 +7,7 @@* the actual search query are all exercised together.*/-import { afterEach, beforeEach, expect, test } from "bun:test";+import { afterEach, beforeEach, expect, setSystemTime, test } from "bun:test";import { existsSync, mkdirSync, mkdtempSync, readdirSync, rmSync, writeFileSync } from "node:fs";import { tmpdir } from "node:os";import { join } from "node:path";@@ -228,6 +228,7 @@ test("brain_recall_gate reports skip reasons without affecting explicit brain_se});expect(extractToolResult(gate)).toEqual({retrieve: false,+ admit: false,reason: "shell_command",});@@ -391,3 +392,254 @@ test("brain_recall_feedback enforces its advertised query maxLength before recorexpect(within["recorded"]).toBe(true);expect(readdirSync(feedbackDir(vault))).toHaveLength(1);});++// ----- Iterative recall round-trip (recall-quality wave, lane A) ----------++/**+ * Six common-term docs pin the IDF floor; the relic docs are recoverable;+ * the wyrm terms live only in the query, so their IDF mass keeps coverage+ * below the completeness threshold no matter how many relics the loop+ * recovers - which is what leaves the plan phase a measurable gap to+ * pause on.+ */+function seedIterativeVault(): void {+ for (let i = 1; i <= 6; i++) {+ writeMd(`notes/wh${i}.md`, `# WH${i}\n\nWarehouse rotation schedule, bay ${i}.\n`);+ }+ for (const term of ["relic01", "relic02"]) {+ writeMd(`notes/${term}.md`, `# ${term}\n\n${term} provenance record.\n`);+ }+}++/**+ * The common terms anchor the match; the numbered relic terms name the+ * provenance docs. The pool the lanes return leaves rare query terms+ * uncovered past the deterministic budget, so the loop pauses with+ * measurable gaps - the state the round-trip needs. The query stays+ * SHORT: the plan-phase envelope echoes it, and a long query would push+ * the response past the server's preview budget, which swaps the+ * response for a preview artifact and hides the marker this test reads.+ */+const iterativeQuery = () => "warehouse rotation relic01 relic02 relic03 relic04 relic05 relic06";++interface IterativePlan {+ phase: string;+ round: number;+ token: string;+ llm_step: { status: string; step: string; prompt: string; schema_hints: string[] };+ pool_ids: number[];+ gaps: string[];+ rounds?: ReadonlyArray<{ round: number; added: number }>;+ stop_reason?: string;+}++/**+ * The round-trip responses carry the plan envelope, which can exceed the+ * server's preview budget: `content[0].text` then holds the bounded+ * preview envelope, while `structuredContent` always holds the full,+ * contract-validated object. The round-trip asserts on the full body.+ */+function extractFullBody(resp: any): Record<string, unknown> {+ if (resp?.result?.structuredContent) return resp.result.structuredContent;+ return extractToolResult(resp);+}++test("brain_search iterative round-trip: plan phase carries the envelope, commit phase finalizes", async () => {+ savedEnv["OPEN_SECOND_BRAIN_SEARCH_ITERATIVE"] =+ process.env["OPEN_SECOND_BRAIN_SEARCH_ITERATIVE"];+ process.env["OPEN_SECOND_BRAIN_SEARCH_ITERATIVE"] = "true";+ seedIterativeVault();+ const cfg = resolveSearchConfig({ vault, configPath });+ try {+ await indexVault(cfg);+ const server = makeServer();+ await initialize(server);++ // Phase one: the flag alone asks for the plan.+ const planResp = extractFullBody(+ await call(server, "brain_search", { query: iterativeQuery(), limit: 5, iterative: true }),+ );+ const plan = planResp["iterative"] as IterativePlan | undefined;+ expect(plan).toBeDefined();+ expect(plan!.phase).toBe("needs-llm-step");+ expect(plan!.llm_step.status).toBe("needs-llm-step");+ expect(plan!.token).toMatch(/^drt-\d+-/);+ expect(plan!.round).toBeGreaterThanOrEqual(2);+ expect(plan!.pool_ids.length).toBeGreaterThan(0);+ expect(plan!.gaps.length).toBeGreaterThan(0);+ expect(typeof plan!.llm_step.prompt).toBe("string");+ // The plan marker carries the deterministic loop's accounting too:+ // what the rounds before the pause recovered and why the budget+ // stopped while gaps remain - both fields the type carries and the+ // output schema declares for this marker.+ expect(Array.isArray(plan!.rounds)).toBe(true);+ expect((plan!.rounds ?? []).length).toBeGreaterThan(0);+ expect(typeof plan!.stop_reason).toBe("string");++ // Phase two: the token plus the committed payload finalizes.+ const commitArgs = {+ query: iterativeQuery(),+ limit: 5,+ iterative: true,+ iterative_token: plan!.token,+ iterative_payload: {+ evidence: [plan!.pool_ids[0]],+ subQueries: ["relic01 relic02"],+ },+ };+ const finalBody = extractFullBody(await call(server, "brain_search", commitArgs));+ const finalPhase = finalBody["iterative"] as+ | {+ phase: string;+ rounds?: ReadonlyArray<{ round: number; added: number }>;+ stop_reason?: string;+ }+ | undefined;+ expect(finalPhase).toBeDefined();+ expect(finalPhase!.phase).toBe("final");+ // The final marker carries the loop's accounting: what each+ // deterministic round recovered and why the budget stopped.+ expect(Array.isArray(finalPhase!.rounds)).toBe(true);+ expect((finalPhase!.rounds ?? []).length).toBeGreaterThan(0);+ expect(typeof finalPhase!.stop_reason).toBe("string");+ const results = finalBody["results"] as Array<Record<string, unknown>>;+ expect(results.length).toBeGreaterThan(0);++ // The token was single use: replaying the commit is refused by name,+ // never silently re-run.+ const replay = (await call(server, "brain_search", commitArgs)) as any;+ expect(replay?.error?.code).toBe(-32602);+ expect(replay?.error?.message ?? "").toContain("token_used");+ } finally {+ if (savedEnv["OPEN_SECOND_BRAIN_SEARCH_ITERATIVE"] === undefined) {+ delete process.env["OPEN_SECOND_BRAIN_SEARCH_ITERATIVE"];+ } else {+ process.env["OPEN_SECOND_BRAIN_SEARCH_ITERATIVE"] =+ savedEnv["OPEN_SECOND_BRAIN_SEARCH_ITERATIVE"];+ }+ }+});++test("a malformed decider payload is a caller error (-32602), never an internal error", async () => {+ savedEnv["OPEN_SECOND_BRAIN_SEARCH_ITERATIVE"] =+ process.env["OPEN_SECOND_BRAIN_SEARCH_ITERATIVE"];+ process.env["OPEN_SECOND_BRAIN_SEARCH_ITERATIVE"] = "true";+ seedIterativeVault();+ const cfg = resolveSearchConfig({ vault, configPath });+ try {+ await indexVault(cfg);+ const server = makeServer();+ await initialize(server);+ const planResp = extractFullBody(+ await call(server, "brain_search", { query: iterativeQuery(), limit: 5, iterative: true }),+ );+ const plan = planResp["iterative"] as IterativePlan | undefined;+ expect(plan).toBeDefined();++ // The most likely caller mistake - a payload missing its `subQueries`+ // half - is a shape refusal. It must surface as the caller-error code+ // with the typed INVALID_INPUT token, never as -32603 with prose.+ const malformed = (await call(server, "brain_search", {+ query: iterativeQuery(),+ limit: 5,+ iterative: true,+ iterative_token: plan!.token,+ iterative_payload: { evidence: [plan!.pool_ids[0]] },+ })) as any;+ expect(malformed?.error?.code).toBe(-32602);+ expect(malformed?.error?.data?.code).toBe("INVALID_INPUT");+ expect(malformed?.error?.message ?? "").toContain("shape");++ // A payload that passes shape but breaks a registered semantic rule+ // (five sub-queries against a budget of four) is the same class of+ // caller error.+ const overLimit = (await call(server, "brain_search", {+ query: iterativeQuery(),+ limit: 5,+ iterative: true,+ iterative_token: plan!.token,+ iterative_payload: {+ evidence: [plan!.pool_ids[0]],+ subQueries: ["a", "b", "c", "d", "e"],+ },+ })) as any;+ expect(overLimit?.error?.code).toBe(-32602);+ expect(overLimit?.error?.data?.code).toBe("INVALID_INPUT");++ // A sub-query of pure punctuation passes shape but carries no+ // significant terms; the registered check refuses it as the same+ // caller-error class.+ const punctuationOnly = (await call(server, "brain_search", {+ query: iterativeQuery(),+ limit: 5,+ iterative: true,+ iterative_token: plan!.token,+ iterative_payload: { evidence: [plan!.pool_ids[0]], subQueries: ["---"] },+ })) as any;+ expect(punctuationOnly?.error?.code).toBe(-32602);+ expect(punctuationOnly?.error?.data?.code).toBe("INVALID_INPUT");++ // Neither refusal spent the token: the valid commit still goes through.+ const finalBody = extractFullBody(+ await call(server, "brain_search", {+ query: iterativeQuery(),+ limit: 5,+ iterative: true,+ iterative_token: plan!.token,+ iterative_payload: { evidence: [plan!.pool_ids[0]], subQueries: ["relic01 relic02"] },+ }),+ );+ const finalPhase = finalBody["iterative"] as { phase: string } | undefined;+ expect(finalPhase).toBeDefined();+ expect(finalPhase!.phase).toBe("final");+ } finally {+ if (savedEnv["OPEN_SECOND_BRAIN_SEARCH_ITERATIVE"] === undefined) {+ delete process.env["OPEN_SECOND_BRAIN_SEARCH_ITERATIVE"];+ } else {+ process.env["OPEN_SECOND_BRAIN_SEARCH_ITERATIVE"] =+ savedEnv["OPEN_SECOND_BRAIN_SEARCH_ITERATIVE"];+ }+ }+});++test("brain_search with the knob on but the flag omitted is byte-identical to the knob off", async () => {+ writeMd("notes/plain.md", "# Plain\n\nthe quarterly ledger reconciliation runbook\n");+ await indexVault(resolveSearchConfig({ vault, configPath }));+ const server = makeServer();+ await initialize(server);+ const query = "quarterly ledger reconciliation";+ // Pin the wall clock: the recency boost reads Date.now() per call, so+ // two searches a millisecond apart differ in float noise that has+ // nothing to do with the mode.+ savedEnv["OPEN_SECOND_BRAIN_SEARCH_ITERATIVE"] =+ process.env["OPEN_SECOND_BRAIN_SEARCH_ITERATIVE"];+ process.env["OPEN_SECOND_BRAIN_SEARCH_ITERATIVE"] = "true";+ try {+ // Pin the wall clock: the recency boost reads Date.now() per call, so+ // two searches a millisecond apart differ in float noise that has+ // nothing to do with the mode. The pin never outlives this test.+ setSystemTime(1_750_000_000_000);+ // record_access off on both legs: the first call's activation record+ // would otherwise feed the second call's usage-aware ranking - a real+ // effect, but one that has nothing to do with the mode under test.+ const off = extractToolResult(+ await call(server, "brain_search", { query, limit: 5, record_access: false }),+ );+ expect(off["iterative"]).toBeUndefined();+ setSystemTime(1_750_000_000_000);+ // Mode on (the operator knob), operation not requested (no flag):+ // the same request must serialize identically, no phase marker.+ const inert = extractToolResult(+ await call(server, "brain_search", { query, limit: 5, record_access: false }),+ );+ expect(JSON.stringify(inert)).toBe(JSON.stringify(off));+ } finally {+ setSystemTime();+ if (savedEnv["OPEN_SECOND_BRAIN_SEARCH_ITERATIVE"] === undefined) {+ delete process.env["OPEN_SECOND_BRAIN_SEARCH_ITERATIVE"];+ } else {+ process.env["OPEN_SECOND_BRAIN_SEARCH_ITERATIVE"] =+ savedEnv["OPEN_SECOND_BRAIN_SEARCH_ITERATIVE"];+ }+ }+});diff --git a/tests/mcp/session-recall-tool.test.ts b/tests/mcp/session-recall-tool.test.tsindex a2fa79e2..04863797 100644--- a/tests/mcp/session-recall-tool.test.ts+++ b/tests/mcp/session-recall-tool.test.ts@@ -4,6 +4,7 @@ import { tmpdir } from "node:os";import { join } from "node:path";import { importSessionRecall } from "../../src/core/brain/session-recall.ts";+import { appendContinuityRecord } from "../../src/core/brain/continuity/store.ts";import type { SessionTurn } from "../../src/core/brain/sessions/types.ts";import { JSONRPC_VERSION, MCPServer, PROTOCOL_VERSION } from "../../src/mcp/index.ts";import { buildToolTable } from "../../src/mcp/tools.ts";@@ -194,3 +195,206 @@ describe("session recall MCP tools", () => {expect(response.error !== undefined || response.result?.isError === true).toBe(true);});});++describe("brain_session_grep coverage operation (t_2c2a883c)", () => {+ test("coverage runs the thread selection end to end with diagnostics", async () => {+ const coverage = await callTool("brain_session_grep", {+ operation: "coverage",+ char_budget: 100_000,+ session_id: "session-mcp",+ });+ const turns = coverage.turns as Array<{ turn_id: string }>;+ expect(turns.map((turn) => turn.turn_id)).toEqual(["t1", "t2"]);+ const diagnostics = coverage.diagnostics as Record<string, unknown>;+ expect(diagnostics["facets_detected"]).toBe(1);+ expect(diagnostics["topics_requested"]).toBe(12);+ expect(diagnostics["topics_realized"]).toBe(1);+ expect(diagnostics["chars_used"]).toBeGreaterThan(0);+ expect(diagnostics["dropped_turn_ids"]).toEqual([]);+ });++ test("operation omitted stays byte-identical: hits only, no coverage fields", async () => {+ const grep = await callTool("brain_session_grep", {+ query: "receipt",+ session_id: "session-mcp",+ });+ expect("turns" in grep).toBe(false);+ expect("diagnostics" in grep).toBe(false);+ expect(Array.isArray(grep.hits)).toBe(true);+ });++ test("an unknown operation value is refused by name", async () => {+ const server = new MCPServer({ vault, configPath: null });+ await initialize(server);+ const response = (await server.handleRequest({+ jsonrpc: JSONRPC_VERSION,+ id: 9,+ method: "tools/call",+ params: {+ name: "brain_session_grep",+ arguments: { operation: "widely" },+ },+ })) as { error?: { code: number; message: string } };+ expect(response.error?.code).toBe(-32602);+ expect(response.error?.message).toContain("operation");+ });++ test("entity_key seeds the fan-out and an unknown key is refused by name", async () => {+ appendContinuityRecord(vault, {+ kind: "session_entity_mention",+ createdAt: "2026-05-20T17:00:03.000Z",+ sourceRefs: [{ id: "session-mcp:t1:symbol:ReceiptSearch" }],+ payload: {+ family: "symbol",+ key: "ReceiptSearch",+ session_ref: "session-mcp",+ turn_id: "t1",+ },+ });+ const server = new MCPServer({ vault, configPath: null });+ await initialize(server);+ const call = (args: Record<string, unknown>) =>+ server.handleRequest({+ jsonrpc: JSONRPC_VERSION,+ id: 9,+ method: "tools/call",+ params: { name: "brain_session_grep", arguments: args },+ }) as Promise<{+ error?: { code: number; message: string };+ result?: { content: ReadonlyArray<{ type: string; text: string }> };+ }>;++ const seeded = await call({+ operation: "coverage",+ char_budget: 100_000,+ entity_key: "ReceiptSearch",+ });+ const turns = JSON.parse(seeded.result!.content[0]!.text).turns as Array<{ turn_id: string }>;+ expect(turns.map((turn) => turn.turn_id)).toEqual(["t1", "t2"]);++ const unknown = await call({+ operation: "coverage",+ char_budget: 100_000,+ entity_key: "NoSuchEntity",+ });+ expect(unknown.error?.code).toBe(-32602);+ expect(unknown.error?.message).toContain("NoSuchEntity");++ for (const extra of [+ { since: "2026-05-01" },+ { before: "2026-05-21" },+ { limit: 5 },+ { snippet_chars: 40 },+ ]) {+ const refused = await call({ operation: "coverage", char_budget: 100_000, ...extra });+ expect(refused.error?.code).toBe(-32602);+ }+ });++ test("entity_key accepts the mined-key length (200) and refuses longer", async () => {+ // Mined keys run to MINED_KEY_MAX_LENGTH = 200; a 129-200 character+ // URL or path key must be able to seed coverage over MCP, so the cap+ // matches the miner's, not the old 128.+ const server = new MCPServer({ vault, configPath: null });+ await initialize(server);+ const call = (args: Record<string, unknown>) =>+ server.handleRequest({+ jsonrpc: JSONRPC_VERSION,+ id: 9,+ method: "tools/call",+ params: { name: "brain_session_grep", arguments: args },+ }) as Promise<{ error?: { code: number; message: string } }>;++ const tooLong = await call({+ operation: "coverage",+ char_budget: 1000,+ entity_key: "K".repeat(201),+ });+ expect(tooLong.error?.code).toBe(-32602);+ expect(tooLong.error?.message).toContain("at most 200 characters");++ const atCap = await call({+ operation: "coverage",+ char_budget: 1000,+ entity_key: "K".repeat(200),+ });+ // A 200-character key is a legal mined key: the refusal is about the+ // unknown key, never about its length.+ expect(atCap.error?.code).toBe(-32602);+ expect(atCap.error?.message).toContain("no session_entity_mention row names");+ });++ test("coverage without char_budget is refused", async () => {+ const server = new MCPServer({ vault, configPath: null });+ await initialize(server);+ const response = (await server.handleRequest({+ jsonrpc: JSONRPC_VERSION,+ id: 9,+ method: "tools/call",+ params: {+ name: "brain_session_grep",+ arguments: { operation: "coverage" },+ },+ })) as { error?: { code: number; message: string } };+ expect(response.error?.code).toBe(-32602);+ expect(response.error?.message).toContain("char_budget");+ });++ test("coverage-only arguments are refused by name under the match operation", async () => {+ // The mirror of the refusal matrix above: char_budget and entity_key+ // name the coverage operation's knobs, so the default match operation+ // refuses them instead of silently ignoring them.+ const server = new MCPServer({ vault, configPath: null });+ await initialize(server);+ const call = (args: Record<string, unknown>) =>+ server.handleRequest({+ jsonrpc: JSONRPC_VERSION,+ id: 9,+ method: "tools/call",+ params: { name: "brain_session_grep", arguments: args },+ }) as Promise<{ error?: { code: number; message: string } }>;++ const budget = await call({ query: "receipt", char_budget: 100_000 });+ expect(budget.error?.code).toBe(-32602);+ expect(budget.error?.message).toContain("char_budget is not applicable to operation 'match'");++ const entity = await call({ query: "receipt", entity_key: "ReceiptSearch" });+ expect(entity.error?.code).toBe(-32602);+ expect(entity.error?.message).toContain(+ "entity_key is not applicable to operation 'match'; it seeds the coverage fan-out",+ );+ });++ test("the typed infeasibility error maps to INVALID_PARAMS", async () => {+ const server = new MCPServer({ vault, configPath: null });+ await initialize(server);+ const response = (await server.handleRequest({+ jsonrpc: JSONRPC_VERSION,+ id: 9,+ method: "tools/call",+ params: {+ name: "brain_session_grep",+ arguments: { operation: "coverage", char_budget: 1, session_id: "session-mcp" },+ },+ })) as { error?: { code: number; message: string } };+ expect(response.error?.code).toBe(-32602);+ expect(response.error?.message).toContain("required chars");+ expect(response.error?.message).toContain("floor-weighted");+ });++ test("describe renders the topic report when asked, and only then", async () => {+ const withTopics = await callTool("brain_session_describe", {+ session_id: "session-mcp",+ topics: true,+ });+ const report = withTopics.topic_report as Record<string, unknown>;+ expect(report["facets_detected"]).toBe(1);+ expect(report["topics_requested"]).toBe(12);+ expect(report["topics_realized"]).toBe(1);++ const withoutTopics = await callTool("brain_session_describe", {+ session_id: "session-mcp",+ });+ expect("topic_report" in withoutTopics).toBe(false);+ });+});diff --git a/tests/mcp/surface-error-codes.test.ts b/tests/mcp/surface-error-codes.test.tsindex 77fc460e..d1b52e3c 100644--- a/tests/mcp/surface-error-codes.test.ts+++ b/tests/mcp/surface-error-codes.test.ts@@ -513,6 +513,11 @@ describe("every operation-dispatching tool answers unknown_operation", () => {{ action: BOGUS },"brain_scaffold_stub: 'action' must be one of list, write",],+ [+ "brain_session_grep",+ { operation: BOGUS },+ "brain_session_grep: operation must be 'match' or 'coverage'",+ ],];for (const [tool, args, message] of CASES) {diff --git a/uv.lock b/uv.lockindex 17ecae5a..0eab9bfa 100644--- a/uv.lock+++ b/uv.lock@@ -4,5 +4,5 @@ requires-python = ">=3.11"[[package]]name = "open-second-brain"-version = "1.81.1"+version = "1.82.0"source = { editable = "." }