Skip to content

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

TypeScript

feat: shipped-seam wiring - a per-session recall pool cap, usage-ordered skill offers, seeded bench sampling and OpenCode V2 configs (v1.83.0) (#251)

Serg Eroshee239d323e210
diff --git a/.claude-plugin/plugin.json b/.claude-plugin/plugin.json
index 3d1cca1d..f21da8e0 100644
--- a/.claude-plugin/plugin.json
+++ b/.claude-plugin/plugin.json
@@ -1,6 +1,6 @@
{
"name": "open-second-brain",
- "version": "1.82.0",
+ "version": "1.83.0",
"description": "Plugin-first second brain package for AI agents and humans.",
"author": {
"name": "Open Second Brain contributors"
diff --git a/.codex-plugin/plugin.json b/.codex-plugin/plugin.json
index 22003f3f..a5268dbe 100644
--- a/.codex-plugin/plugin.json
+++ b/.codex-plugin/plugin.json
@@ -1,6 +1,6 @@
{
"name": "open-second-brain",
- "version": "1.82.0",
+ "version": "1.83.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.md
index cc640bb5..d98830d9 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -5,6 +5,21 @@ 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.83.0] - 2026-10-13
+
+Open Second Brain 1.83.0 wires four shipped seams, each opt-in and byte-identical when off: a per-source-session cap on the search candidate pool, usage-ordered skill offers on `skills_attach`, seeded question-type-proportional sampling for the LongMemEval bench suite, and the OpenCode V2 config shape for the opencode install. No new MCP tools, no new continuity record kinds, no new external dependencies.
+
+### Added
+
+- **A per-source-session cap on the search candidate pool.** `search_pool_max_per_session` (`OPEN_SECOND_BRAIN_SEARCH_POOL_MAX_PER_SESSION`, integer, default `0` - off) bounds how many rows one source import session may contribute to the reranker-facing candidate pool. A row's session identity is a non-empty `session_ref` frontmatter value (imported signal notes), else a non-empty `session_id` (handoff notes), read through the same frontmatter cache the pool filters already use; rows without identity, and rows whose frontmatter is unreadable, pass through uncapped. When the cap is active it sits after the relevance floor and before the MMR diversity rerank and joins the pool-width widening, so the cap spreads the window across sessions instead of merely truncating it sooner. The backfill trigger is unchanged - the cap never adds a reason for the second assemble pass, and when that pass runs for its own pre-existing reasons the cap is re-applied over the wider pool, with the reported trail being the final pass's. Drops carry the new retrieval-trail code `source-session-capped-rows` (`detail.dropped` against `detail.cap`), noted once per answer. The knob rides the `search_mmr_lambda` plumbing exactly: parsed in `resolveSearchConfig`, range-validated in `validateResolvedConfig` (a negative value is refused), surfaced as the optional `ResolvedRecallConfig.poolMaxPerSession` spread-omitted at `0` so exact-shape resolved-config assertions keep holding, with a per-query `SearchOptions.poolMaxPerSession` override and both results-affecting folds - the search config fingerprint and the per-query cache key - so a knob change can never serve stale cached rows. A bench `--pin` accepts the knob by name (`{"recall":{"poolMaxPerSession":N}}`). Off (`0` or absent), results and query-cache keys are byte-identical and no frontmatter reads are added; with the knob on, the resolved value folds into the search fingerprint so cached rows can never go stale, while in a vault with no session identity the results alone stay byte-identical at any value.
+- **Usage-ordered skill offers on `skills_attach`.** With `skills_attach_usage_ordering` (`OPEN_SECOND_BRAIN_SKILLS_ATTACH_USAGE_ORDERING`, default off) on, observed `skill_invoked` usage reorders the survivors of the discriminating-term floor by the bounded composite `score * (1 + 0.5 * weight)` - `SKILL_USAGE_ORDERING_MAX_BOOST = 0.5`, `weight` the usage store's decay value in (0, 1] - with equal composites resolving by name ascending, so a skill an agent invokes daily can rise over a slightly hotter one-off while a wide relevance gap stays decisive, the floor is never crossed by weight, and every returned `score` stays the untouched lexical score. The pure `skillUsageWeights(usage, knownNames)` builder joins usage onto discovered names without rewriting any record: exact names join first, plugin-qualified keys (`vendor:name`, the shape the Claude Code `Skill` tool records) join through the longest suffix after a colon that names a discovered skill, keys matching nothing are dropped, and the higher weight wins when several rows join one name. Private records never count: the continuity read drops `private` rows the same way every reader does. The tool derives usage exactly once per attach call only when the flag is on and feeds the same weight map to both build paths, so the deterministic and decision-model offers stay coherent; the tool description names the knob in one clause. Flag off - or on, in a vault with no usage records - the offer is byte-identical to the lexical order.
+- **Seeded LongMemEval sampling.** `o2b brain bench memory --suite longmemeval --sample-seed <value> --sample-cap <n>` scores a deterministic, question-type-proportional subset of the dataset instead of running it wholesale. The flags are a pair (either alone is refused by name), the cap must be a positive integer (otherwise refused naming the value), and both together require a suite whose registration declares the new `sampling` capability - longmemeval is the only one - otherwise refused naming the suite, so the flags can never be silently ignored by a loader that cannot honor them. The pure sampler (`src/core/bench/longmemeval-sample.ts`) excludes abstention entries first (both spellings; their count still lands in `abstention_excluded`), stratifies the survivors by their present `question_type` values sorted ascending, apportions the cap across strata by largest-remainder (Hamilton) apportionment clamped to the population with fractional ties broken by stratum name, and draws within a stratum by a seeded Fisher-Yates over its own mulberry32 PRNG keyed by `sha256Hex(seed)` - no `Math.random`, no wall clock - over entries sorted by `q_id`, so dataset file order cannot change the subset; the selection re-sorts by `q_id`, and a population of zero after abstention exclusion raises the named `LongMemEvalSampleError`. Sampling happens before conversion, so a sampled run materializes fixture notes and continuity records only for the questions it scores; the receipt gains `sample_population`, `sample_selected` and the per-stratum `sample_strata` beside `abstention_excluded`, and the report line gains `sample_selected N` only on a sampled run. The seed and cap fold into `benchRunIdentityHash` spread-omitted: run ids of runs without sampling are byte-stable (the committed pins hold unchanged), two runs differing only in seed or in cap get different ids even when the sampled fixture would be identical, and a resumed run whose sampling options changed fails the identity guard by name. Without the flags the loader path is byte-identical, and the frozen locomo and sample fixtures stay untouched.
+- **The opencode install learns the OpenCode V2 config shape.** The adapter now detects, through one shared function used by apply, verify, detect and plan, whether the config carries the native V2 `mcp.servers` object - and registers there - or keeps the legacy top-level `mcp` key every earlier release wrote. When only `opencode.jsonc` exists it is the resolved config path, and a vendored minimal JSONC editor (`src/core/install/jsonc.ts`, token-offset splices, no new dependency) edits comment-bearing files so comments and formatting survive byte for byte outside the changed entry; duplicate top-level keys are a named `JsoncEditError` refusal, and a BOM is stripped on read and restored on write. An existing healthy top-level registration is never migrated when `mcp.servers` appears (V2 hosts keep reading a legacy declaration, so migration would churn installs for zero benefit); the manifest records the key actually written (`mcp.servers.<entry>` or `mcp.<entry>`), and uninstall removes exactly those keys under either shape. When the host adds `mcp.servers` to a config the adapter previously owned, the first `--check` reports drift once and the first re-apply is refused through the user-modified-block guard; a forced re-apply (`--force`) registers at the native path and cleans the shadowed legacy copies of its own two keys, never user keys. V1-shaped plain-JSON configs keep the previous write path byte for byte, and the doctor's registered-command probe learned the nested `mcp.servers` key so a healthy V2 install passes `o2b doctor`.
+
+### Changed
+
+- **Docs:** `docs/cli-reference.md` gains the `search_pool_max_per_session` row in the recall-quality config table, the `source-session-capped-rows` row in the retrieval-trail vocabulary, a per-source-session pool cap section, and the bench sampling flags with their selection semantics and the resume-guard consequence; `docs/how-it-works.md` covers the cap in the recall-layers ranking paragraph; `docs/mcp.md` adds `skills_attach_usage_ordering` to the `skills_attach` opt-in list with the name-normalization rule, the private-records note and the per-call cost; `docs/observability.md` documents the sampling flags, the stratified selection, the receipt fields and the identity fold; `install/opencode.md` documents the V2 shape, the `.jsonc` path, shape-aware uninstall and the one-time drift; `docs/updating.md` gains the 1.83.0 upgrade note for that drift, following the 1.50.0 convention; the README names the release and extends the search capability (mirrored into `plugins/codex/README.md` by the mirror sync).
+
## [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.
@@ -8482,6 +8497,7 @@ Hermes / Claude Code / Codex / OpenClaw configurations do not change.
- Sandbox vault and plugin manifest fixtures for tests.
- GitHub release workflow for tag-based and manually dispatched releases.
+[1.83.0]: https://github.com/itechmeat/open-second-brain/compare/v1.82.0...v1.83.0
[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
diff --git a/README.md b/README.md
index 9f228d2c..806bef90 100644
--- a/README.md
+++ b/README.md
@@ -98,7 +98,7 @@ 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; 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).
+- **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; and an opt-in per-source-session cap (`search_pool_max_per_session`, default off) keeps one long imported session from filling the candidate window, so diversity spreads across sessions: [search CLI](docs/cli-reference.md#search), [iterative recall](docs/cli-reference.md#iterative-recall-since-v1820), [pool cap](docs/cli-reference.md#the-per-source-session-pool-cap-since-v1830), [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).
@@ -123,7 +123,7 @@ The full router with readiness criteria is [`install.md`](install.md); native Wi
## What is new
-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).
+1.83.0 wires four shipped seams, each an opt-in that is byte-identical when off. Search can cap how many rows one source import session holds in the reranker-facing candidate window (`search_pool_max_per_session` / `OPEN_SECOND_BRAIN_SEARCH_POOL_MAX_PER_SESSION`, default `0`): the cap sits after the relevance floor and before the MMR diversity rerank and widens the pool rather than truncating it, so a long imported session stops crowding out everything else, while a vault without session frontmatter never sees a difference. `skills_attach` can order its offers by observed invocation usage (`skills_attach_usage_ordering` / `OPEN_SECOND_BRAIN_SKILLS_ATTACH_USAGE_ORDERING`, default off): a bounded composite, `score * (1 + 0.5 * weight)`, lifts a daily skill over a slightly hotter one-off without ever crossing the discriminating-term floor; plugin-qualified invocation names join discovered skills through a deterministic longest-suffix rule, private records never count, and the returned scores stay lexical. `o2b brain bench memory --suite longmemeval` accepts `--sample-seed` plus `--sample-cap` to score a seeded, question-type-proportional subset of the dataset instead of the whole file - deterministic given the seed, immune to dataset file order, receipt-reported (`sample_population` / `sample_selected` / `sample_strata`), and folded into the run identity so a resumed run whose sampling options changed fails the identity guard by name. The opencode install learns OpenCode V2's native `mcp.servers` config shape and `.jsonc` config files: comment-bearing files are edited byte-preserving, the legacy top-level shape stays untouched, and a one-time drift after the host adds `mcp.servers` is documented with its fix. Every release is described in the [CHANGELOG](CHANGELOG.md).
## Documentation
diff --git a/docs/brainstorm/wiring-shipped-seams/cli-output/consultant.md b/docs/brainstorm/wiring-shipped-seams/cli-output/consultant.md
new file mode 100644
index 00000000..860d8f05
--- /dev/null
+++ b/docs/brainstorm/wiring-shipped-seams/cli-output/consultant.md
@@ -0,0 +1,32 @@
+### Variant 1: Four parallel disjoint lanes with one bench contract commit first
+- **Approach**: Run the four residues as four file-disjoint lanes. The bench sampler lane lands a contract commit first - CLI flags with paired-flag refusal, the widened loader signature with an options parameter, and the sampling capability declaration - because the pool-cap lane holds the wave's only append-only right on a bench file: one knob name in the bench pin's recall key list, exercisable only after that commit. The cap, skill-ordering and OpenCode lanes start immediately over files nothing else touches; each lane's pure module (cap grouper, usage map builder, stratified sampler, JSONC editor) is written and tested in isolation from its first commit. One integrator pass closes docs, census reconciliation, the CHANGELOG entry and the version bump.
+- **Trade-offs**:
+ - Maximal wall-clock parallelism: three of four lanes share no file with anything and never wait.
+ - Exactly one declared cross-lane dependency (the pin key append waits on the bench contract commit), so coordination cost is one paragraph of contract.
+ - The bench gains its measurement instrument early: the seeded sampler is the tool the cap's measured flip-rule decision needs, inside the same pull request.
+ - Cost: the contract must pin file ownership precisely and the bench lane must commit its contract before the cap lane finishes.
+- **Complexity**: medium
+- **Risk**: low
+
+### Variant 2: Serial stack in risk order
+- **Approach**: Land the four residues one at a time on the shared branch, ordered so each is fully green before the next starts: skill usage ordering (smallest, single ranking point), per-session pool cap, seeded sampler, OpenCode adapter (largest, least mechanical). No lane structure, no cross-lane contract; every change is built against a fully settled tree.
+- **Trade-offs**:
+ - Zero coordination cost and the simplest possible audit trail: one clean commit series per feature.
+ - Every feature is verified against the previous feature's final state, so no append-only splits or dependency waits are needed.
+ - Four sequential build-and-stabilize cycles stretch the release badly; the cap, skill and OpenCode lanes share no files yet serialize unnecessarily.
+ - The measurement instrument arrives third, so the cap lands unmeasured and its flip-rule decision waits or ships on assertion.
+- **Complexity**: small
+- **Risk**: medium
+
+### Variant 3: Two stacked half-waves - retrieval and its measurement, then the host adapter
+- **Approach**: Split the wave into two halves inside one pull request. Half one lands the three retrieval-side residues in parallel (pool cap, skill usage ordering, seeded sampler) with the bench contract commit inside it. Half two lands the OpenCode V2 adapter after the tree settles, keeping the least mechanical, most environment-dependent work isolated from the retrieval changes.
+- **Trade-offs**:
+ - The adapter's review surface is fully separated from the ranking changes, which are the drift-sensitive ones.
+ - Each half is independently verifiable and revertible.
+ - The OpenCode lane shares no files with the retrieval lanes, so isolating it buys review clarity at the price of an artificial serialization point.
+ - The integrator faces two merge windows instead of one, doubling census and docs reconciliation work.
+- **Complexity**: medium
+- **Risk**: medium
+
+### Recommended: Variant 1
+**Rationale**: The four residues are file-disjoint except one genuine seam - the cap's bench pin entry needs the bench verb file the sampler 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, and the sampler lands early enough to measure the cap inside the same pull request. This is the same substrate-then-lanes shape the previous recall-quality wave executed successfully on this repository, so the ownership mechanics, dependency-wait rule and census arbitration are proven here.
diff --git a/docs/brainstorm/wiring-shipped-seams/cli-output/prompt.md b/docs/brainstorm/wiring-shipped-seams/cli-output/prompt.md
new file mode 100644
index 00000000..b9846960
--- /dev/null
+++ b/docs/brainstorm/wiring-shipped-seams/cli-output/prompt.md
@@ -0,0 +1,94 @@
+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/wiring-shipped-seams 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 (v1.82.0) and corrected or refuted the card premises; the "residue" line in each card is the corrected, agreed scope.
+
+## Card t_bb6ce095 (priority 4): Per-session candidate-pool cap feeding the reranker
+
+Source: garrytan/gbrain v0.60.199.0.
+
+What upstream ships: an opt-in retrieval knob that widens the candidate pool fed to the reranker and caps it at one row per conversation session, so several chunks of one session can no longer occupy all reranker slots. Upstream measured +3.5 strict recall at 10 with the knob on and still shipped it off by default.
+
+Recon verdict (premise corrected): the diversity rerank really is similarity-only MMR over the ranked pool (mmrRerank, src/core/search/mmr.ts:67; assembled at src/core/search/pipeline/assemble.ts:341), and no per-source cap exists anywhere on the reranker-facing pool. But candidate rows carry NO session identity (BrainSearchResult, src/core/search/search-result.ts:112-193; no session column in the schema), and the card's session-scope.ts citation is a naming trap - that module scopes the caller's current conversation. Source import sessions are recoverable per row only through frontmatter: `session_ref` on imported signal notes (src/core/brain/signal.ts:521-522), `session_id`/`scope` on handoff notes (src/core/brain/handoff.ts:143-152). The assemble stage already carries a frontmatter cache on AssemblyInput (assemble.ts:81, consumed at :205-209) with one-read-per-path semantics (readCachedFrontmatterEntry, src/core/search/result-filters.ts:60). Pool width lives in assemble.ts:211-257 (POOL_LIMIT_MULTIPLIER 3, POOL_MIN_WIDTH 30, widening disjunction over mmr/traversal/cross-encoder), the relevance floor at :330-338, MMR at :339-342, relevance rerank at :346-348, a backfill re-assemble at :357-393 whose wideCap can never exceed the already-widened rankLimit, and degradation notes at :404-430 with codes in src/core/search/retrieval-trail.ts:159-189. The exact config plumbing precedent is search_mmr_lambda: DEFAULTS (src/core/search/index.ts:276), envOrConfig parse (:1182-1186), validateResolvedConfig (:629), ResolvedRecallConfig.mmrLambda (src/core/search/types.ts:1542), per-query SearchOptions.mmrLambda (:919), cache fingerprint (src/core/search/pipeline/cache-slot.ts:279-300), per-query cache key (src/core/search/query-cache.ts:124), bench pin keys (BENCH_PIN_NESTED_KEYS.recall, src/cli/brain/verbs/bench.ts:176+), docs rows (docs/cli-reference.md:2388, docs/how-it-works.md:1234). Optional resolved fields use spread-omission so exact-shape assertions keep holding (index.ts:1175-1178).
+
+Residue: an opt-in per-source-session cap on the reranker-facing candidate pool, grouped through the frontmatter the assemble stage already carries (session_ref first, session_id second, no identity passes uncapped, unreadable frontmatter passes uncapped), placed after the relevance floor and before the diversity rerank, widening the pool via the existing Math.max composition when active, counting drops under a new RETRIEVAL_DEGRADATION code, folded into the search config plumbing exactly like search_mmr_lambda, off by default with a byte-identical-off proof.
+
+## Card t_5d1ec8a8 (priority 4): Rank offered skills by observed usage activity
+
+Source: Tencent/TencentDB-Agent-Memory v2.0.2.
+
+What upstream ships: the skill list is sorted by usage activity so frequently used skills surface first.
+
+Recon verdict (premise clean): no usage signal reaches the offer ranking. rankSkillCandidates (src/core/surface/skill-attach.ts:119-143) scores descriptors with BM25, applies the discriminating-term floor as a filter ("The floor filters, it never reorders: ranking stays the scorer's", line 126), slices to limit; the module docblock pins "the same query and skill set always produce the same block" (lines 4-8). It is the single ranking point for both the default path and the decision-model shortlist (buildSkillAttachmentWithDecision, src/core/surface/skill-attach-decision.ts:243+, shortlist at :257, options inherited via DecisionSkillAttachmentOptions :117). The per-turn caller is toolSkillsAttach (src/mcp/skill-tools.ts:164-187). The usage store already ships: deriveSkillUsage (src/core/brain/skill-usage.ts:105-149) returns SkillUsage with invocationCount and weight (the shared pure decay curve, weight in (0,1], nowMs injectable, default Date.now()); records are keyed on the raw payload["skill"] string, and for the Claude Code Skill tool that string is plugin-qualified ("open-second-brain:skill-name") which never joins to the discovered bare name - a normalization rule must be decided and documented. The config precedent is skills_attach_triggers: resolveConfigFlag (src/core/config.ts:779-786), resolver (:795-801), option on BuildSkillAttachmentOptions, pass-through at the tool, docs/mcp.md opt-in key list (:1218-1227), CHANGELOG. The repo's import-cycle ratchet counts `import type` as an edge and core/brain/skill-usage.ts already imports from core/surface, so core/surface must not import back.
+
+Residue: a usage-derived weight folded into rankSkillCandidates as the single ranking point for both paths, gated by a default-off config flag beside the other skill gates, with a documented normalization rule for plugin-qualified invocation names, a deterministic composite score with a name tie-break, and the documented ranking invariants at skill-attach.ts amended in the same change.
+
+## Card t_4501c662 (priority 4): Seeded proportional LongMemEval sampling for the bench harness
+
+Source: Signet-AI/signetai v0.237.0.
+
+What upstream ships: a seeded, proportionally stratified LongMemEval question sampler - every run draws the same category-balanced question subset from a seed, so retrieval-quality comparisons measure the retrieval change and not the question mix.
+
+Recon verdict (premise corrected): the LongMemEval lane SHIPPED in v1.82.0 (src/core/bench/longmemeval.ts, 697 lines, registered as --suite longmemeval with an embeddings capability). The half that holds: no sampler of any kind exists under src/core/bench - every lane runs its fixture wholesale. Sampling must select PRE-conversion on LongMemEvalEntry: the official six question types survive only on the parsed entry (QUESTION_TYPE_TO_CATEGORY at longmemeval.ts:188-198 collapses the three single-session-* types into one BenchCategory post-conversion), and abstention entries (explicit type or `_abs` q_id suffix, isLongMemEvalAbstention :163-170) are dropped at conversion with a recorded count. The loader chain is parseLongMemEvalDataset (:220-249) then longMemEvalToBenchFixture (:559-645); loadLongMemEvalFixture (:648-658) is the registry entry point and BenchSuiteRegistration.loader takes only fixturePath today (src/core/bench/types.ts:194). Run identity is benchRunIdentityHash (src/core/bench/run-store.ts:49-61) = sha256(canonicalJson({fixture_hash, knobs, recall_floor})), the resume guard refuses a mismatch by name (:117-136); the recallFloor trace is the pattern to follow end to end (bench.ts:279-288 validator, :338-352 threading; phases.ts:99-111 options, :214-221 refusal, :223-234 identity fold; checkpoint fields types.ts:360-374). Determinism assets: no Math.random anywhere in the bench, canonicalJson + sha256Hex in src/core/integrity/digest.ts, sorted outputs everywhere; no general PRNG exists, so the sampler brings its own small deterministic generator. Committed sample fixtures are tiny and CI-pinned - sampling tests must build synthetic populations through the entry() helper (tests/core/bench/longmemeval.test.ts:38-54).
+
+Residue: seeded proportional stratified sampling over the six official question types, applied to dataset entries PRE-conversion behind new CLI flags following the --recall-floor trace, with the sampling options folded into benchRunIdentityHash and the checkpoint, an own deterministic PRNG (no Math.random, no wall clock), sorted inputs so dataset file order cannot change the subset, receipt fields mirroring abstention_excluded, and byte-identical behavior when the flags are absent.
+
+## Card t_68ae8a53 (priority 4): Teach the OpenCode install adapter and plugin the V2 config shape
+
+Source: plur-ai/plur v0.21.4.
+
+What upstream ships: the host plugin loads in OpenCode V2 - init understands the V2 plugins config object and the mcp.servers key while preserving JSONC comments, disabled choices and custom MCP entries. The V1 adapter stays supported.
+
+Recon verdict (premise corrected): the bundled plugin already supports V2 at the runtime-hook API (setup() with per-capability feature detection, plugins/opencode/open-second-brain.ts) and reads and writes no config - the card's "study how the plugin reads/writes the config" has no referent, and the plugin needs no work. The real gap: the adapter is V1-only (src/core/install/adapters/opencode.ts:3-16 docblock, configPath hard-wired to opencode.json :44-46, plain-JSON legacy migration :72-95) and the shared body createJsonMcpAdapter (src/core/install/adapters/_json-mcp.ts) has a single top-level key notion everywhere (:181, :231) with plain JSON.parse/stringify round-trips (json-merge.ts:44-102) that would strip JSONC comments; the repo has NO jsonc dependency (only proper-lockfile in package.json). Upstream V2 behavior (plur v0.21.4 read for recon): native `mcp.servers` map wins when it exists and (contains the entry, or top-level mcp lacks it) - "native declarations win, but an existing legacy declaration must not be shadowed"; `opencode.jsonc` targeted when it is the only file present; comments and trailing commas survive via token-offset edits, never re-serialization; ambiguous JSONC (duplicate keys) refused unchanged; entry shape {type, command: [argv], environment?, enabled} unchanged. The doctor's registered-command probe (src/core/doctor-readiness.ts:723-777) re-reads the config with JSON_MCP_TOP_LEVEL_KEYS = ["mcpServers", "mcp"] (:641) independent of the adapter - a nested registration would report "skipped" unless the list learns the dotted path. Verify is reconstruction-based and must stay symmetric with apply (_json-mcp.ts:92-120 documents the drift-against-itself failure). The user-modified-block mtime guard (:328-351) bites when a shape change rewrites an owned file; the 1.50.0 upgrade-notes convention in docs/updating.md is the model for the one-time drift note. The host-facts census pins 10 targets (tests/core/architecture/host-facts-census.test.ts) - no target joins, so the row grows nothing; V1/V2 is a property of the on-disk file.
+
+Residue: the adapter learns the V2 shape - detection by file shape shared by apply and verify, `.jsonc` path support, comment-preserving token-offset edits through a vendored minimal JSONC editor (a new dependency is a design decision to make explicitly; prefer the smallest honest option), the doctor probe taught the nested key, V1 installs untouched.
+
+# 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. Every opt-in surface ships default off with a byte-identical-off regression proof; failures are typed named errors, never silent fallbacks; no hardcoded values that belong in constants; the tool census is pinned; no new external dependencies without an explicit design decision.
+
+Recent commits:
+
+44a8ccaf feat: recall quality - an iterative recall loop, coverage-first session recall and a measured surfacing key (v1.82.0) (#250)
+259e4b70 fix(snapshot): decode readdir buffer entries as UTF-8 so exclusions match (v1.81.1) (#243)
+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)
+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)
+
+Related files:
+
+- Search pipeline: src/core/search/pipeline/assemble.ts, src/core/search/mmr.ts, src/core/search/types.ts, src/core/search/index.ts, src/core/search/retrieval-trail.ts, src/core/search/result-filters.ts, src/core/search/pipeline/cache-slot.ts, src/core/search/query-cache.ts
+- Skills: src/core/surface/skill-attach.ts, src/core/surface/skill-attach-decision.ts, src/core/brain/skill-usage.ts, src/core/config.ts, src/mcp/skill-tools.ts
+- Bench: src/core/bench/longmemeval.ts, src/core/bench/types.ts, src/core/bench/phases.ts, src/core/bench/run-store.ts, src/cli/brain/verbs/bench.ts
+- Install: src/core/install/adapters/opencode.ts, src/core/install/adapters/_json-mcp.ts, src/core/install/json-merge.ts, src/core/doctor-readiness.ts, src/core/runtime/host-facts.ts
+
+Conventions:
+
+- Mode-off byte-identical invariant: every opt-in feature leaves outcomes byte-identical when off, with a regression proof.
+- Deterministic core: sorted inputs, named constants, no Math.random or wall clock in selection logic; clocks injectable.
+- Typed named refusals everywhere; a knob that would silently do nothing is refused by name instead.
+- Censuses and ratchets (tool ceiling, continuity readers, write sites, host facts, import cycles) move only in the commit that grows their inputs.
+- Docs: full product name in public prose, no exclamation marks; CHANGELOG is Keep-a-Changelog with one descriptive entry per release.
+
+# Required output format
+
+Produce exactly 3 distinct architectural variants. 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/wiring-shipped-seams/design.md b/docs/brainstorm/wiring-shipped-seams/design.md
new file mode 100644
index 00000000..c7c79775
--- /dev/null
+++ b/docs/brainstorm/wiring-shipped-seams/design.md
@@ -0,0 +1,120 @@
+# Wiring shipped seams - per-session pool cap, usage-ordered skill offers, seeded LongMemEval sampling, and the OpenCode V2 config shape
+
+**Status:** draft
+**Author:** feature-release-playbook orchestrator
+**Audience:** implementation
+
+## Problem statement
+
+Four verified cards in this wave share one defect family: the last unblocked wiring step on a surface the codebase already ships. The recall pipeline's diversity stage is similarity-based MMR over the ranked pool, so near-duplicate chunks collapse while several distinct chunks of one long imported session can still fill the whole reranker-facing window; the per-turn skill offer is ordered by lexical score alone even though a usage store with invocation counts and decay weights already ships; the bench harness runs every fixture wholesale even though the LongMemEval lane shipped in v1.82.0, so run-to-run score movement conflates retrieval changes with question-mix noise; and the OpenCode install adapter writes only the V1 top-level `mcp` key with a plain JSON round-trip that would strip JSONC comments, while OpenCode V2 hosts read the native `mcp.servers` shape and `.jsonc` config files. Every residue is an extension of a proven in-tree subsystem, verified anchor by anchor by the recon node against this exact worktree.
+
+## Premise verification record
+
+The recon node verified every card premise against the live tree before this brainstorm. Corrections to carry into implementation:
+
+- t_bb6ce095: candidate rows carry NO session identity. `BrainSearchResult` (src/core/search/search-result.ts:112-193) has no session field and the chunk schema has none; the card's "one row per conversation session" is implementable only through frontmatter identity: `session_ref` on imported signal notes (src/core/brain/signal.ts:521-522) and `session_id`/`scope` on handoff notes (src/core/brain/handoff.ts:143-152). The card's session-scope.ts citation is a naming trap: that module scopes the caller's current conversation, not source import sessions. The knob and its degradation code are named for SOURCE sessions to keep the two apart.
+- t_5d1ec8a8: premise clean. `deriveSkillUsage` (src/core/brain/skill-usage.ts:105) already returns an invocation count and a decay weight, and `rankSkillCandidates` (src/core/surface/skill-attach.ts:119) takes only query, skills and includeTriggers. One recon-added constraint: for the Claude Code `Skill` tool the captured `payload["skill"]` is the plugin-qualified command string (`open-second-brain:skill-name`), which never joins to the discovered bare name; the design normalizes at map-build time (Design decision 8).
+- t_4501c662: the card's evidence is half stale - the LongMemEval lane SHIPPED in v1.82.0 (src/core/bench/longmemeval.ts, registered as `--suite longmemeval`). The half that holds: no sampler of any kind exists under src/core/bench; every lane runs its fixture wholesale. Additional recon constraint: the official six question types survive only on the parsed entry; after conversion the three `single-session-*` types collapse into one `BenchCategory`, so a type-proportional sampler must select PRE-conversion.
+- t_68ae8a53: the bundled plugin already supports OpenCode V2 at the runtime-hook API (`setup()` with per-capability feature detection in plugins/opencode/open-second-brain.ts) and reads and writes no config - the card's instruction to study the plugin's config handling has no referent. The real gap is the adapter (V1-only, plain-JSON re-serialization), the doctor key list (doctor-readiness.ts:641, independent of the adapter), and the absence of any JSONC handling in the repo (no jsonc dependency in package.json or bun.lock; src/core/install/ has no JSONC module). Host-facts row anchors are 647-661, not the card's 647-659.
+
+## Scope
+
+- t_bb6ce095 (lane 1) - the corrected residue: an opt-in per-source-session cap on the reranker-facing candidate pool, grouped through the frontmatter cache the assemble stage already carries (`session_ref` first, `session_id` second, no identity passes through uncapped), placed after the relevance floor and before the diversity rerank, joining the existing pool-width widening when active, dropping rows counted under a new `RETRIEVAL_DEGRADATION` code, folded into the search config plumbing exactly like `search_mmr_lambda` (DEFAULTS, envOrConfig, validateResolvedConfig, ResolvedRecallConfig, cache and query-key fingerprints, bench pin key list, docs rows), off by default with a byte-identical-off proof.
+- t_5d1ec8a8 (lane 2) - the corrected residue: a usage-derived weight folded into `rankSkillCandidates` as the single ranking point for both the default and the decision-model path, gated by a default-off config flag beside the other skill gates, with a documented normalization rule for plugin-qualified invocation names, a deterministic composite score with a name tie-break, and the documented ranking invariants at skill-attach.ts amended in the same change.
+- t_4501c662 (lane 3) - the corrected residue: seeded proportional stratified sampling over the six official LongMemEval question types, applied to dataset entries PRE-conversion behind new CLI flags following the `--recall-floor` trace, with the sampling options folded into `benchRunIdentityHash` and the checkpoint, an own deterministic PRNG (no Math.random, no wall clock), sorted inputs so dataset file order cannot change the subset, receipt fields mirroring `abstention_excluded`, and byte-identical behavior when the flags are absent.
+- t_68ae8a53 (lane 4) - the corrected residue: the OpenCode adapter learns the V2 shape - detection by file shape (`mcp.servers` present means the native key), `.jsonc` config path support, comment-preserving token-offset edits through a vendored minimal JSONC editor (the repo has no JSONC dependency; the design decision is explicit below), verify reconstruction kept symmetric with apply, the doctor registered-command probe taught the nested key, V1 installs untouched.
+- Integration lane - docs pages (cli-reference, how-it-works, mcp, observability, install/opencode, updating, README plus the plugin mirror sync), CHANGELOG entry, the minor version bump via scripts/sync-version.ts inside this pull request, census reconciliation and the full local gate run.
+
+## Out of scope
+
+- A generic sampler for the locomo or surfacing-replay suites: type-proportional stratification is LongMemEval-only (locomo carries a free-text category hint mapped to the four collapsed BenchCategory values, weaker than the card's ask). The loader options shape leaves room for a later generic cap.
+- Explicit operator-tuned stratum proportions: proportional-to-population is the card's ask; a proportions override is a tuning surface nobody has asked to tune.
+- A bounded trailing window for `deriveSkillUsage`: the read model already decays weights; windowing changes which records establish the decay baseline and is a semantic change of its own. The knob derives once per attach call only when on; cost is documented.
+- Usage ordering for `skills_attach` tool help beyond a one-line mention, and any README skills section (README carries no skills_attach mention today; the triggers knob's docs footprint was docs/mcp.md only).
+- A V2 plugins-config-object registration for the bundled plugin: the plugin is a local file installed by file-drop, the V2 config object targets package-name plugins (bare name, version-pinned spec, or options tuple), and directory plugin loading is what V2's removal directives (`-name`, `-glob`) presuppose. The plugin keeps its no-imports rule and spool-only writes.
+- Automatic migration of an existing healthy top-level `mcp` entry into `mcp.servers`: V2 hosts keep reading a legacy declaration (upstream's own rule: native declarations win, an existing legacy declaration must not be shadowed), so migration would churn every existing install and trip the user-modified-block guard for zero benefit.
+- Preserving an operator's explicit `enabled: false` as non-drift: today an explicit disable is drift by design ("an operator toggling the server off shows up as drift instead of silently staying off after re-apply"); that contract stays, on both shapes, this wave.
+- A symlink-safe atomic write (realpathSync before rename): a pre-existing V1-path hole, recorded under risks, not this wave.
+- Version bump outside the pull request, new MCP tools (the tool census is pinned), new continuity record kinds, and any new external dependency.
+
+## Chosen approach
+
+Variant 1: four parallel file-disjoint lanes with one bench contract commit first (consultant recommendation, orchestrator agrees; full text of all variants and the decision record in `variants.md`).
+
+Lane 3 (bench sampler) lands its contract commit first - CLI flags, loader options widening, capability declaration - because lane 1 holds the wave's only append-only right on a lane-3 file: the new knob name in `BENCH_PIN_NESTED_KEYS.recall` in src/cli/brain/verbs/bench.ts, exercisable only after that commit. Lanes 1 (per-session pool cap), 2 (skill usage ordering) and 4 (OpenCode V2 adapter) then run concurrently over fully disjoint file sets with no other declared dependency; each lane's pure module is testable in isolation from its first commit. One integrator pass closes census reconciliation, docs, the CHANGELOG entry, the version bump and the full local gate run in CI order.
+
+## Design decisions
+
+1. **t_bb6ce095 - the cap groups by SOURCE import-session identity read through the existing frontmatter cache.** Candidate rows carry no session id, so the cap derives one per row at assemble time: `readCachedFrontmatterEntry` over the `FilterContext` the assemble closure already builds, giving one parsed-frontmatter read per path per search. Group key: a non-empty string `session_ref`, else a non-empty string `session_id` (handoff notes), else null - rows without identity, and rows whose frontmatter is unreadable, pass through uncapped, mirroring the `duplicateKey` null handling. Ordinary vault notes are therefore untouched by construction; in a vault of ordinary notes the knob is a measured no-op, and the docs say so.
+2. **t_bb6ce095 - placement and widening: floor, then cap, then diversity.** The cap phase sits after the relevance floor and before `mmrRerank` and `rerankByRelevance` (assemble.ts:330-348), so the diversity pass selects across sessions rather than inside one and the floor never wastes cap slots on rows it would drop. When the cap is active (value > 0), it joins the existing `Math.max` pool-width composition by extending the widening disjunction (assemble.ts:249-257) - a wider pool is required or the cap merely truncates sooner. The backfill trigger is deliberately NOT extended: the cap adds no trigger condition of its own. Reviewed against the shipped pipeline, for plain queries the backfill's `wideCap` (`Math.max(limit * 5, 50)`, semantic-phase.ts:59-61) exceeds the cap-widened `rankLimit` (`Math.max(limit, limit * 3, 30, topK)`; `semanticPoolSize` joins only through `baseRankLimit`, which plain queries do not use), so a backfill that fires for its own pre-existing reasons (visibility drops, merges leaving an under-filled window) re-runs with the cap active over the wider pool: the cap is re-applied in the second pass, the window can only grow, and `noteAssemblyNarrowings` reports the final pass. Folding `semanticPoolSize(limit)` into the widened composition to keep the cap single-pass would change the backfill's width for every query - a behavior change beyond this wave's mandate - so the honest contract is: the cap never adds a retry reason, and a pre-existing backfill re-runs the cap. (Review revision, pr-251 M2-M4/L4: the cap now groups frontmatter-less rows by path and runs AFTER the caller's filters - which moves it past the diversity rerank, so "floor, then cap, then diversity" above no longer holds and the caller's scopes can never be starved by cap slots spent on rows they would drop - and the backfill trigger now DOES include the cap's own under-filled drops, with one re-widen at `limit * (widestGroup + 1)`; a value at or above the query's resolved pool width is treated as off, the fingerprint still folding.)
+3. **t_bb6ce095 - the knob rides the search_mmr_lambda plumbing exactly.** `search_pool_max_per_session` / `OPEN_SECOND_BRAIN_SEARCH_POOL_MAX_PER_SESSION`, integer, default 0 (off), parsed in `resolveSearchConfig` beside the mmrLambda parse, validated in `validateResolvedConfig`, surfaced as an OPTIONAL `ResolvedRecallConfig.poolMaxPerSession` field spread-omitted when 0 (the `relationalRerankPin` pattern at index.ts:1175-1178, so exact-shape assertions on the resolved config keep holding), with a per-query `SearchOptions.poolMaxPerSession` override following the mmrLambda pattern. Results-affecting folds are mandatory: `configFingerprint` gains the resolved value (cache-slot.ts) and the per-query cache key gains the override (query-cache.ts) - a knob missing from either serves stale cached rows. `BENCH_PIN_NESTED_KEYS.recall` gains the knob name or a `--pin '{"recall":{...}}'` naming it is refused. Off means the phase never runs and no frontmatter reads are added: byte-identical, and free.
+4. **t_bb6ce095 - drops are named, once.** A new `RETRIEVAL_DEGRADATION` code `source-session-capped-rows` (detail.dropped, detail.cap) joins retrieval-trail.ts beside `relevance-floor-dropped-rows`, noted once in `noteAssemblyNarrowings` - the name says SOURCE session so the degradation trail never conflates the cap with the caller's session focus. The assemble closure can run twice only via the backfill; the cap never adds a trigger (decision 2), and `noteAssemblyNarrowings` is called once per answer on the final assembly, so the note stays once per answer even when a pre-existing backfill re-runs the cap.
+5. **t_5d1ec8a8 - one ranking point, a multiplicative composite, lexical scores preserved as primary.** `BuildSkillAttachmentOptions` gains `usageWeight?: ReadonlyMap<string, number>` (skill name to decay weight); the map is absent when the knob is off, so both `buildSkillAttachment` and the decision-model shortlist inherit the input unchanged through `DecisionSkillAttachmentOptions`. Inside `rankSkillCandidates`, after the discriminating-term floor and before the slice, when a usage map is present the order becomes the composite `score * (1 + SKILL_USAGE_ORDERING_MAX_BOOST * weight)` descending, then name ascending - with `SKILL_USAGE_ORDERING_MAX_BOOST = 0.5` a named module constant and weight the `SkillUsage.weight` decay value in (0, 1]. A maximally-used skill earns at most +50 percent on its lexical score, so usage can lift a daily skill over a slightly hotter one-off but can never rescue a non-matching skill past the floor. The returned `score` field stays the lexical score; the OFF path returns the scorer's order untouched (byte-identical). The documented invariants at skill-attach.ts lines 4-8 and 126 are amended in the same commit to state the gated contract: absent usage input, ranking stays the scorer's.
+6. **t_5d1ec8a8 - the flag rides the skills_attach_triggers plumbing exactly.** `skills_attach_usage_ordering` / `OPEN_SECOND_BRAIN_SKILLS_ATTACH_USAGE_ORDERING`, default off, via `resolveConfigFlag` beside the other skill gates in src/core/config.ts, resolved once in `toolSkillsAttach` and passed to both build paths. When on, the tool layer derives usage exactly once per attach call with an explicit `nowMs: Date.now()` (one clock read per call; `decayWeight` itself is pure, tests pin nowMs as skill-usage.test.ts already does), and builds the map through a new pure helper in src/core/brain/skill-usage.ts so the continuity reader set is unchanged (reader-census stays green).
+7. **t_5d1ec8a8 - the type is a local structural input, not a cross-layer import.** skill-attach.ts declares the map shape locally (`ReadonlyMap<string, number>`); core/surface never imports core/brain. The repo's import-cycle ratchet counts `import type` as an edge, and core/brain/skill-usage.ts already imports from core/surface - the reverse edge would close a cycle.
+8. **t_5d1ec8a8 - plugin-qualified invocation names are normalized at map-build time, never by rewriting records.** The Claude Code `Skill` tool stores `payload["skill"]` exactly as invoked (`open-second-brain:codegraph-partner`), which never equals the discovered bare name. The new `skillUsageWeights(usage, knownNames)` helper joins by exact name first; keys containing a colon are then joined by trying each suffix after a colon against the discovered names (longest matching suffix wins), and keys that match nothing are dropped - they name skills outside this vault's discovery set, which cannot be ranked anyway. The rule and the drop are documented in skill-usage.ts and docs/mcp.md, so the coverage boundary (private records never count; non-discovered names never join) is stated, not silent.
+9. **t_4501c662 - sampling selects PRE-conversion entries over the official types.** A new pure module src/core/bench/longmemeval-sample.ts exports `sampleLongMemEvalEntries(entries, opts)`: abstention entries are excluded FIRST (their count flows to the existing `abstention_excluded` semantics, so the receipt stays honest), the remaining entries are stratified by `question_type` (the distinct present types, sorted ascending - the six official types in real datasets, legacy types in the committed samples), each stratum's allocation comes from largest-remainder (Hamilton) apportionment of the cap proportional to stratum population, clamped to the population, with fractional-remainder ties broken by stratum name ascending. Within a stratum, entries are sorted by `q_id`, reordered by a seeded Fisher-Yates over an own mulberry32 PRNG (the raw seed string hashed by `sha256Hex`, its first 8 hex chars parsed into a uint32; no Math.random, no wall clock), the allocation taken, and the selection re-sorted by `q_id` so downstream order is independent of selection. A cap at or above the population selects everyone; a population of zero after abstention exclusion is a named `LongMemEvalSampleError`, not an empty fixture handed to the converter.
+10. **t_4501c662 - the flags are a pair and ride the --recall-floor trace.** `--sample-seed <value>` and `--sample-cap <count>` parse beside `parseRecallFloorFlag` with the same CliError refusal shape; either alone is refused by name (a lone seed would silently select the whole population - the forbidden silent no-op), a non-positive or non-integer cap is refused, and both together require a suite whose registration declares the new `capabilities.sampling: true` (only longmemeval) - otherwise the CLI refuses naming the suite, so the flags can never be silently ignored by a loader that cannot honor them. The loader contract widens with an optional second parameter (`BenchSuiteLoadOptions`) preserving `registerBenchSuite` compatibility; `loadLongMemEvalFixture` gains an options-carrying path and the no-options path stays byte-identical.
+11. **t_4501c662 - sampling options fold into run identity with spread-omission.** `benchRunIdentityHash`'s canonical record gains a `sample` record (seed, cap) only when sampling is set: two option sets that produce the same fixture (cap at or above the population) still get different run ids, while runs without sampling hash exactly as before, so pre-change in-flight runs keep resuming (the loud identity guard is reserved for runs whose options actually changed). `BenchCheckpoint` gains the optional `sample` field beside `pinned_knobs`, and `runMemoryBench` validates and folds like `recallFloor` (named refusal before any run state exists). Receipt fields `sample_population`, `sample_selected` and `sample_strata` join `BenchSuiteReceipt` mirroring `abstention_excluded`, and the longmemeval report family gains `sample_selected`, so a run reports honestly what it measured.
+12. **t_68ae8a53 - a vendored minimal JSONC editor, not a new dependency.** The repo has exactly one runtime dependency and no JSONC handling anywhere, and the needed edit surface is narrow: read with positions enough to locate top-level keys, insert or replace one entry under `mcp.servers`, remove it, and refuse ambiguity. New leaf module src/core/install/jsonc.ts (sibling of json-merge.ts): a tokenizer covering line and block comments, strings with escapes, trailing commas and literals; edits applied as token-offset splices, never whole-root re-serialization; duplicate top-level keys are a named `JsoncEditError` refusal (upstream refuses ambiguity the same way). Files bearing no comments and no trailing commas keep the existing json-merge round-trip byte-for-byte (every existing pinned-content test holds); the JSONC path activates only when the tokenizer sees comments or trailing commas. A dependency would be the larger, less honest change for this surface.
+13. **t_68ae8a53 - shape detection by file, shared by apply and verify.** `resolveTargetShape(parsed)` returns the native `mcp.servers` key when the file carries that object, else the V1 top-level `mcp` - adopting upstream's precedence rule (native declarations win; an existing legacy declaration must not be shadowed). Apply and verify both call the same function, so verify's reconstruction is symmetric with apply by construction and a fresh install can never report drift against itself. The manifest's `owned_keys` string records the shape actually written (`mcp.<name>` or `mcp.servers.<name>`), so uninstall removes exactly what apply wrote. When only `opencode.jsonc` exists it is the config path; when neither exists a fresh install creates `opencode.json` as today (V1 and V2 hosts both read it).
+14. **t_68ae8a53 - the doctor probe learns the nested key in the same change.** `JSON_MCP_TOP_LEVEL_KEYS` and `extractFromJsonConfig` learn the dotted `mcp.servers` path, or every healthy V2 install would report "no Open Second Brain command entry found" from a check that is independent of the adapter. Host facts grow nothing: the V1/V2 choice is a property of the on-disk file, and the module's rule is that nothing there reads the machine; the 10-target census pin stays untouched because no target joins or leaves.
+15. **Wave-wide house rules.** Every opt-in surface ships default off with a byte-identical-off regression proof (for the adapter, V1-shaped configs are the byte-identical case); failures are typed named errors, never silent fallbacks - the sampler's zero-population case, the JSONC ambiguous-file case, the lone-sample-flag case and the wrong-suite sample-flag case all refuse by name; the tool census, continuity reader/envelope censuses, write-site census, host-facts census and import-cycle ratchet move only in the commits that grow their inputs (none of them grow this wave); no variable is named anything secret-shaped (the redactor and plugin-scanner rules); docs prose uses the full product name and no exclamation marks.
+
+## File changes
+
+Lane 1 - per-source-session pool cap (t_bb6ce095):
+
+- new `src/core/search/pipeline/session-pool-cap.ts` (pure grouping and capping over ranked rows through the frontmatter cache)
+- modify `src/core/search/pipeline/assemble.ts` (widen disjunction, cap phase placement, drop count, narrowings note)
+- modify `src/core/search/types.ts` (optional `SearchOptions.poolMaxPerSession`, optional `ResolvedRecallConfig.poolMaxPerSession`)
+- modify `src/core/search/index.ts` (DEFAULTS entry, envOrConfig parse, validateResolvedConfig line, spread-omitted resolved field)
+- modify `src/core/search/pipeline/cache-slot.ts` and `src/core/search/query-cache.ts` (results-affecting fingerprint folds)
+- modify `src/core/search/retrieval-trail.ts` (new degradation code)
+- new tests `tests/core/search/session-pool-cap.test.ts`
+- extend `tests/core/search/pool-total.test.ts`, `tests/core/search/retrieval-trail.test.ts`, `tests/core/search/config.test.ts`
+- append-only after lane 3's contract commit: `src/cli/brain/verbs/bench.ts` (one entry in `BENCH_PIN_NESTED_KEYS.recall`)
+
+Lane 2 - usage-ordered skill offers (t_5d1ec8a8):
+
+- modify `src/core/brain/skill-usage.ts` (pure `skillUsageWeights` map builder with the normalization rule)
+- modify `src/core/surface/skill-attach.ts` (usage option, composite ordering, amended invariant docblocks)
+- modify `src/core/config.ts` (`resolveSkillsAttachUsageOrdering` beside the other skill gates)
+- modify `src/mcp/skill-tools.ts` (resolve the flag, derive usage once, pass the map to both build paths, tool description line)
+- extend `tests/core/brain/skill-usage.test.ts`, `tests/core/surface/skill-attach.test.ts`, `tests/core/surface/skill-attach-decision.test.ts`, `tests/mcp/skills-attach-tool.test.ts`, `tests/mcp/skills-attach-decision-tool.test.ts`
+
+Lane 3 - seeded LongMemEval sampling (t_4501c662):
+
+- new `src/core/bench/longmemeval-sample.ts` (stratification, apportionment, own PRNG, named error)
+- modify `src/core/bench/types.ts` (`BenchSuiteLoadOptions`, `capabilities.sampling`, receipt fields, report family field, checkpoint field)
+- modify `src/core/bench/longmemeval.ts` (options-carrying loader path, sampling receipt)
+- modify `src/core/bench/phases.ts` (`BenchRunOptions.sample`, named refusal, identity fold)
+- modify `src/core/bench/run-store.ts` (spread-omitted `sample` in the identity hash, create/load opts)
+- modify `src/cli/brain/verbs/bench.ts` (flags, validators, capability gate, suite registration entries, USAGE string, report print)
+- append-only `src/cli/command-manifest.ts`, `src/cli/brain/help-text.ts` (bench verb strings)
+- new tests `tests/core/bench/longmemeval-sample.test.ts`
+- extend `tests/core/bench/longmemeval.test.ts`, `tests/core/bench/run-store.test.ts`, `tests/core/bench/phases.test.ts`, `tests/cli/brain-bench.test.ts`
+
+Lane 4 - OpenCode V2 config shape (t_68ae8a53):
+
+- new `src/core/install/jsonc.ts` (vendored minimal comment-preserving editor, named error)
+- modify `src/core/install/adapters/opencode.ts` (shape detection shared by apply and verify, `.jsonc` path resolution, JSONC-aware write path, plan notes)
+- modify `src/core/doctor-readiness.ts` (nested `mcp.servers` key in the registered-command probe)
+- new tests `tests/core/install/jsonc.test.ts`
+- extend `tests/core/install/adapters/opencode.test.ts`, `tests/core/doctor-readiness.test.ts`, `tests/cli/bootstrap.test.ts`, `tests/cli/install-json-shape.test.ts`
+
+Integration lane:
+
+- modify `docs/cli-reference.md`, `docs/how-it-works.md`, `docs/mcp.md`, `docs/observability.md`, `install/opencode.md`, `docs/updating.md`, `README.md` plus `plugins/codex/README.md` via `bun run sync-plugin-mirrors`, `CHANGELOG.md`, `package.json` plus the manifests synced by `scripts/sync-version.ts` (minor bump)
+- census reconciliation across the ratchet tests named in the recon reports
+
+## Risks and open questions
+
+- **Cache staleness on the new knob.** The cap changes result content, so a missing fingerprint fold serves stale rows; the lane mirrors the two mmrLambda folds exactly and the config test pins both.
+- **Ranking-behavior drift on the skill offer.** The reorder changes what agents are offered every turn once the flag is on, and `computeSkillOfferId` hashes the offered order, so offer ids shift when usage data shifts - by design, but any fixture pinning an offer id must also pin the usage input and nowMs. The default-off path is byte-identical and the bench-style surface tests cover both modes.
+- **Bench identity and resume.** The sampler's spread-omitted identity fold keeps pre-change run ids stable, but a resumed run whose sampling options changed still fails the guard loudly by design; docs say so rather than hiding it. Committed sample fixtures stay untouched - sampling tests build synthetic populations through the existing `entry()` helper so fixture hashes in CI stay pinned.
+- **JSONC edge cases.** The vendored editor refuses what it cannot rewrite honestly (duplicate top-level keys); a config it refuses leaves the install flow with a named error and no partial write. The tokenizer's test matrix covers comments in the target region, comments elsewhere, trailing commas and BOM.
+- **The user-modified-block guard on first V2-shape apply.** When a native `mcp.servers` object appears in a config the adapter previously owned, the guard reports the file as user-modified and the first re-apply is an operator action; the docs follow the 1.50.0 upgrade-notes convention (the first `--check` after the host upgrades reports drift once; fix is re-apply).
+- **Directory plugin loading on V2 hosts.** The wave keeps the file-drop plugin install on the evidence that V2's config-object removal directives presuppose directory loading; if a future host drops it, the plugin would need config-object registration as a follow-up. The adapter's verify path (plugin content compare) surfaces that failure rather than hiding it.
+- **Cost of the usage read per turn.** With the flag on, `deriveSkillUsage` reads the whole continuity store once per attach call - precedent-priced by the existing MCP usage operation, absent when off; the docs name the cost and the deferred windowing option.
+- **Pre-existing, out of scope:** the atomic write replaces a symlinked config rather than writing through it (V1 paths included); Windows launcher env and BOM handling are already covered by the existing write path and tests.
diff --git a/docs/brainstorm/wiring-shipped-seams/plan.md b/docs/brainstorm/wiring-shipped-seams/plan.md
new file mode 100644
index 00000000..469092bc
--- /dev/null
+++ b/docs/brainstorm/wiring-shipped-seams/plan.md
@@ -0,0 +1,159 @@
+# Wiring shipped seams - implementation plan
+
+Executed by the implement node with PARALLEL IMPLEMENTATION LANES. Lane 3 lands its contract commit first; lanes 1, 2, 3 and 4 then run concurrently over disjoint files; the integrator finishes. Every task is atomic and commit-sized. Every opt-in surface is default off with a byte-identical-off regression proof; failures are typed named errors, never silent fallbacks; no new MCP tools, no new continuity record kinds, no new external dependencies.
+
+## Cross-lane contract
+
+### (a) File ownership - every file has exactly one owner; overlap forbidden
+
+- **Lane 1** (per-source-session pool cap, t_bb6ce095): `src/core/search/pipeline/session-pool-cap.ts` (new), `src/core/search/pipeline/assemble.ts`, `src/core/search/types.ts`, `src/core/search/index.ts`, `src/core/search/pipeline/cache-slot.ts`, `src/core/search/query-cache.ts`, `src/core/search/retrieval-trail.ts`, `tests/core/search/session-pool-cap.test.ts` (new), `tests/core/search/pool-total.test.ts`, `tests/core/search/retrieval-trail.test.ts`, `tests/core/search/config.test.ts`.
+- **Lane 2** (usage-ordered skill offers, t_5d1ec8a8): `src/core/brain/skill-usage.ts`, `src/core/surface/skill-attach.ts`, `src/core/config.ts`, `src/mcp/skill-tools.ts`, `tests/core/brain/skill-usage.test.ts`, `tests/core/surface/skill-attach.test.ts`, `tests/core/surface/skill-attach-decision.test.ts`, `tests/mcp/skills-attach-tool.test.ts`, `tests/mcp/skills-attach-decision-tool.test.ts`.
+- **Lane 3** (seeded LongMemEval sampling, t_4501c662): `src/core/bench/longmemeval-sample.ts` (new), `src/core/bench/longmemeval.ts`, `src/core/bench/types.ts`, `src/core/bench/phases.ts`, `src/core/bench/run-store.ts`, `src/cli/brain/verbs/bench.ts`, `src/cli/command-manifest.ts` (append-only), `src/cli/brain/help-text.ts` (append-only), `tests/core/bench/longmemeval-sample.test.ts` (new), `tests/core/bench/longmemeval.test.ts`, `tests/core/bench/run-store.test.ts`, `tests/core/bench/phases.test.ts`, `tests/cli/brain-bench.test.ts`. `tests/core/bench/locomo.test.ts` and the committed sample fixtures under `tests/fixtures/bench/` are FROZEN and must stay green untouched.
+- **Lane 4** (OpenCode V2 config shape, t_68ae8a53): `src/core/install/jsonc.ts` (new), `src/core/install/adapters/opencode.ts`, `src/core/doctor-readiness.ts`, `tests/core/install/jsonc.test.ts` (new), `tests/core/install/adapters/opencode.test.ts`, `tests/core/doctor-readiness.test.ts`, `tests/cli/bootstrap.test.ts`, `tests/cli/install-json-shape.test.ts`. `plugins/opencode/open-second-brain.ts` and `src/core/runtime/host-facts.ts` are FROZEN for the wave.
+- **Integrator**: docs pages (`docs/cli-reference.md`, `docs/how-it-works.md`, `docs/mcp.md`, `docs/observability.md`, `install/opencode.md`, `docs/updating.md`, `README.md` plus `plugins/codex/README.md` via `bun run sync-plugin-mirrors`), `CHANGELOG.md`, `package.json` plus the manifests synced by `scripts/sync-version.ts` (minor bump), census reconciliation. No lane-owned source files.
+
+### (b) The one shared file and its append-only split
+
+- `src/cli/brain/verbs/bench.ts`: Lane 3 owns the file. Lane 1 holds append-only rights strictly limited to one entry in the `BENCH_PIN_NESTED_KEYS.recall` list (the `poolMaxPerSession` knob name), exercisable only after Lane 3's contract commit (L3-T1) has landed. No other region of the file may be touched by Lane 1.
+
+### (c) Pure modules each lane produces, and what waits on them
+
+- Lane 1 produces `src/core/search/pipeline/session-pool-cap.ts` (pure: ranked rows plus a frontmatter cache in, capped rows plus a drop count out; no clock, no fs beyond the passed cache). It is lane-internal; nothing else waits on it.
+- Lane 2 produces the pure `skillUsageWeights(usage, knownNames)` export in `src/core/brain/skill-usage.ts` (usage rows plus discovered names in, weight map out; no clock - nowMs arrives inside `usage`). It is lane-internal; nothing else waits on it.
+- Lane 3 produces `src/core/bench/longmemeval-sample.ts` (pure: entries plus seed and cap in, selected entries plus a receipt fragment out; own PRNG, no Math.random, no wall clock, no fs). Lane 1's append-only right waits only on L3-T1 (the bench verb contract), not on this module.
+- Lane 4 produces `src/core/install/jsonc.ts` (pure: text in, spliced text out, or a named `JsoncEditError`; no fs). It is lane-internal; nothing else waits on it.
+
+### (d) Ordering and the dependency-wait rule
+
+Lane 3 commits L3-T1 first, before any other lane-3 task and before lane 1 needs the bench file. Lane 1's L1-T4 is its final task: if L3-T1 has not landed when lanes 1-3 of lane 1 are done, lane 1 writes the failing pin test against the documented key list (it fails on the missing entry, which is the expected failure), then polls `git log -- src/cli/brain/verbs/bench.ts` every 30 s for up to 12 min; after 30 min of waiting in total, escalate to the orchestrator instead of inventing the surface. Lanes 2 and 4 depend on nothing and start immediately.
+
+### (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(skills): ...`, `feat(bench): ...`, `feat(install): ...`); 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 (knob on, no session-ref notes, empty usage vault, sample cap at the population) is part of every byte-identical test.
+- Subprocess-spawning tests get explicit 20000 ms budgets; bun's default per-test budget is 5000 ms; order-dependent assertions use sorted listings.
+- Hoist repeated literals into named constants; never name a variable anything secret-shaped; docs prose uses the full product name, no exclamation marks.
+
+## Lane 1 - per-source-session pool cap (t_bb6ce095)
+
+### Task L1-T1: Pure session-pool-cap module
+- **Files**: `src/core/search/pipeline/session-pool-cap.ts` (new), `tests/core/search/session-pool-cap.test.ts` (new)
+- **Seams**: frozen `BrainSearchResult` rows per the `res()` helper pattern in tests/core/search/mmr.test.ts:16-33; `readCachedFrontmatterEntry` (src/core/search/result-filters.ts:60) and `CachedFrontmatter.unreadable` for the read verdict; the `duplicateKey` null pass-through precedent (src/core/search/pipeline/assemble.ts:144-147).
+- **Test-first steps**: build a frontmatter cache over temp notes where several paths share a `session_ref`; assert rows keep ranked order, the first `capPerSession` rows per key survive, the rest are dropped and counted; assert rows with `session_id` only group by it; assert no-identity rows and unreadable-frontmatter rows pass through uncapped; assert a non-string or empty frontmatter value counts as absent; assert the function is pure (same inputs, same outputs, no cache mutation beyond reads).
+- **Done criteria**: the module exports the cap function and a result carrying results plus `dropped`; every grouped, uncapped and unreadable case above passes; the module imports only from `../result-filters.ts` and `../types.ts` (no upward edges, import-cycles ratchet green).
+- **Depends on**: none
+
+### Task L1-T2: Config plumbing exactly like search_mmr_lambda
+- **Files**: `src/core/search/types.ts`, `src/core/search/index.ts`, `src/core/search/pipeline/cache-slot.ts`, `src/core/search/query-cache.ts`, `tests/core/search/config.test.ts`
+- **Seams**: `DEFAULTS` block (index.ts:264-298, `mmrLambda: 0.7` at :276); the `parseFloat01(envOrConfig(...))` parse at :1182-1186 becomes the pattern for a `parseInteger(envOrConfig(env, config, "OPEN_SECOND_BRAIN_SEARCH_POOL_MAX_PER_SESSION", "search_pool_max_per_session"), ...)` parse; `validateResolvedConfig` (index.ts:629) gains the integer-range line; the spread-omission pattern at index.ts:1175-1178 (`relationalRerankPin`); `ResolvedRecallConfig` (types.ts:1540-1542); `SearchOptions.mmrLambda` (types.ts:919) as the per-query override pattern; `configFingerprint` (cache-slot.ts:279-300, `mmr: r.mmrLambda` at :284); the per-query cache key (query-cache.ts:124).
+- **Test-first steps**: a failing config test resolves the knob from an env var and from a `_brain.yaml` key, pins the default 0, pins the range refusal for a negative value through `validateResolvedConfig`, pins the resolved field ABSENT at 0 and present at a positive value (exact-shape assertion), and pins both fingerprint folds (a knob change invalidates cached rows: fingerprint string differs; per-query key differs when the override is set).
+- **Done criteria**: config tests green; `ResolvedRecallConfig.poolMaxPerSession?` and `SearchOptions.poolMaxPerSession?` documented with doc comments naming the off value; existing exact-shape resolved-config tests untouched and green.
+- **Depends on**: none
+
+### Task L1-T3: Assemble wiring - widen, cap phase, drop note, byte-identical off
+- **Files**: `src/core/search/pipeline/assemble.ts`, `src/core/search/retrieval-trail.ts`, `tests/core/search/session-pool-cap.test.ts`, `tests/core/search/pool-total.test.ts`, `tests/core/search/retrieval-trail.test.ts`
+- **Seams**: the widening disjunction and `Math.max` composition (assemble.ts:249-257); the phase order merge, traversal, floor (:330-338), MMR (:339-342), relevance rerank (:346-348); the assemble result fields (`floorDropped` at :353) and `noteAssemblyNarrowings` (:404-430); the degradation code family (retrieval-trail.ts:159-189, `relevanceFloorDroppedRows` shape); the full-pipeline harness in tests/core/search/pool-total.test.ts:16-45 (`createTempVault`/`makeConfig`/`writeMd` from tests/helpers/search-fixtures.ts, `indexVault`, then `search()`).
+- **Test-first steps**: failing test one - a vault where one `session_ref` covers enough notes to fill the window: knob off returns today's crowded order byte-for-byte against a frozen fixture; knob on spreads the window across sessions and reports the new `source-session-capped-rows` degradation with `detail.dropped`; failing test two - the widened pool: with the cap on, `rankLimit` joins the widening composition so a `crossEncoderActive` query keeps its `topK` guarantee; failing test three - no-identity vaults (ordinary notes only): knob on is byte-identical to knob off and adds zero frontmatter reads' worth of behavioral difference; failing test four - the degradation note is emitted once per answer, and the backfill still fires exactly when it does today (the cap never triggers a second assemble, pinning the design decision that `wideCap` cannot exceed the widened `rankLimit`).
+- **Done criteria**: the cap runs after the floor and before MMR; drops carry the new code beside `relevance-floor-dropped-rows`; the off path is byte-identical on the full-pipeline fixture; every pre-existing search test passes untouched.
+- **Depends on**: L1-T1, L1-T2
+
+### Task L1-T4: Bench pin entry (the wave's one append-only right)
+- **Files**: `src/cli/brain/verbs/bench.ts` (append-only: one entry in `BENCH_PIN_NESTED_KEYS.recall`), `tests/cli/brain-bench.test.ts` is lane 3's - lane 1 asserts the pin acceptance through the exported validator or a lane-local test importing the key list.
+- **Seams**: `BENCH_PIN_NESTED_KEYS.recall` (src/cli/brain/verbs/bench.ts:176+) already lists `mmrLambda`, `maxHops` and siblings; a `--pin '{"recall":{"poolMaxPerSession":N}}'` is refused until the name joins the list.
+- **Test-first steps**: a failing test pins that the knob name is accepted in a recall pin (and a bogus name still refused), then add the single list entry.
+- **Done criteria**: the pin accepts the knob; the bench pin identity guard tests stay green; no other line of the bench verb touched.
+- **Depends on**: L1-T3, and L3-T1 (contract commit) must have landed
+
+## Lane 2 - usage-ordered skill offers (t_5d1ec8a8)
+
+### Task L2-T1: Usage map builder with the name-normalization rule
+- **Files**: `src/core/brain/skill-usage.ts`, `tests/core/brain/skill-usage.test.ts`
+- **Seams**: `deriveSkillUsage` (skill-usage.ts:105-149) and `SkillUsage.weight` in (0, 1]; the store keying on the raw `payload["skill"]` string (skill-usage.ts:88); the plugin-qualified arrival path (`resolveInvokedSkill`, src/core/brain/sessions/import.ts:883-897, returns the `Skill` tool's command string unmodified).
+- **Test-first steps**: failing test - `skillUsageWeights(usage, knownNames)` joins exact names first; a usage key `open-second-brain:codegraph-partner` joins discovered `codegraph-partner` through the suffix-after-colon rule (longest matching suffix wins when several colons exist); keys matching nothing are dropped and the docblock states the rule; the map values are the decay weights unchanged; an empty usage list yields an empty map.
+- **Done criteria**: the helper is pure, exported beside `deriveSkillUsage`, its docblock documents the join rule and the drop; existing skill-usage tests pass untouched (no record rewriting anywhere).
+- **Depends on**: none
+
+### Task L2-T2: The composite fold in rankSkillCandidates and the amended invariants
+- **Files**: `src/core/surface/skill-attach.ts`, `tests/core/surface/skill-attach.test.ts`
+- **Seams**: `BuildSkillAttachmentOptions` (skill-attach.ts:48-62); the `Pick` in `rankSkillCandidates` (skill-attach.ts:120); the floor filter at :127 and the invariant comment at :126; the module docblock at :4-8; the local structural input shape (no core/brain import - the import-cycles ratchet counts `import type`); the stable-output tie-break convention (skills.ts:198, skill-usage.ts:147).
+- **Test-first steps**: failing test - with `usageWeight` absent, output order and content are byte-identical to today's fixture (the off proof); with a map present, a lexically slightly-hotter one-off drops below a daily-used skill under the composite `score * (1 + SKILL_USAGE_ORDERING_MAX_BOOST * weight)` with the constant at 0.5; equal composites resolve by name ascending; a non-matching skill can never cross the discriminating-term floor regardless of weight; the returned `score` field stays the lexical score; the composite ordering is deterministic across repeated calls.
+- **Done criteria**: ordering tests green; the docblock at :4-8 and the comment at :126 amended in the same commit to state the gated contract (absent usage input, ranking stays the scorer's); the constant exported with its rationale; every pre-existing skill-attach test passes untouched on the off path.
+- **Depends on**: none (the map shape is a local `ReadonlyMap<string, number>`; L2-T1 is lane-internal sequencing, not a blocker)
+
+### Task L2-T3: Config flag and per-turn tool wiring
+- **Files**: `src/core/config.ts`, `src/mcp/skill-tools.ts`, `tests/mcp/skills-attach-tool.test.ts`
+- **Seams**: `resolveConfigFlag`/`isFlagOn` (config.ts:779-786) and the resolver family (:795-811); `toolSkillsAttach` (skill-tools.ts:164-187): the gate at :170, triggers at :173, discovery at :174, both build calls at :177 and :179-186; the tool description string (:229-231).
+- **Test-first steps**: failing test - `resolveSkillsAttachUsageOrdering` reads env and `_brain.yaml` key `skills_attach_usage_ordering`, default off; with the flag off, `skills_attach` output is byte-identical on a vault with usage records (off proof at the tool level); with the flag on and usage records present (append `skill_invoked` records via the test helper in tests/core/brain/skill-usage.test.ts:23-28), the offer reorders per the composite, offer_id recomputed over the rendered order; with the flag on and an empty vault, the offer is byte-identical to off (mode-on-but-inert); `deriveSkillUsage` is called exactly once per attach call when on and zero times when off (assert through a module-level counter or spy).
+- **Done criteria**: flag resolver beside its siblings with the same docblock posture; the tool passes the same map to both build paths; the tool description mentions the ordering knob in one clause; pre-existing skills-attach tool tests green.
+- **Depends on**: L2-T1, L2-T2
+
+### Task L2-T4: Decision-model coherence
+- **Files**: `tests/mcp/skills-attach-decision-tool.test.ts`, `tests/core/surface/skill-attach-decision.test.ts`
+- **Seams**: `buildSkillAttachmentWithDecision` (skill-attach-decision.ts:243+): the BM25 baseline via `buildSkillAttachment` (:246), the shortlist via `rankSkillCandidates` (:257), inheritance through `DecisionSkillAttachmentOptions` (:117), the `deterministic_offered`/`deterministic_offer_id` record fields (:293-294).
+- **Test-first steps**: failing test - with the flag on, the decision path's shortlist and its deterministic fallback offer reflect the same usage map (the deterministic record matches what deterministic mode would have offered); with the flag off, decision-path output is byte-identical to today's fixture; a fixture pinning an offer id pins the usage input and nowMs with it.
+- **Done criteria**: both modes coherent on one map; pre-existing decision tests green; no changes to skill-attach-decision.ts source required (options inheritance carries the input) - if implementation finds otherwise, the change stays inside lane 2's file list after orchestrator sign-off.
+- **Depends on**: L2-T3
+
+## Lane 3 - seeded LongMemEval sampling (t_4501c662)
+
+### Task L3-T1: Contract commit - loader options, capability, CLI flags, refusals
+- **Files**: `src/core/bench/types.ts`, `src/cli/brain/verbs/bench.ts`, `src/cli/command-manifest.ts` (append-only), `src/cli/brain/help-text.ts` (append-only), `tests/cli/brain-bench.test.ts`
+- **Seams**: `BenchSuiteRegistration`/`BenchSuiteLoad` (types.ts:176-196); the registry entries (bench.ts:55-81) and `registerBenchSuite` compatibility (:84-92); the capabilities precedent `{ embeddings: boolean }`; the `--recall-floor` trace: parse spec (:292-300), `parseRecallFloorFlag` (:279-288), threading into `runMemoryBench` (:338-352); the USAGE string (:29-31); the report printer (:365-376); fixture path resolution (:386-391).
+- **Test-first steps**: failing CLI tests - `--sample-seed` alone is refused by name; `--sample-cap` alone is refused by name; a non-positive or non-integer cap is refused naming the value; both flags together with a suite whose capabilities lack `sampling: true` (locomo, surfacing-replay, no-suite default) are refused naming the suite; both flags with `--suite longmemeval` reach a stub loader registered through `registerBenchSuite` carrying `BenchSuiteLoadOptions { sample: { seed, cap } }`; omitting both flags leaves today's CLI behavior byte-identical (existing brain-bench assertions untouched, including `quality.total === 6` on the tiny fixture); a third-party registration without the capability still registers and loads unchanged (the loader's second parameter is optional).
+- **Done criteria**: the type surface (`BenchSuiteLoadOptions`, `capabilities.sampling`) and the flag pair land with all refusal paths named; the registry's three built-in entries updated (longmemeval `sampling: true`, others false); the USAGE and help-text strings name the flags; pre-existing CLI tests green untouched.
+- **Depends on**: none (this is the wave's contract commit and must be lane 3's first)
+
+### Task L3-T2: Pure stratified sampler module
+- **Files**: `src/core/bench/longmemeval-sample.ts` (new), `tests/core/bench/longmemeval-sample.test.ts` (new)
+- **Seams**: `LongMemEvalEntry` and `isLongMemEvalAbstention` (longmemeval.ts:116-131, 163-170); `LONGMEMEVAL_QUESTION_TYPES` (:201-204); the `entry()` population builder pattern (tests/core/bench/longmemeval.test.ts:38-54); `canonicalJson` + `sha256Hex` (src/core/integrity/digest.ts); the named-error convention (`LongMemEvalParseError`, longmemeval.ts:149).
+- **Test-first steps**: failing tests - abstention entries (both spellings) are excluded before selection and their count flows through; strata are the distinct present `question_type` values sorted ascending; largest-remainder apportionment of the cap proportional to population is exact (sum equals the cap when the population allows), clamped to the population, remainder ties broken by stratum name; the same seed and cap select the same subset twice and across calls (no Math.random, no wall clock - assert by selecting under differing fake clocks if the module takes none at all); a different seed or cap selects a different subset; dataset FILE ORDER cannot change the subset (shuffle the input array, same selection); a cap at or above the population selects everyone; a zero population after abstention exclusion raises the named `LongMemEvalSampleError`; the receipt fragment carries per-stratum population and selected counts.
+- **Done criteria**: the module is pure, network-free, imports no fs, exports the sampler plus the receipt type plus the named error; every determinism and edge case above passes; the egress and verdict-vocabulary censuses stay green.
+- **Depends on**: none for the module itself (L3-T1 for the types it references if declared there; declare the sampler's own option and result types in the sampler module to keep this independent)
+
+### Task L3-T3: Loader wiring and receipt
+- **Files**: `src/core/bench/longmemeval.ts`, `src/core/bench/types.ts`, `tests/core/bench/longmemeval.test.ts`
+- **Seams**: `loadLongMemEvalFixture` (longmemeval.ts:648-658); the conversion receipt (`abstention_excluded` at :139-142, :644); `BenchSuiteReceipt` (types.ts:182-185); the report family field (`abstention_excluded: number | null`, types.ts:281) and its print site (bench.ts:371-375).
+- **Test-first steps**: failing tests - the no-options loader path returns today's fixture and receipt byte-identically (frozen assertion); with `sample` options, abstention is excluded first, the sampler runs on the survivors, the selected entries convert, the receipt carries `sample_population`, `sample_selected` and `sample_strata` beside `abstention_excluded`; an end-to-end `runMemoryBench` with sampling over a synthetic dataset (explicit 20000 ms budget) reports the sampled count through the longmemeval family and the CLI line.
+- **Done criteria**: sampling provably happens pre-conversion (the converted fixture's question count equals the sampled count); receipt fields mirror the abstention precedent; unset options leave every existing longmemeval test green untouched.
+- **Depends on**: L3-T1, L3-T2
+
+### Task L3-T4: Run identity and checkpoint fold
+- **Files**: `src/core/bench/phases.ts`, `src/core/bench/run-store.ts`, `src/core/bench/types.ts`, `tests/core/bench/phases.test.ts`, `tests/core/bench/run-store.test.ts`
+- **Seams**: `BenchRunOptions.recallFloor` and the named pre-run refusal (phases.ts:99-111, 214-221); the identity fold (:223-234); `benchRunIdentityHash` (run-store.ts:49-61) and create/load opts (:73-100, 102-138); the resume guard (:117-136); `BenchCheckpoint` (types.ts:360-374, `pinned_knobs` precedent).
+- **Test-first steps**: failing tests - the canonical identity record spreads `sample` in ONLY when sampling is set, so a no-sampling run's id equals the pre-change id byte-for-byte (pin the hash against a frozen value); two runs differing only in seed, or only in cap, get different run ids even when both fixtures are identical (cap at the population); a resumed run whose sampling options changed fails the identity guard with the existing named error; the refusal fires before any run state exists when options are invalid at the phases layer.
+- **Done criteria**: identity, checkpoint and refusal tests green; the identity guard's loud-failure docblock updated to name sampling options among the guarded inputs; pre-existing run-store and phases tests green.
+- **Depends on**: L3-T1, L3-T2, L3-T3
+
+## Lane 4 - OpenCode V2 config shape (t_68ae8a53)
+
+### Task L4-T1: Vendored minimal JSONC editor
+- **Files**: `src/core/install/jsonc.ts` (new), `tests/core/install/jsonc.test.ts` (new)
+- **Seams**: the plain-JSON round-trip it must not regress (src/core/install/json-merge.ts:44-102, BOM strip at :91, indent sniffing at :119-126); the leaf-module discipline and import-cycles ratchet; the atomic write path (src/core/fs-atomic.ts) stays the caller's concern - the editor transforms text only.
+- **Test-first steps**: failing tests - the tokenizer parses JSONC with line comments, block comments, strings containing comment-like content and escapes, trailing commas; a comment-free file round-trips byte-identically through the editor's read; inserting one entry under a nested object splices at token offsets and leaves every comment and the file's formatting outside the splice untouched (byte-compare the untouched regions); replacing an existing entry splices exactly its value range; removing an entry closes the hole without disturbing neighbors; duplicate top-level keys raise the named `JsoncEditError` mentioning the key; a BOM is stripped on read and restored on write; malformed input raises the named error rather than emitting partial text.
+- **Done criteria**: the editor is pure text-in/text-out with one named error type; the test matrix above passes; no new dependency in package.json; import-cycles green (the module imports nothing from src/).
+- **Depends on**: none
+
+### Task L4-T2: Adapter shape detection, `.jsonc` path, JSONC-aware writes, verify symmetry
+- **Files**: `src/core/install/adapters/opencode.ts`, `tests/core/install/adapters/opencode.test.ts`, `tests/cli/install-json-shape.test.ts`
+- **Seams**: `configPath` (opencode.ts:44-46) and `legacyConfigPath` (:48-50); `migrateLegacyMcpJson` (:72-95) as the migration template; `serializeOpencodeEntry` (:58-65); the `createJsonMcpAdapter` base with `topLevelKey: "mcp"` (:116-124) and its apply/verify/uninstall body (_json-mcp.ts:314-418, verify reconstruction :429-525); the user-modified-block guard (_json-mcp.ts:328-351); `owned_keys` (`${topKey}.${KEY}`, :374); the test harness (tests/core/install/adapters/opencode.test.ts:31-83, the legacy-migration describe block :190-239, the conflict aged via `utimesSync` in tests/cli/bootstrap.test.ts:714+).
+- **Test-first steps**: failing tests - shape detection: a config carrying an `mcp.servers` object (with or without our entry) targets `mcp.servers`; a config without it targets top-level `mcp` (today's behavior byte-identical on a V1 fixture, the off proof); both apply and verify derive the shape from the same function, so a fresh V2 install verifies clean against itself (apply then `--check` equivalent reports no drift); the manifest records `owned_keys: ["mcp.servers.<entry>"]` for a V2 write and uninstall removes exactly that key; when only `opencode.jsonc` exists it is the resolved config path and edits preserve its comments (build a JSONC fixture with header and inline comments, apply, assert the comments survive byte-for-byte and our entry landed under `mcp.servers`); duplicate top-level keys surface the named `JsoncEditError` as an apply refusal naming the file; a V1 install with an existing top-level entry is NOT migrated when `mcp.servers` appears without operator re-apply until the next apply, and that first re-apply after the shape change reports the documented one-time drift through the existing guard behavior; the legacy `mcp.json` migration is untouched and green.
+- **Done criteria**: V1 fixtures byte-identical through apply/verify/uninstall; V2 fixtures get native-shape registration with comments preserved; verify symmetric with apply by construction; manifest, uninstall and the plan notes shape-aware; the existing opencode adapter suite green plus the new cases.
+- **Depends on**: L4-T1
+
+### Task L4-T3: Doctor registered-command probe learns the nested key
+- **Files**: `src/core/doctor-readiness.ts`, `tests/core/doctor-readiness.test.ts`
+- **Seams**: `JSON_MCP_TOP_LEVEL_KEYS = ["mcpServers", "mcp"]` (doctor-readiness.ts:641) and `extractFromJsonConfig` (:888-922); the existing opencode extraction test (doctor-readiness.test.ts:521-539); `probeRegisteredCommands` (:723-777).
+- **Test-first steps**: failing test - a config with our entry only under `mcp.servers` is extracted and probed exactly as a top-level entry is today (command, args, environment); the dotted key joins the key list without changing the flat keys' behavior (existing tests green untouched); a config with neither shape still reports the current skipped wording.
+- **Done criteria**: a healthy V2 install passes `o2b doctor`'s registered-command probe; the flat-key behavior is pinned unchanged; pre-existing doctor tests green.
+- **Depends on**: none for the probe logic (L4-T2 for the end-to-end story; the test can be written immediately)
+
+## Integration
+
+### Task INT-T1: Integration gate - censuses, docs, version, full local gates (integrator)
+- **Files**: `docs/cli-reference.md`, `docs/how-it-works.md`, `docs/mcp.md`, `docs/observability.md`, `install/opencode.md`, `docs/updating.md`, `README.md` plus `plugins/codex/README.md` via `bun run sync-plugin-mirrors`, `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). Docs carry: the new config key row and env var beside `search_mmr_lambda` (cli-reference.md:2388 pattern) and the how-it-works ranking paragraph (:1234); the `skills_attach_usage_ordering` key in the docs/mcp.md opt-in list (:1218-1227 pattern) with the normalization and cost notes; the bench flags in cli-reference.md:571-576 and observability.md:223 with the sampling semantics and the resume-guard consequence; install/opencode.md V2 shape and the docs/updating.md one-time drift note following the 1.50.0 convention; the README release paragraph plus the mirror sync. Census pins green: host-facts 10-target equality, write-site and destructive-site censuses, continuity reader/envelope censuses, import cycles, the tool ceiling; `tests/core/bench/locomo.test.ts` and the committed fixture hashes untouched. The CHANGELOG entry names each knob, flag, env var, default and the byte-identical-off guarantee with a trailing Docs bullet enumerating every doc file touched.
+- **Depends on**: L1-T1 through L4-T3
diff --git a/docs/brainstorm/wiring-shipped-seams/variants.md b/docs/brainstorm/wiring-shipped-seams/variants.md
new file mode 100644
index 00000000..cd6fddfb
--- /dev/null
+++ b/docs/brainstorm/wiring-shipped-seams/variants.md
@@ -0,0 +1,42 @@
+# Variants - wiring shipped seams
+
+Audit trail for the brainstorm phase of the feature-release-playbook run on branch feat/wiring-shipped-seams, 2026-10-13. 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: Four parallel disjoint lanes with one bench contract commit first
+- **Approach**: Run the four residues as four file-disjoint lanes. The bench sampler lane lands a contract commit first - CLI flags with paired-flag refusal, the widened loader signature with an options parameter, and the sampling capability declaration - because the pool-cap lane holds the wave's only append-only right on a bench file: one knob name in the bench pin's recall key list, exercisable only after that commit. The cap, skill-ordering and OpenCode lanes start immediately over files nothing else touches; each lane's pure module (cap grouper, usage map builder, stratified sampler, JSONC editor) is written and tested in isolation from its first commit. One integrator pass closes docs, census reconciliation, the CHANGELOG entry and the version bump.
+- **Trade-offs**:
+ - Maximal wall-clock parallelism: three of four lanes share no file with anything and never wait.
+ - Exactly one declared cross-lane dependency (the pin key append waits on the bench contract commit), so coordination cost is one paragraph of contract.
+ - The bench gains its measurement instrument early: the seeded sampler is the tool the cap's measured flip-rule decision needs, inside the same pull request.
+ - Cost: the contract must pin file ownership precisely and the bench lane must commit its contract before the cap lane finishes.
+- **Complexity**: medium
+- **Risk**: low
+
+### Variant 2: Serial stack in risk order
+- **Approach**: Land the four residues one at a time on the shared branch, ordered so each is fully green before the next starts: skill usage ordering (smallest, single ranking point), per-session pool cap, seeded sampler, OpenCode adapter (largest, least mechanical). No lane structure, no cross-lane contract; every change is built against a fully settled tree.
+- **Trade-offs**:
+ - Zero coordination cost and the simplest possible audit trail: one clean commit series per feature.
+ - Every feature is verified against the previous feature's final state, so no append-only splits or dependency waits are needed.
+ - Four sequential build-and-stabilize cycles stretch the release badly; the cap, skill and OpenCode lanes share no files yet serialize unnecessarily.
+ - The measurement instrument arrives third, so the cap lands unmeasured and its flip-rule decision waits or ships on assertion.
+- **Complexity**: small
+- **Risk**: medium
+
+### Variant 3: Two stacked half-waves - retrieval and its measurement, then the host adapter
+- **Approach**: Split the wave into two halves inside one pull request. Half one lands the three retrieval-side residues in parallel (pool cap, skill usage ordering, seeded sampler) with the bench contract commit inside it. Half two lands the OpenCode V2 adapter after the tree settles, keeping the least mechanical, most environment-dependent work isolated from the retrieval changes.
+- **Trade-offs**:
+ - The adapter's review surface is fully separated from the ranking changes, which are the drift-sensitive ones.
+ - Each half is independently verifiable and revertible.
+ - The OpenCode lane shares no files with the retrieval lanes, so isolating it buys review clarity at the price of an artificial serialization point.
+ - The integrator faces two merge windows instead of one, doubling census and docs reconciliation work.
+- **Complexity**: medium
+- **Risk**: medium
+
+### Recommended: Variant 1
+**Rationale**: The four residues are file-disjoint except one genuine seam - the cap's bench pin entry needs the bench verb file the sampler 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, and the sampler lands early enough to measure the cap inside the same pull request. This is the same substrate-then-lanes shape the previous recall-quality wave executed successfully on this repository, so the ownership mechanics, dependency-wait rule and census arbitration are proven here.
+
+## Orchestrator decision
+
+**Chosen: Variant 1 - four parallel disjoint lanes with one bench contract commit first.** 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 (the cap lane's one-line append to `BENCH_PIN_NESTED_KEYS.recall` in the bench verb, exercisable only after lane 3's contract commit lands), so serializing or half-waving the wave would only add wall clock without removing any risk Variant 1 does not already pin. One amendment to the consultant's sketch, recorded in the design doc and the plan contract: lane 3 also owns the bench verb's USAGE and report-print strings and the two append-only CLI string files, keeping every commit single-owner at the file level, and the cap lane's append is its final task so the dependency wait costs it nothing.
diff --git a/docs/cli-reference.md b/docs/cli-reference.md
index c8878e99..9a5d55f8 100644
--- a/docs/cli-reference.md
+++ b/docs/cli-reference.md
@@ -568,12 +568,12 @@ Trigger generation, brief delivery, and gate telemetry are pull-based or config-
```text
o2b 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> [--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)
+o2b brain bench memory --fixture <name|path> [--suite <name>] [--sample-seed <value>] [--sample-cap <n>] [--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). Sampling (since v1.83.0): --sample-seed plus --sample-cap run a seeded, question-type-proportional subset of the dataset instead of the whole fixture; longmemeval is the only suite that declares the capability
```
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.
+Since v1.82.0 the verb's suite registry maps a `--suite` name to its loader plus a declared capability set (`{embeddings: boolean}`, plus `sampling` since v1.83.0): 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. Since v1.83.0 `--sample-seed <value>` plus `--sample-cap <n>` (longmemeval only - the only suite that declares the sampling capability) run a seeded, question-type-proportional subset of the dataset instead of the whole fixture: the two flags are refused apart, a non-positive or non-integer cap is refused naming the value, and a suite whose registration lacks the capability is refused naming the suite, so the flags can never be silently ignored. Sampling selects before conversion - abstention questions are excluded first (their count still lands in `abstention_excluded`), the survivors are stratified by the dataset's own `question_type` values, each stratum contributes its population-proportional share of the cap by largest-remainder apportionment (remainders compared as integers, ties by stratum name), and the draw is a seeded shuffle over entries sorted by question id, so dataset file order cannot change the subset and the same seed and cap always select the same questions. A sampled run's `--json` report carries the sampling receipt in its `longmemeval` family: `sample_population`, `sample_selected` and the per-stratum `sample_strata` sit beside `abstention_excluded`, each present only on a sampled run and absent from a whole-dataset report, and the human report line gains `sample_selected N` only on a sampled run; the seed and cap fold into the run identity: run ids without sampling are unchanged, and a resumed run whose sampling options changed fails the identity guard by name. `--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)
@@ -2124,6 +2124,7 @@ so there is no separate lane field that could drift from it:
| `rerank-provider-unavailable` | the configured cross-encoder reranker (remote endpoint or local model) could not answer, so the answer keeps the heuristic order; `detail.category` is one of `auth`, `quota`, `gone`, `rejected`, `transient`, `timeout`, `network`, `malformed`, `unclassified` |
| `rerank-model-sunset` | the configured rerank model's announced decommission date has passed, so no rerank request was sent and the answer keeps the heuristic order |
| `relevance-floor-dropped-rows` | the relevance floor dropped ranked rows; `detail.dropped` counts them |
+| `source-session-capped-rows` | the per-source-session pool cap (`search_pool_max_per_session`, since v1.83.0) dropped ranked rows whose source import session already held its share of the pool; when that left the window under-filled, the pool was re-widened once before this answer was cut; `detail.dropped` counts them against `detail.cap` |
| `scope-filters-dropped-rows` | visibility, ownership, or session / project scope dropped ranked rows; `detail.dropped` against `detail.before` |
| `cross-vault-origin-failed` | a cross-vault origin could not be searched; `detail.origin` is the origin label |
| `cross-vault-chain-stopped` | an origin answered confidently and the remaining origins were deliberately not searched; `detail.skipped` counts them |
@@ -2389,6 +2390,7 @@ layer config-tunable and bounded:
| `search_max_hops` | `OPEN_SECOND_BRAIN_SEARCH_MAX_HOPS` | `1` | Link-graph traversal depth during recall; `0` disables |
| `search_hop_decay` | `OPEN_SECOND_BRAIN_SEARCH_HOP_DECAY` | `0.5` | Per-hop score multiplier for traversal-surfaced docs |
| `search_max_expansion_per_hit` | `OPEN_SECOND_BRAIN_SEARCH_MAX_EXPANSION_PER_HIT` | `3` | Cap on outbound links followed per node |
+| `search_pool_max_per_session` | `OPEN_SECOND_BRAIN_SEARCH_POOL_MAX_PER_SESSION` | `0` | Cap on candidate-pool rows per source import session (else per note path); `0` off; a value at or above the query's pool width behaves as off |
Recall and ranking quality (v0.20.0), each tunable and bounded:
@@ -2592,6 +2594,52 @@ 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 per-source-session pool cap (since v1.83.0)
+
+One long imported session can otherwise fill the whole reranker-facing
+candidate window with near-duplicate chunks, leaving the diversity
+rerank nothing to spread across. The opt-in knob
+`search_pool_max_per_session` (`OPEN_SECOND_BRAIN_SEARCH_POOL_MAX_PER_SESSION`,
+default `0` - off) bounds how many rows one group may contribute to the
+filtered candidate pool the caller's window is cut from: a row's group
+is a non-empty `session_ref` frontmatter value on an imported signal
+note, else a non-empty `session_id` on a handoff note, else - when the
+note names neither - the row's own path, so all chunks of one note form
+one group. The path fallback is what makes the common sources of
+crowding capable at all: bench session notes (the LongMemEval and
+LoCoMo converters write plain bodies) and multi-chunk single notes carry
+no session frontmatter, and an unreadable file falls back to its path
+for the same reason. Identity is read through the same frontmatter cache
+the pool filters already use. Off (`0` or absent), results and
+query-cache keys are byte-identical and no frontmatter reads are added;
+with the knob on, the resolved value folds into the search fingerprint
+so cached rows can never go stale. A per-query override
+(`poolMaxPerSession`, alongside `mmrLambda`) rides the same plumbing and
+is validated like the config key - a fractional, negative or non-finite
+override is refused by name before the pipeline runs, and `0` forces the
+cap off for that query - and a `--pin` on `brain bench memory` accepts
+the knob by name (`{"recall":{"poolMaxPerSession":N}}`).
+
+When the cap is active it runs after the caller's own filters (status,
+property, degree, reach, visibility, ownership, session/project scope),
+so only filter-passing rows consume a group's quota and the cap can
+never surface a row those filters would withhold; and it widens the
+candidate pool the way MMR and traversal already do, so the cap spreads
+the window instead of merely truncating it sooner. A value at or above
+the pool width the query resolves cannot drop a row and is treated as
+off - the phase never runs - while the value still folds into the
+fingerprint, so a change around that boundary can never serve a stale
+cached row. When the cap's drops leave the window under-filled (and the
+rank cap actually truncated the pool), one additional assemble pass runs
+at a wider pool - wide enough to outrun the heaviest group the first
+pass observed (`limit * (widestGroup + 1)`, beside the existing backfill
+width) - so the window refills from the groups the cap did not exhaust
+when the corpus holds the rows; a corpus that holds nothing outside the
+heavy group still answers short, and the trail names the final pass's
+numbers. Drops carry a `source-session-capped-rows` entry in the
+retrieval trail's `degraded` list (see "The retrieval trail"), with
+`detail.dropped` against `detail.cap`.
+
### The reserved visibility token (since v1.54.0)
```text
diff --git a/docs/how-it-works.md b/docs/how-it-works.md
index bb01f017..0cd1ce9e 100644
--- a/docs/how-it-works.md
+++ b/docs/how-it-works.md
@@ -1231,7 +1231,21 @@ semantic_weightΒ·cosine + link_boost + recency_boost + entity_boost)`
documents scored `parentΒ·hop_decay^hop` (bounded by `search_max_hops`
/ `search_max_expansion_per_hit`); then MMR reranks the pool with a
deterministic token-set similarity so near-duplicates do not crowd
- the top (`search_mmr_lambda`, `1` disables). Header-anchored chunking
+ the top (`search_mmr_lambda`, `1` disables). An opt-in cap on the
+ pool keeps one group from filling the window the caller draws from
+ (`search_pool_max_per_session`, default `0` - off; since v1.83.0): a
+ row's group is its source import session (`session_ref` on imported
+ signal notes, `session_id` on handoff notes) or, when a note names
+ neither, its own path - all chunks of one note form one group, so
+ bench session notes and multi-chunk notes are capped too. The cap runs
+ after the caller's own filters, so only filter-passing rows consume a
+ group's quota and the cap never surfaces a row those filters would
+ withhold; it widens the pool rather than truncating it; a value at or
+ above the query's resolved pool width behaves as off; and when its
+ drops leave the window under-filled, one wider assemble pass re-runs
+ so the window refills from the groups the cap did not exhaust. A vault
+ whose notes each fit in one chunk is byte-identical with the knob on
+ or off. Header-anchored chunking
indexes each chunk's heading breadcrumb in a dedicated FTS column
(weighted below content) so a mid-document chunk keeps its topical
anchor. Entity and heading layers populate on the next reindex.
diff --git a/docs/mcp.md b/docs/mcp.md
index 3d1fee53..24e18360 100644
--- a/docs/mcp.md
+++ b/docs/mcp.md
@@ -1207,8 +1207,8 @@ anywhere in its derivation. A single-skill corpus carries no
discrimination at all, so the floor abstains there rather than dropping
the only candidate.
-Two optional config keys (each with a matching environment variable)
-tune the surface; both are off/unset by default, so behaviour is
+Three optional config keys (each with a matching environment variable)
+tune the surface; each is off/unset by default, so behaviour is
unchanged unless an operator opts in:
- `skills_dir` (`OPEN_SECOND_BRAIN_SKILLS_DIR`) overrides the skill
@@ -1226,6 +1226,45 @@ unchanged unless an operator opts in:
(`triggers: [research, lookup]`); the scorer also emits overlapping
bigrams for runs of Han characters, so a spaceless CJK query can match a
trigger keyword.
+- `skills_attach_usage_ordering`
+ (`OPEN_SECOND_BRAIN_SKILLS_ATTACH_USAGE_ORDERING`), when `"true"` or
+ `"1"`, reorders the survivors of the discriminating-term floor by a
+ bounded composite of lexical score and observed invocation usage,
+ `score * (1 + 0.5 * weight)`, with `weight` a ranking weight in (0, 1]
+ built so frequency stays visible among recently used skills: the
+ skill's recency decay (the same 30-day half-life curve the usage
+ report shows, measured from its last dated invocation) times
+ `log(1 + count) / log(1 + maxCount)`, where `count` is the skill's
+ deduplicated invocation count and `maxCount` the largest count among
+ the usage rows that join a discovered skill. A skill invoked hundreds
+ of times this week therefore outranks one invoked once yesterday,
+ where the usage report's decay value saturates at 1 for both and the
+ name tie-break would decide; when every joined count is 1 the ratio is
+ 1 everywhere and the ordering is recency alone. A skill still never
+ rises by more than half again its own lexical score, so a wide
+ relevance gap stays decisive and the floor is never crossed by weight.
+ Equal composites resolve by name ascending,
+ and the returned `score` stays the untouched lexical score. Usage
+ joins onto the discovered skills by name, deterministically and
+ without a word list: a `skill_invoked` record whose skill string
+ equals a discovered name joins exactly, a plugin-qualified invocation
+ (`vendor:name`, the shape the Claude Code `Skill` tool records) joins
+ through the longest suffix after a colon that names a discovered
+ skill, and a key matching nothing is dropped - unknown is never
+ guessed onto a nearest-looking name. Private records never count: the
+ continuity read drops `private` rows the same way every reader does.
+ The count is also unscoped: every `skill_invoked` record counts,
+ whichever agent or owner produced it, so at a remote or shared reach
+ the ordering reflects other owners' activity, not only yours. With
+ the flag off - or on, in a vault with no usage records - the
+ offer is byte-identical to the lexical order. The cost of opting in
+ is one whole-continuity-store read per attach call - a scan of every
+ `skill_invoked` record, so it grows with the invocation history (the
+ same read `o2b brain skill-proposals usage` already prices); it is
+ not memoized, because the append-only store exposes no cheap signal a
+ cache could invalidate on, and a stale ordering would be worse than a
+ slow one. A bounded trailing window is a documented follow-up, not
+ shipped.
## Workspace Insight Suite tools (since v0.38.0)
diff --git a/docs/observability.md b/docs/observability.md
index 6f5c3a5a..19c5d965 100644
--- a/docs/observability.md
+++ b/docs/observability.md
@@ -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. 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.
+- `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. Since v1.83.0 the capability set also declares `sampling`, and `--sample-seed <value>` plus `--sample-cap <n>` (a pair - either alone is refused by name; a non-positive or non-integer cap is refused naming the value; a suite without the capability is refused naming the suite, and longmemeval is the only one that has it) run a seeded, question-type-proportional subset of the dataset instead of the whole fixture: abstention questions are excluded first and their count still lands in `abstention_excluded`, the survivors are stratified by the dataset's own `question_type` values, each stratum contributes its population-proportional share of the cap by largest-remainder apportionment (remainders compared as integers, ties by stratum name), and the draw is a seeded shuffle over entries sorted by question id - no wall clock, no `Math.random` - so dataset file order cannot change the subset and the same seed and cap always select the same questions. Sampling happens before conversion, so a sampled run materializes notes and continuity records only for the questions it scores. A sampled run's `--json` report carries the sampling receipt in its `longmemeval` family: `sample_population`, `sample_selected` and the per-stratum `sample_strata` sit beside `abstention_excluded`, each present only on a sampled run and absent from a whole-dataset report, and the human `longmemeval` report line gains `sample_selected N` only on a sampled run; the seed and cap fold into the run identity with the same spread-omission the floor uses: run ids of runs without sampling are byte-stable, and a resumed run whose sampling options changed fails the identity guard by name (the guard's message names the sampling options beside the pinned knobs and the floor).
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/docs/updating.md b/docs/updating.md
index 312d6791..1af0b6d0 100644
--- a/docs/updating.md
+++ b/docs/updating.md
@@ -47,6 +47,33 @@ instruction files such as `CLAUDE.md`/`AGENTS.md`, installed
`.claude/skills/`) and warns with the exact replacement for any stale
reference it finds (`removed-tool-reference`).
+## Upgrading to 1.83.0
+
+Nothing below needs a migration step. Every new surface in this release
+- the per-source-session search pool cap, the usage-ordered skill
+offers, the seeded LongMemEval sampling flags - ships default off and
+is byte-identical when off, so an existing install behaves exactly as
+before until an operator opts in. The one exception is written here
+rather than left to be discovered at the terminal.
+
+**The first `o2b install --check --target opencode` after the host
+writes an `mcp.servers` object reports `drift`, and the first re-apply
+is refused.** OpenCode V2 hosts read the native `mcp.servers` config
+shape, and the opencode adapter now registers there when that object
+exists instead of always writing the legacy top-level `mcp` key. An
+install that never sees an `mcp.servers` object is unaffected - the
+legacy shape stays byte for byte what earlier releases wrote. When the
+host (or the operator) adds the object to a config this integration
+previously owned, verification - which works by re-construction - no
+longer reproduces what is on disk, so the check drifts once; and the
+first apply after that is refused by the hand-edited-file guard rather
+than silently overwriting a file something else just changed. **Fix:**
+`o2b install --target opencode --apply --force` (or `o2b update
+--force`). The forced re-apply registers the two servers under
+`mcp.servers` and removes the shadowed legacy copies of its own two
+keys from the top-level block; user-authored config is never touched.
+Details in [`install/opencode.md`](../install/opencode.md#config-shape-since-v1830).
+
## Upgrading to 1.76.0
No step is required. Searches and session starts now keep the search
diff --git a/install/opencode.md b/install/opencode.md
index 29acaff3..bb2781ba 100644
--- a/install/opencode.md
+++ b/install/opencode.md
@@ -4,11 +4,19 @@
in one pass:
1. **MCP servers** - merges the two Open Second Brain servers
- (`open-second-brain`, `open-second-brain-writer`) into
- `${XDG_CONFIG_HOME:-$HOME/.config}/opencode/opencode.json` under the
- `mcp` key, using opencode's entry schema
- (`{"type": "local", "command": [...], "environment": {...},
- "enabled": true}`). User-authored entries are preserved.
+ (`open-second-brain`, `open-second-brain-writer`) into the opencode
+ config (`${XDG_CONFIG_HOME:-$HOME/.config}/opencode/opencode.json`,
+ or `opencode.jsonc` when that is the only config file present),
+ using opencode's entry schema (`{"type": "local", "command": [...],
+ "environment": {...}, "enabled": true}`; at the native V2
+ `mcp.servers` shape the entry instead carries `"disabled": false`,
+ since V2 replaces the `enabled` field with `disabled`).
+ User-authored entries are preserved. Since v1.83.0 the entry lands
+ under the native V2 `mcp.servers` key when the config already
+ carries that object; everything else keeps the legacy top-level
+ `mcp` key (see [Config shape](#config-shape-since-v1830)). A
+ `.jsonc` config is edited through a comment-preserving editor, so
+ operator comments survive byte for byte.
2. **Plugin** - copies the bundled Open Second Brain plugin into
`${XDG_CONFIG_HOME:-$HOME/.config}/opencode/plugins/open-second-brain.ts`.
opencode auto-loads it at startup.
@@ -40,6 +48,46 @@ shared multi-device vault, per device - rather than logged under the shared
identity. `apply` stamps this on `VAULT_AGENT_NAME` in `opencode.json`; no
manual step is needed.
+## Config shape (since v1.83.0)
+
+OpenCode V2 hosts read the native `mcp.servers` shape and `.jsonc`
+config files, and the adapter writes both without disturbing what is
+already there. Which shape an install targets is a property of the
+on-disk file, not of the host version: a config that carries an
+`mcp.servers` object is written at the native path, and every other
+config keeps the legacy top-level `mcp` key this integration has always
+written. Apply and verify resolve the shape through the same rule, so a
+fresh install never reports drift against itself.
+
+- **File choice.** When only `opencode.jsonc` exists it is the config
+ path, and edits preserve its comments and formatting byte for byte
+ outside the changed entry (the editor splices at token offsets rather
+ than re-serializing the file). When both files exist, or neither, the
+ behavior is unchanged: `opencode.json` wins, and a fresh install
+ still creates it - both host generations read it. With both files on
+ disk, Open Second Brain services `opencode.json` alone and leaves
+ `opencode.jsonc` untouched. Upstream does not document whether V2
+ merges the two files or still reads the legacy top-level `mcp` key,
+ so the install resolves the shape from the `.json` file alone and
+ assumes that file is the one the host reads.
+- **Legacy is never shadowed.** An existing healthy top-level
+ registration is not migrated when `mcp.servers` appears: V2 hosts
+ keep reading a legacy declaration, so migration would churn every
+ install for zero benefit.
+- **Uninstall is shape-aware.** The install manifest records the key
+ each write actually used (`mcp.<name>` or `mcp.servers.<name>`), and
+ uninstall removes exactly those keys - never user-authored entries -
+ under either shape.
+- **One-time drift on a shape change.** When an `mcp.servers` object
+ appears in a config the adapter previously owned at the top level
+ (typically the host writing its own object during an upgrade), the
+ first `o2b install --check --target opencode` reports drift once, and
+ the first re-apply is refused through the hand-edited-file guard.
+ **Fix:** `o2b install --target opencode --apply --force` (or
+ `o2b update --force`). That re-apply registers the servers at the
+ native path and cleans the shadowed legacy copies of its own two keys
+ from the top-level block; user keys are never touched.
+
## What the plugin does
- **Active context inject** - appends the rendered `Brain/active.md`
diff --git a/openclaw.plugin.json b/openclaw.plugin.json
index 0c15e40f..c0dff85e 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.82.0",
+ "version": "1.83.0",
"activation": { "onStartup": true },
"skills": ["./skills"],
"contracts": {
diff --git a/openclaw/index.js b/openclaw/index.js
index ad9cd916..b2738582 100644
--- a/openclaw/index.js
+++ b/openclaw/index.js
@@ -2299,6 +2299,7 @@ __export(exports_config, {
resolveSharedNamespace: () => resolveSharedNamespace,
resolveSkillAutoAttach: () => resolveSkillAutoAttach,
resolveSkillsAttachTriggers: () => resolveSkillsAttachTriggers,
+ resolveSkillsAttachUsageOrdering: () => resolveSkillsAttachUsageOrdering,
resolveSkillsDir: () => resolveSkillsDir,
resolveTelegramBotToken: () => resolveTelegramBotToken,
resolveTelegramCaptureAllowlist: () => resolveTelegramCaptureAllowlist,
@@ -2606,6 +2607,9 @@ function resolveSkillsAttachTriggers(configPath) {
function resolveSkillAutoAttach(configPath) {
return resolveConfigFlag("OPEN_SECOND_BRAIN_SKILL_AUTO_ATTACH", "skill_auto_attach", configPath);
}
+function resolveSkillsAttachUsageOrdering(configPath) {
+ return resolveConfigFlag("OPEN_SECOND_BRAIN_SKILLS_ATTACH_USAGE_ORDERING", "skills_attach_usage_ordering", configPath);
+}
function resolveSearchFocusContextPack(configPath) {
return resolveConfigFlag("OPEN_SECOND_BRAIN_SEARCH_FOCUS_CONTEXT_PACK", "search_focus_context_pack", configPath);
}
diff --git a/package.json b/package.json
index c5c3309a..294c7e2e 100644
--- a/package.json
+++ b/package.json
@@ -1,6 +1,6 @@
{
"name": "open-second-brain",
- "version": "1.82.0",
+ "version": "1.83.0",
"private": false,
"description": "Second brain for AI agents using Obsidian-compatible Markdown vaults. Works with Hermes, Claude Code, Codex, and OpenClaw.",
"keywords": [
diff --git a/plugin.yaml b/plugin.yaml
index a78a7822..83ff955f 100644
--- a/plugin.yaml
+++ b/plugin.yaml
@@ -1,5 +1,5 @@
name: open-second-brain
-version: "1.82.0"
+version: "1.83.0"
description: "Open Second Brain - native Hermes memory provider backed by an Obsidian-compatible Markdown vault."
author: "Open Second Brain contributors"
memory_provider: true
diff --git a/plugins/codex/.codex-plugin/plugin.json b/plugins/codex/.codex-plugin/plugin.json
index 842c0b59..8f0639b0 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.82.0",
+ "version": "1.83.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.md
index 9bb971bf..53b88dda 100644
--- a/plugins/codex/README.md
+++ b/plugins/codex/README.md
@@ -98,7 +98,7 @@ 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; 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).
+- **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; and an opt-in per-source-session cap (`search_pool_max_per_session`, default off) keeps one long imported session from filling the candidate window, so diversity spreads across sessions: [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), [pool cap](https://github.com/itechmeat/open-second-brain/blob/main/docs/cli-reference.md#the-per-source-session-pool-cap-since-v1830), [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).
@@ -123,7 +123,7 @@ The full router with readiness criteria is [`install.md`](https://github.com/ite
## What is new
-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).
+1.83.0 wires four shipped seams, each an opt-in that is byte-identical when off. Search can cap how many rows one source import session holds in the reranker-facing candidate window (`search_pool_max_per_session` / `OPEN_SECOND_BRAIN_SEARCH_POOL_MAX_PER_SESSION`, default `0`): the cap sits after the relevance floor and before the MMR diversity rerank and widens the pool rather than truncating it, so a long imported session stops crowding out everything else, while a vault without session frontmatter never sees a difference. `skills_attach` can order its offers by observed invocation usage (`skills_attach_usage_ordering` / `OPEN_SECOND_BRAIN_SKILLS_ATTACH_USAGE_ORDERING`, default off): a bounded composite, `score * (1 + 0.5 * weight)`, lifts a daily skill over a slightly hotter one-off without ever crossing the discriminating-term floor; plugin-qualified invocation names join discovered skills through a deterministic longest-suffix rule, private records never count, and the returned scores stay lexical. `o2b brain bench memory --suite longmemeval` accepts `--sample-seed` plus `--sample-cap` to score a seeded, question-type-proportional subset of the dataset instead of the whole file - deterministic given the seed, immune to dataset file order, receipt-reported (`sample_population` / `sample_selected` / `sample_strata`), and folded into the run identity so a resumed run whose sampling options changed fails the identity guard by name. The opencode install learns OpenCode V2's native `mcp.servers` config shape and `.jsonc` config files: comment-bearing files are edited byte-preserving, the legacy top-level shape stays untouched, and a one-time drift after the host adds `mcp.servers` is documented with its fix. Every release is described in the [CHANGELOG](https://github.com/itechmeat/open-second-brain/blob/main/CHANGELOG.md).
## Documentation
diff --git a/plugins/hermes/plugin.yaml b/plugins/hermes/plugin.yaml
index a78a7822..83ff955f 100644
--- a/plugins/hermes/plugin.yaml
+++ b/plugins/hermes/plugin.yaml
@@ -1,5 +1,5 @@
name: open-second-brain
-version: "1.82.0"
+version: "1.83.0"
description: "Open Second Brain - native Hermes memory provider backed by an Obsidian-compatible Markdown vault."
author: "Open Second Brain contributors"
memory_provider: true
diff --git a/pyproject.toml b/pyproject.toml
index c2340d61..5984d1e9 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.82.0"
+version = "1.83.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.ts
index 12deaa1f..69a1ef32 100644
--- a/src/cli/brain/help-text.ts
+++ b/src/cli/brain/help-text.ts
@@ -1431,10 +1431,17 @@ export const VERB_HELP: Record<string, string> = {
"mine [--repo K] surface decision-shaped commits as draft ADR\n" +
"candidate notes under Brain/decisions/candidates/ (skip-existing).",
bench:
- "usage: o2b brain bench memory --fixture <name|path> [--resume <run-id>] [--runs-dir <dir>] [--json]\n" +
+ "usage: o2b brain bench memory --fixture <name|path> [--suite <name>]\n" +
+ " [--pin <json>] [--recall-floor <n>] [--sample-seed <value>]\n" +
+ " [--sample-cap <n>] [--resume <run-id>] [--runs-dir <dir>] [--json]\n" +
"Memory quality benchmark over a disposable fixture vault under the\n" +
"runs directory (never the configured vault). Reports quality,\n" +
"latency, and context cost separately; checkpoint/resume by run id;\n" +
"bench_judge_cmd arms the optional external judge. Exit 1 on any\n" +
- "failed question.\n",
+ "failed question.\n" +
+ "--sample-seed V --sample-cap N with a sampling-capable suite\n" +
+ "(longmemeval): run a seeded, question-type-proportional subset of\n" +
+ "the dataset instead of the whole fixture. Both flags are required\n" +
+ "together and fold into the run identity, so a resumed run whose\n" +
+ "sampling options changed fails the identity guard.\n",
};
diff --git a/src/cli/brain/verbs/bench.ts b/src/cli/brain/verbs/bench.ts
index fa5b3a2e..38303756 100644
--- a/src/cli/brain/verbs/bench.ts
+++ b/src/cli/brain/verbs/bench.ts
@@ -20,6 +20,7 @@ import { loadReplayBenchFixture } from "../../../core/bench/replay.ts";
import { runMemoryBench } from "../../../core/bench/phases.ts";
import type {
BenchPinnedKnobs,
+ BenchSampleRequest,
BenchSuiteLoad,
BenchSuiteRegistration,
} from "../../../core/bench/types.ts";
@@ -28,7 +29,8 @@ import { CliError, fail, parse } from "../helpers.ts";
const USAGE =
"usage: o2b brain bench memory --fixture <name|path> [--suite <name>] [--pin <json>] " +
- "[--recall-floor <n>] [--resume <run-id>] [--runs-dir <dir>] [--json]";
+ "[--recall-floor <n>] [--sample-seed <value>] [--sample-cap <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");
@@ -66,7 +68,7 @@ const BENCH_SUITES = new Map<string, BenchSuiteRegistration>([
LONGMEMEVAL_SUITE_NAME,
Object.freeze({
loader: loadLongMemEvalFixture,
- capabilities: Object.freeze({ embeddings: true }),
+ capabilities: Object.freeze({ embeddings: true, sampling: true }),
}),
],
[
@@ -196,6 +198,7 @@ const BENCH_PIN_NESTED_KEYS: Readonly<Record<string, ReadonlyArray<string>>> = {
"iterativeRecallEnabled",
"iterativeRecallMaxRounds",
"poolMultiplier",
+ "poolMaxPerSession",
"selfTuningEnabled",
"chainStopEnabled",
"chainStopScore",
@@ -287,6 +290,40 @@ export function parseRecallFloorFlag(raw: string | undefined): number | undefine
return value;
}
+/**
+ * Parse the `--sample-seed` value: absent keeps the whole-dataset load;
+ * present it must be a non-empty string and pairs with `--sample-cap`.
+ * The seed is opaque - the sampler hashes it, so any string works and
+ * none is ever interpolated into a run id. The value is passed through
+ * UNTRIMMED on purpose: the sampler trims the seed in one place before
+ * hashing, so the CLI and the API path hash the same value for the same
+ * input. This surface only refuses a blank value by name, before any
+ * run state is created.
+ */
+export function parseSampleSeedFlag(raw: string | undefined): string | undefined {
+ if (raw === undefined) return undefined;
+ if (raw.trim() === "") {
+ throw new CliError(
+ `brain bench memory: --sample-seed must be a non-empty string, got '${raw}'`,
+ );
+ }
+ return raw;
+}
+
+/**
+ * Parse the `--sample-cap` value: absent keeps the whole-dataset load;
+ * present it must be a positive integer - the bound on selected
+ * questions - and pairs with `--sample-seed`.
+ */
+export function parseSampleCapFlag(raw: string | undefined): number | undefined {
+ if (raw === undefined) return undefined;
+ const value = Number(raw);
+ if (raw.trim() === "" || !Number.isInteger(value) || value <= 0) {
+ throw new CliError(`brain bench memory: --sample-cap must be a positive integer, 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), {
@@ -294,6 +331,8 @@ export async function cmdBrainBench(argv: string[]): Promise<number> {
suite: { type: "string" },
pin: { type: "string" },
"recall-floor": { type: "string" },
+ "sample-seed": { type: "string" },
+ "sample-cap": { type: "string" },
resume: { type: "string" },
"runs-dir": { type: "string" },
json: { type: "boolean" },
@@ -318,10 +357,39 @@ export async function cmdBrainBench(argv: string[]): Promise<number> {
);
}
+ // Sampling flags are LOADER options: validated (pair, values,
+ // capability) before the registry dispatch, so a refused request never
+ // reaches a loader and a sampling-capable loader receives
+ // `BenchSuiteLoadOptions { sample }`.
+ const sampleSeed = parseSampleSeedFlag(
+ typeof flags["sample-seed"] === "string" ? flags["sample-seed"] : undefined,
+ );
+ const sampleCap = parseSampleCapFlag(
+ typeof flags["sample-cap"] === "string" ? flags["sample-cap"] : undefined,
+ );
+ if ((sampleSeed === undefined) !== (sampleCap === undefined)) {
+ const loneFlag = sampleSeed !== undefined ? "--sample-seed" : "--sample-cap";
+ return fail(
+ "brain bench memory: --sample-seed and --sample-cap must be given together " +
+ `(sampling takes a seed and a cap; got only ${loneFlag})`,
+ );
+ }
+ const sample: BenchSampleRequest | undefined =
+ sampleSeed !== undefined && sampleCap !== undefined
+ ? { seed: sampleSeed, cap: sampleCap }
+ : undefined;
+ if (sample !== undefined && registration.capabilities.sampling !== true) {
+ return fail(
+ "brain bench memory: --sample-seed/--sample-cap need a suite that declares the " +
+ "sampling capability; " +
+ (suite === "" ? "no --suite was given" : `suite '${suite}' does not declare it`),
+ );
+ }
+
// 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 loaded = registration.loader(fixturePath, sample === undefined ? {} : { sample });
const fixture = loaded.fixture;
const runsDir = resolve(
typeof flags["runs-dir"] === "string" && flags["runs-dir"].trim() !== ""
@@ -346,6 +414,7 @@ export async function cmdBrainBench(argv: string[]): Promise<number> {
capabilities: registration.capabilities,
...(pinnedKnobs !== null ? { pinnedKnobs } : {}),
...(recallFloor !== undefined ? { recallFloor } : {}),
+ ...(sample !== undefined ? { sample } : {}),
...(loaded.receipt !== undefined ? { suiteReceipt: loaded.receipt } : {}),
...(resume !== undefined && resume !== "" ? { resume } : {}),
...(judgeCmd !== undefined ? { judgeCmd } : {}),
@@ -371,7 +440,16 @@ export async function cmdBrainBench(argv: string[]): Promise<number> {
if (report.longmemeval !== undefined) {
process.stdout.write(
`longmemeval: recall_all@5 ${report.longmemeval.recall_all_at_5} ` +
- `abstention_excluded ${report.longmemeval.abstention_excluded}\n`,
+ `abstention_excluded ${report.longmemeval.abstention_excluded}` +
+ // Present only on a sampled run, so the whole-dataset line is
+ // byte-identical to before. The population rides beside the
+ // selected count, so the line shows the share of the dataset
+ // the run covers (both fields are written together by the one
+ // spread site that emits the sampled family).
+ (report.longmemeval.sample_selected !== undefined
+ ? ` sample_population ${report.longmemeval.sample_population} sample_selected ${report.longmemeval.sample_selected}`
+ : "") +
+ "\n",
);
}
process.stdout.write(`judge: ${report.judge.status}\n`);
diff --git a/src/core/bench/longmemeval-sample.ts b/src/core/bench/longmemeval-sample.ts
new file mode 100644
index 00000000..1c823aaa
--- /dev/null
+++ b/src/core/bench/longmemeval-sample.ts
@@ -0,0 +1,273 @@
+/**
+ * Seeded, question-type-proportional sampling for the LongMemEval suite
+ * (wiring-shipped-seams wave, t_4501c662).
+ *
+ * The LongMemEval lane runs its dataset wholesale, and the full official
+ * files carry hundreds of questions per run. This module selects a
+ * DETERMINISTIC subset so a bench run can trade coverage for cost
+ * without losing the type balance the benchmark's aggregate is computed
+ * over: the survivors of abstention exclusion are stratified by their
+ * present `question_type` values, a cap is apportioned across strata by
+ * largest remainder (ties broken by stratum name), and each stratum
+ * contributes its share, chosen by a seeded shuffle.
+ *
+ * Determinism contract: no Math.random, no wall clock, no fs. The
+ * selection is a pure function of (entries, seed, cap). Entries are
+ * sorted by question id before the PRNG is touched, so dataset file
+ * order cannot change the subset; the PRNG is a mulberry32 stream keyed
+ * by the sha256 of the TRIMMED seed string. The seed is normalized in
+ * exactly one place - HERE, before the digest - so the same input
+ * selects the same subset whatever surface (CLI or API) passed it:
+ * callers may refuse a blank seed early to name their own surface, but
+ * must not trim or otherwise transform the value. The same options
+ * always select the same subset; a different seed or cap selects a
+ * different one.
+ *
+ * The abstention rule lives here rather than in longmemeval.ts because
+ * abstention exclusion must happen BEFORE selection, and this module
+ * must not import the suite adapter - the adapter imports this module,
+ * so the reverse edge would close a cycle. longmemeval.ts re-exports
+ * the predicate and its constant, leaving the suite's public API
+ * unchanged.
+ *
+ * An all-abstention (or empty) population, a duplicated question id -
+ * which would make the selection depend on dataset file order - and a
+ * malformed option raise the named {@link LongMemEvalSampleError},
+ * never a silent wholesale run.
+ */
+
+import { sha256Hex } from "../integrity/digest.ts";
+
+/**
+ * The explicit question type whose entries measure abstention. Shared
+ * with the suite adapter, which re-exports it.
+ */
+export const LONGMEMEVAL_ABSTENTION_TYPE = "abstention";
+
+/** Suffix the official dataset puts on abstention question ids. */
+const OFFICIAL_ABSTENTION_SUFFIX = "_abs";
+
+/** The entry shape sampling reads; the suite's full entry satisfies it. */
+export interface LongMemEvalSampleEntry {
+ readonly q_id: string;
+ readonly question_type: string;
+}
+
+/**
+ * True when an entry measures abstention and is excluded from scoring.
+ * The official dataset marks abstention by a question id ending in
+ * {@link OFFICIAL_ABSTENTION_SUFFIX}; the legacy sample shape uses the
+ * explicit {@link LONGMEMEVAL_ABSTENTION_TYPE} question type. Both
+ * paths stay live, and both are excluded before any selection runs.
+ */
+export function isLongMemEvalAbstention(entry: LongMemEvalSampleEntry): boolean {
+ return (
+ entry.question_type === LONGMEMEVAL_ABSTENTION_TYPE ||
+ entry.q_id.endsWith(OFFICIAL_ABSTENTION_SUFFIX)
+ );
+}
+
+/** Sampling options: an opaque seed string and a positive integer cap. */
+export interface LongMemEvalSampleOptions {
+ readonly seed: string;
+ readonly cap: number;
+}
+
+/** One stratum's population and selected count, for the receipt. */
+export interface LongMemEvalSampleStratum {
+ readonly question_type: string;
+ readonly population: number;
+ readonly selected: number;
+}
+
+/**
+ * What one sampling decision decided, surfaced beside the selected
+ * entries so a report can state what a run measured instead of letting
+ * a reader assume the whole dataset was scored.
+ */
+export interface LongMemEvalSampleReceipt {
+ /** Entries excluded as abstention before any selection ran. */
+ readonly abstention_excluded: number;
+ /** Survivors the sampler chose from. */
+ readonly population: number;
+ /** Entries selected: min(cap, population). */
+ readonly selected: number;
+ /** One row per present question type, sorted by name ascending. */
+ readonly strata: ReadonlyArray<LongMemEvalSampleStratum>;
+}
+
+export interface LongMemEvalSampleSelection<E> {
+ readonly entries: ReadonlyArray<E>;
+ readonly receipt: LongMemEvalSampleReceipt;
+}
+
+/**
+ * The sampler's named error: a population that is empty once abstention
+ * entries are excluded, a duplicated question id, or a malformed
+ * option. Callers catch it by name; a sampling failure is never
+ * downgraded to a wholesale run.
+ */
+export class LongMemEvalSampleError extends Error {}
+
+/** Hex characters of the seed digest folded into the PRNG state. */
+const SEED_HASH_HEX_CHARS = 8;
+
+/**
+ * A mulberry32 PRNG: 32 bits of state, a multiply-shift per draw,
+ * identical output for a given state on every platform.
+ */
+function mulberry32(state: number): () => number {
+ let current = state >>> 0;
+ return () => {
+ current = (current + 0x6d2b79f5) | 0;
+ let t = current;
+ t = Math.imul(t ^ (t >>> 15), t | 1);
+ t ^= t + Math.imul(t ^ (t >>> 7), t | 61);
+ return ((t ^ (t >>> 14)) >>> 0) / 4294967296;
+ };
+}
+
+/** Key the PRNG state from the seed string through the shared digest. */
+function prngState(seed: string): number {
+ return Number.parseInt(sha256Hex(seed).slice(0, SEED_HASH_HEX_CHARS), 16) >>> 0;
+}
+
+/** Fisher-Yates over a copy; the input array is never mutated. */
+function shuffled<E>(items: ReadonlyArray<E>, random: () => number): E[] {
+ const out = [...items];
+ for (let i = out.length - 1; i > 0; i -= 1) {
+ const j = Math.floor(random() * (i + 1));
+ const swapped = out[i]!;
+ out[i] = out[j]!;
+ out[j] = swapped;
+ }
+ return out;
+}
+
+/**
+ * Select a seeded, type-proportional subset of LongMemEval entries.
+ *
+ * Abstention entries are excluded first (their count rides the
+ * receipt), the survivors are stratified by their present
+ * `question_type` values, the cap is apportioned across strata by
+ * largest remainder with ties broken by stratum name, and each stratum
+ * contributes its share chosen by the seeded shuffle. The selected
+ * entries come back in canonical question-id order whatever order the
+ * dataset carried.
+ *
+ * Raises {@link LongMemEvalSampleError} for a malformed option, a
+ * duplicated question id, or a population that is empty once
+ * abstention entries are excluded.
+ */
+export function sampleLongMemEvalEntries<E extends LongMemEvalSampleEntry>(
+ entries: ReadonlyArray<E>,
+ opts: LongMemEvalSampleOptions,
+): LongMemEvalSampleSelection<E> {
+ if (!Number.isInteger(opts.cap) || opts.cap <= 0) {
+ throw new LongMemEvalSampleError(
+ `LongMemEval sample cap must be a positive integer, got ${opts.cap}`,
+ );
+ }
+ // The seed is normalized in exactly one place - here, before the
+ // digest: it is trimmed, so the CLI (which passes the operator's
+ // value through untransformed) and the API path hash the same value
+ // for the same input. The raw value is echoed in the error so an
+ // operator sees what they actually typed.
+ const seed = opts.seed.trim();
+ if (seed === "") {
+ throw new LongMemEvalSampleError(
+ `LongMemEval sample seed must be a non-empty string, got '${opts.seed}'`,
+ );
+ }
+ const eligible = entries.filter((entry) => !isLongMemEvalAbstention(entry));
+ const abstentionExcluded = entries.length - eligible.length;
+ if (eligible.length === 0) {
+ throw new LongMemEvalSampleError(
+ `LongMemEval dataset: every one of the ${abstentionExcluded} question(s) is an abstention entry and was excluded before sampling; nothing remains to select`,
+ );
+ }
+ // Duplicated question ids would make the selection below depend on
+ // dataset file order; the converter refuses duplicates at conversion
+ // time, and the sampler refuses them here, before any order-sensitive
+ // step runs.
+ const seen = new Set<string>();
+ for (const entry of eligible) {
+ if (seen.has(entry.q_id)) {
+ throw new LongMemEvalSampleError(
+ `LongMemEval dataset: question id '${entry.q_id}' appears twice; the sampled selection would depend on dataset file order`,
+ );
+ }
+ seen.add(entry.q_id);
+ }
+
+ // File order is erased before the PRNG is touched: one canonical
+ // order by question id, strata keyed off it.
+ const sorted = [...eligible].toSorted((a, b) => (a.q_id < b.q_id ? -1 : a.q_id > b.q_id ? 1 : 0));
+ const byStratum = new Map<string, E[]>();
+ for (const entry of sorted) {
+ const bucket = byStratum.get(entry.question_type);
+ if (bucket === undefined) byStratum.set(entry.question_type, [entry]);
+ else bucket.push(entry);
+ }
+ const stratumNames = [...byStratum.keys()].toSorted();
+ const populationByStratum = stratumNames.map((name) => byStratum.get(name)!.length);
+ const total = sorted.length;
+ const effectiveCap = Math.min(opts.cap, total);
+
+ // Largest-remainder apportionment: integer quotas first, then the
+ // surplus seats go to the largest remainders, compared as INTEGER
+ // remainders ((cap*pop) mod total). Two mathematically equal
+ // fractional remainders can differ as doubles (total 6, cap 2: pop 1
+ // computes 0.3333333333333333, pop 4 computes 0.33333333333333326),
+ // which would silently defeat the documented tie-break. Exact integer
+ // ties break to the lexicographically first stratum. With the cap
+ // clamped to the population every quota is at most its stratum's
+ // size, so a surplus seat never overflows a stratum.
+ const base = populationByStratum.map((pop) => Math.floor((effectiveCap * pop) / total));
+ const remainderOrder = stratumNames
+ .map((name, i) => ({
+ name,
+ remainder: (effectiveCap * populationByStratum[i]!) % total,
+ }))
+ .toSorted((a, b) =>
+ a.remainder !== b.remainder ? b.remainder - a.remainder : a.name < b.name ? -1 : 1,
+ );
+ const selectedByStratum = new Map<string, number>(
+ stratumNames.map((name, i) => [name, base[i]!]),
+ );
+ let surplus = effectiveCap - base.reduce((sum, value) => sum + value, 0);
+ for (const { name } of remainderOrder) {
+ if (surplus === 0) break;
+ selectedByStratum.set(name, selectedByStratum.get(name)! + 1);
+ surplus -= 1;
+ }
+
+ // Every stratum is shuffled in name order, so the PRNG stream's draw
+ // count depends only on the populations - never on the cap. The PRNG
+ // is keyed by the trimmed seed (the one normalization point above).
+ const random = mulberry32(prngState(seed));
+ const selected: E[] = [];
+ for (const name of stratumNames) {
+ const pool = shuffled(byStratum.get(name)!, random);
+ selected.push(...pool.slice(0, selectedByStratum.get(name)));
+ }
+ const canonical = selected.toSorted((a, b) => (a.q_id < b.q_id ? -1 : a.q_id > b.q_id ? 1 : 0));
+
+ return {
+ entries: canonical,
+ receipt: Object.freeze({
+ abstention_excluded: abstentionExcluded,
+ population: total,
+ selected: canonical.length,
+ strata: Object.freeze(
+ stratumNames.map((name, i) =>
+ Object.freeze({
+ question_type: name,
+ population: populationByStratum[i]!,
+ selected: selectedByStratum.get(name)!,
+ }),
+ ),
+ ),
+ }),
+ };
+}
diff --git a/src/core/bench/longmemeval.ts b/src/core/bench/longmemeval.ts
index db91761a..4a94a1f0 100644
--- a/src/core/bench/longmemeval.ts
+++ b/src/core/bench/longmemeval.ts
@@ -54,6 +54,13 @@
import { readFileSync } from "node:fs";
import { parseBenchFixture } from "./fixture.ts";
+import {
+ isLongMemEvalAbstention,
+ LONGMEMEVAL_ABSTENTION_TYPE,
+ sampleLongMemEvalEntries,
+} from "./longmemeval-sample.ts";
+import type { LongMemEvalSampleStratum } from "./longmemeval-sample.ts";
+import type { BenchSuiteLoadOptions } from "./types.ts";
import {
RETRIEVAL_CATEGORIES,
type BenchCategory,
@@ -139,6 +146,17 @@ export interface LongMemEvalDataset {
export interface LongMemEvalReceipt {
/** Abstention questions dropped at conversion time. */
readonly abstention_excluded: number;
+ /**
+ * Seeded-sampling bookkeeping, present only when the loader sampled:
+ * the population it chose from, the questions it selected, and the
+ * per-stratum breakdown. Mirrors the abstention precedent - a
+ * whole-dataset run carries no sample fields rather than a
+ * manufactured 0 - and surfaces through the suite receipt the run
+ * reports ({@link BenchSuiteReceipt}).
+ */
+ readonly sample_population?: number;
+ readonly sample_selected?: number;
+ readonly sample_strata?: ReadonlyArray<LongMemEvalSampleStratum>;
}
export interface LongMemEvalConversion {
@@ -148,26 +166,13 @@ export interface LongMemEvalConversion {
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.
+ * The abstention rule lives in the sampler module, whose exclusion of
+ * abstention entries must precede selection and which must stay a leaf
+ * (this adapter imports it); re-exported here so the suite's public
+ * API is unchanged.
*/
-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)
- );
-}
+export { isLongMemEvalAbstention, LONGMEMEVAL_ABSTENTION_TYPE };
/**
* The recall cutoff the suite scores at: a question passes retrieval
@@ -644,8 +649,28 @@ export function longMemEvalToBenchFixture(dataset: LongMemEvalDataset): LongMemE
return { fixture, receipt: { abstention_excluded: abstentionExcluded } };
}
-/** Load a LongMemEval dataset file and convert it to a suite load. */
-export function loadLongMemEvalFixture(path: string): LongMemEvalConversion {
+/**
+ * Load a LongMemEval dataset file and convert it to a suite load.
+ *
+ * The second parameter is OPTIONAL and carries the run's sampling
+ * request: with one, abstention entries are excluded first, the seeded
+ * sampler selects a type-proportional subset of the survivors, and only
+ * the selected entries convert - sampling happens PRE-conversion, so
+ * notes and continuity records materialize just for the questions a run
+ * will score. Without one, the conversion is byte-identical to the
+ * shipped whole-dataset loader.
+ *
+ * The receipt mirrors the abstention precedent: on a sampled run it
+ * carries the sample population, the selected count and the per-stratum
+ * breakdown beside the abstention count, which stays the SAMPLER's
+ * count - the exclusion happened before selection, so the conversion of
+ * the selected entries would otherwise read 0 and hide the dataset's
+ * abstention questions from the report.
+ */
+export function loadLongMemEvalFixture(
+ path: string,
+ options?: BenchSuiteLoadOptions,
+): LongMemEvalConversion {
let raw: unknown;
try {
raw = JSON.parse(readFileSync(path, "utf8"));
@@ -654,7 +679,22 @@ export function loadLongMemEvalFixture(path: string): LongMemEvalConversion {
`LongMemEval dataset not readable JSON at ${path}: ${e instanceof Error ? e.message : String(e)}`,
);
}
- return longMemEvalToBenchFixture(parseLongMemEvalDataset(raw));
+ const dataset = parseLongMemEvalDataset(raw);
+ if (options?.sample === undefined) return longMemEvalToBenchFixture(dataset);
+ const sample = sampleLongMemEvalEntries(dataset.entries, options.sample);
+ const converted = longMemEvalToBenchFixture({
+ ...(dataset.name !== undefined ? { name: dataset.name } : {}),
+ entries: sample.entries,
+ });
+ return {
+ fixture: converted.fixture,
+ receipt: {
+ abstention_excluded: sample.receipt.abstention_excluded,
+ sample_population: sample.receipt.population,
+ sample_selected: sample.receipt.selected,
+ sample_strata: sample.receipt.strata,
+ },
+ };
}
/** One persisted retrieval result the strict metric reads. */
diff --git a/src/core/bench/phases.ts b/src/core/bench/phases.ts
index e2c5e193..73c89a61 100644
--- a/src/core/bench/phases.ts
+++ b/src/core/bench/phases.ts
@@ -64,6 +64,7 @@ import {
type BenchQuestion,
type BenchQuestionResult,
type BenchReport,
+ type BenchSampleRequest,
type BenchSuiteCapabilities,
type BenchSuiteReceipt,
} from "./types.ts";
@@ -117,6 +118,15 @@ export interface BenchRunOptions {
* conversion excluded from scoring.
*/
readonly suiteReceipt?: BenchSuiteReceipt;
+ /**
+ * The seeded sampling request the run's fixture was loaded under.
+ * The CLI samples at load time, so this folds into the run identity
+ * (a resumed run whose sampling options changed fails the guard, even
+ * when a cap at or above the population would make the sampled
+ * fixtures identical) and is refused up front when malformed - it
+ * drives no phase of its own.
+ */
+ readonly sample?: BenchSampleRequest;
readonly now?: Date;
}
@@ -219,6 +229,19 @@ export async function runMemoryBench(opts: BenchRunOptions): Promise<BenchReport
`bench run refused: recallFloor ${opts.recallFloor} is outside [0, 1]; the admission floor must be a finite number in the unit interval`,
);
}
+ // Refused BEFORE any run state exists, on the same principle: the
+ // sampling options are part of the run identity, so a malformed one
+ // must not buy a full run under an identity that could never resume.
+ if (opts.sample !== undefined) {
+ if (!Number.isInteger(opts.sample.cap) || opts.sample.cap <= 0) {
+ throw new Error(
+ `bench run refused: sample cap ${opts.sample.cap} is not a positive integer; the sampling cap bounds the selected questions`,
+ );
+ }
+ if (opts.sample.seed.trim() === "") {
+ throw new Error("bench run refused: sample seed must be a non-empty string");
+ }
+ }
const pinnedKnobs = opts.pinnedKnobs ?? DEFAULT_BENCH_KNOB_PIN;
const run: BenchRunHandle =
opts.resume !== undefined
@@ -226,11 +249,13 @@ export async function runMemoryBench(opts: BenchRunOptions): Promise<BenchReport
expectFixture: opts.fixture,
pinnedKnobs,
...(opts.recallFloor !== undefined ? { recallFloor: opts.recallFloor } : {}),
+ ...(opts.sample !== undefined ? { sample: opts.sample } : {}),
})
: createBenchRun(opts.runsDir, opts.fixture, {
...(opts.now !== undefined ? { now: opts.now } : {}),
pinnedKnobs,
...(opts.recallFloor !== undefined ? { recallFloor: opts.recallFloor } : {}),
+ ...(opts.sample !== undefined ? { sample: opts.sample } : {}),
});
let checkpoint = run.checkpoint;
const vault = benchVaultDir(run.runDir);
@@ -311,13 +336,30 @@ export async function runMemoryBench(opts: BenchRunOptions): Promise<BenchReport
// 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.
+ // one it reports null, never a manufactured 0. The sampled count
+ // rides along only when the run sampled, so a whole-dataset report
+ // serializes byte-identically to before.
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,
+ // The sampled bookkeeping rides the named family when the run
+ // sampled - population, selected count and the per-stratum
+ // breakdown - so a reader can see what the run's numbers cover
+ // without opening the checkpoint. Spread-omitted otherwise: a
+ // whole-dataset (or receipt-less) report serializes
+ // byte-identically to before.
+ ...(opts.suiteReceipt?.sample_population !== undefined
+ ? { sample_population: opts.suiteReceipt.sample_population }
+ : {}),
+ ...(opts.suiteReceipt?.sample_selected !== undefined
+ ? { sample_selected: opts.suiteReceipt.sample_selected }
+ : {}),
+ ...(opts.suiteReceipt?.sample_strata !== undefined
+ ? { sample_strata: opts.suiteReceipt.sample_strata }
+ : {}),
});
}
diff --git a/src/core/bench/run-store.ts b/src/core/bench/run-store.ts
index d5783c4b..b3340453 100644
--- a/src/core/bench/run-store.ts
+++ b/src/core/bench/run-store.ts
@@ -6,10 +6,11 @@
* the final report. Resume validates the fixture hash before skipping
* phases - a changed fixture invalidates the checkpoint rather than
* 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.
+ * knobs, the recall admission floor and the seeded sampling request
+ * ({@link benchRunIdentityHash}), so a resumed run whose pin, floor or
+ * sampling options 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";
@@ -24,6 +25,7 @@ import {
type BenchFixture,
type BenchPhase,
type BenchPinnedKnobs,
+ type BenchSampleRequest,
} from "./types.ts";
export interface BenchRunHandle {
@@ -39,23 +41,30 @@ 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.
+ * AND the recall admission floor (null when unset) AND the seeded
+ * sampling request (spread in only when set), canonically hashed
+ * together. Two runs that differ only in their pin, floor or sampling
+ * options therefore get different run ids - even when the sampled
+ * fixture would be identical, because the options are what the run was
+ * asked to do - and a resumed run whose pin, floor or sampling options
+ * changed fails the identity guard instead of silently comparing two
+ * pipelines - or worse, deciding the remaining questions under new
+ * options while the persisted ones keep the old. The sampling half is
+ * spread-omitted, so a no-sampling record is byte-identical to the
+ * shipped one and every pre-change run id stays stable.
*/
export function benchRunIdentityHash(
fixture: BenchFixture,
pinnedKnobs: BenchPinnedKnobs,
recallFloor?: number,
+ sample?: BenchSampleRequest,
): string {
return sha256Hex(
canonicalJson({
fixture: fixtureHash(fixture),
knobs: pinnedKnobs,
recall_floor: recallFloor ?? null,
+ ...(sample !== undefined ? { sample } : {}),
}),
).slice(0, RUN_IDENTITY_HEX_CHARS);
}
@@ -73,12 +82,17 @@ export function benchResultsDir(runDir: string): string {
export function createBenchRun(
runsDir: string,
fixture: BenchFixture,
- opts: { now?: Date; pinnedKnobs?: BenchPinnedKnobs; recallFloor?: number } = {},
+ opts: {
+ now?: Date;
+ pinnedKnobs?: BenchPinnedKnobs;
+ recallFloor?: number;
+ sample?: BenchSampleRequest;
+ } = {},
): 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 identity = benchRunIdentityHash(fixture, knobs, opts.recallFloor, opts.sample);
const stamp = now
.toISOString()
.replace(/[^0-9]/g, "")
@@ -92,6 +106,7 @@ export function createBenchRun(
fixture_hash: hash,
pinned_knobs: knobs,
knobs_hash: identity,
+ ...(opts.sample !== undefined ? { sample: opts.sample } : {}),
created_at: now.toISOString(),
completed_phases: Object.freeze([]),
});
@@ -106,6 +121,7 @@ export function loadBenchRun(
expectFixture?: BenchFixture;
pinnedKnobs?: BenchPinnedKnobs;
recallFloor?: number;
+ sample?: BenchSampleRequest;
} = {},
): BenchRunHandle {
const runDir = guardedRunDir(runsDir, runId);
@@ -127,10 +143,15 @@ export function loadBenchRun(
`bench run ${runId}: checkpoint predates knob pinning - the run identity cannot be verified, restart the run`,
);
}
- const expectedIdentity = benchRunIdentityHash(opts.expectFixture, knobs, opts.recallFloor);
+ const expectedIdentity = benchRunIdentityHash(
+ opts.expectFixture,
+ knobs,
+ opts.recallFloor,
+ opts.sample,
+ );
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`,
+ `bench run ${runId}: run identity mismatch (checkpoint ${checkpoint.knobs_hash}, current ${expectedIdentity}) - the pinned knobs, the recall floor or the sampling options changed since this run started`,
);
}
}
@@ -172,6 +193,7 @@ function parseCheckpoint(raw: unknown): BenchCheckpoint {
const phases = record["completed_phases"];
const knobsHash = record["knobs_hash"];
const pinnedKnobs = record["pinned_knobs"];
+ const sample = record["sample"];
if (
typeof runId !== "string" ||
typeof fixtureName !== "string" ||
@@ -190,6 +212,12 @@ function parseCheckpoint(raw: unknown): BenchCheckpoint {
) {
throw new Error("bench checkpoint: pinned_knobs must be an object");
}
+ if (
+ sample !== undefined &&
+ (sample === null || typeof sample !== "object" || Array.isArray(sample))
+ ) {
+ throw new Error("bench checkpoint: sample must be an object");
+ }
const completed = phases.filter(
(phase): phase is BenchPhase =>
typeof phase === "string" && (BENCH_PHASES as ReadonlyArray<string>).includes(phase),
@@ -205,6 +233,12 @@ function parseCheckpoint(raw: unknown): BenchCheckpoint {
!Array.isArray(pinnedKnobs)
? { pinned_knobs: Object.freeze({ ...(pinnedKnobs as BenchPinnedKnobs) }) }
: {}),
+ ...(sample !== undefined &&
+ sample !== null &&
+ typeof sample === "object" &&
+ !Array.isArray(sample)
+ ? { sample: Object.freeze({ ...(sample as BenchSampleRequest) }) }
+ : {}),
created_at: createdAt,
completed_phases: Object.freeze(completed),
});
diff --git a/src/core/bench/types.ts b/src/core/bench/types.ts
index 66ebd88e..06c99f0e 100644
--- a/src/core/bench/types.ts
+++ b/src/core/bench/types.ts
@@ -26,6 +26,7 @@ import type {
ResolvedSearchConfig,
} from "../search/types.ts";
import type { VaultScopeRules } from "../vault-scope/defaults.ts";
+import type { LongMemEvalSampleStratum } from "./longmemeval-sample.ts";
export const BENCH_REPORT_SCHEMA = "o2b.bench.v2";
@@ -166,6 +167,36 @@ export interface BenchSuiteCapabilities {
* semantic lane.
*/
readonly embeddings: boolean;
+ /**
+ * Whether the suite's loader accepts a seeded sampling request
+ * ({@link BenchSuiteLoadOptions.sample}). Absent means false: the
+ * sampling flags are refused for such a suite, naming it. Declared
+ * here, honored by the loader - a capability declaration alone is
+ * inert, exactly like {@link BenchSuiteCapabilities.embeddings}.
+ */
+ readonly sampling?: boolean;
+}
+
+/**
+ * A seeded sampling request for one suite load: select a deterministic,
+ * question-type-proportional subset of the dataset instead of running
+ * it whole. The seed is an opaque string (hashed, never interpolated
+ * into run ids); the cap is a positive integer bounding the selected
+ * questions. Part of the run identity: a resumed run whose sampling
+ * options changed fails the identity guard.
+ */
+export interface BenchSampleRequest {
+ readonly seed: string;
+ readonly cap: number;
+}
+
+/**
+ * Options the bench verb passes to a suite loader as its second,
+ * OPTIONAL parameter - a suite registered before an option existed
+ * keeps its one-parameter loader and simply never sees the request.
+ */
+export interface BenchSuiteLoadOptions {
+ readonly sample?: BenchSampleRequest;
}
/**
@@ -182,6 +213,16 @@ export interface BenchSuiteLoad {
export interface BenchSuiteReceipt {
/** LongMemEval-style abstention questions dropped at conversion time. */
readonly abstention_excluded?: number;
+ /**
+ * Seeded-sampling bookkeeping, present only when the loader sampled:
+ * the population it chose from, the questions it selected, and the
+ * per-stratum breakdown. Mirrors the abstention precedent - a
+ * whole-dataset run carries no sample fields rather than a
+ * manufactured 0.
+ */
+ readonly sample_population?: number;
+ readonly sample_selected?: number;
+ readonly sample_strata?: ReadonlyArray<LongMemEvalSampleStratum>;
}
/**
@@ -191,7 +232,7 @@ export interface BenchSuiteReceipt {
* a hard-coded branch chain.
*/
export interface BenchSuiteRegistration {
- readonly loader: (fixturePath: string) => BenchSuiteLoad;
+ readonly loader: (fixturePath: string, options?: BenchSuiteLoadOptions) => BenchSuiteLoad;
readonly capabilities: BenchSuiteCapabilities;
}
@@ -279,6 +320,26 @@ export interface BenchLongMemEvalFamily {
* receipt - the count is then unknown, never a manufactured 0.
*/
readonly abstention_excluded: number | null;
+ /**
+ * Questions the run's seeded sampler selected, taken from the run's
+ * conversion receipt. Present only when the run sampled, so a
+ * whole-dataset (or receipt-less) report serializes byte-identically
+ * to before.
+ */
+ readonly sample_selected?: number;
+ /**
+ * Population the run's seeded sampler chose from, taken from the
+ * run's conversion receipt. Present only when the run sampled, under
+ * the same spread-omission as `sample_selected`.
+ */
+ readonly sample_population?: number;
+ /**
+ * Per-stratum population/selected breakdown of the run's seeded
+ * sample, taken from the run's conversion receipt. Present only when
+ * the run sampled, under the same spread-omission as
+ * `sample_selected`.
+ */
+ readonly sample_strata?: ReadonlyArray<LongMemEvalSampleStratum>;
}
export interface BenchQuestionResult {
@@ -369,6 +430,14 @@ export interface BenchCheckpoint {
*/
readonly pinned_knobs?: BenchPinnedKnobs;
readonly knobs_hash?: string;
+ /**
+ * The seeded sampling request this run was created under, present only
+ * on a sampled run. The run-identity hash covers it, so a resumed run
+ * under different sampling options fails the guard; the field itself
+ * is spread-omitted on unsampled runs, keeping those checkpoints
+ * byte-identical to before.
+ */
+ readonly sample?: BenchSampleRequest;
readonly created_at: string;
readonly completed_phases: ReadonlyArray<BenchPhase>;
}
diff --git a/src/core/brain/skill-usage.ts b/src/core/brain/skill-usage.ts
index 316259a8..1177a67a 100644
--- a/src/core/brain/skill-usage.ts
+++ b/src/core/brain/skill-usage.ts
@@ -21,6 +21,7 @@
import { loadNormalizedContinuityRecords } from "./continuity/read-model.ts";
import { decayWeight } from "./continuity/usage-signal.ts";
+import { clamp01 } from "../math.ts";
import { readSkillOfferId } from "../surface/skill-offer.ts";
export interface SkillUsage {
@@ -148,6 +149,170 @@ export function deriveSkillUsage(vault: string, opts: { nowMs?: number } = {}):
return usage;
}
+/**
+ * Join derived usage rows onto the discovered skill names, for ranking.
+ *
+ * The usage store keys on the raw invocation string (`payload["skill"]`),
+ * which is runtime-dependent: an MCP `get_skill` name equals the discovered
+ * `SkillEntry.name` byte for byte, while a Claude Code `Skill` command
+ * arrives plugin-qualified (`open-second-brain:codegraph-partner`) and never
+ * equals it. The join rule, deterministic and vocabulary-free:
+ *
+ * - a usage key that IS a known name joins exactly, and an exact join
+ * always wins over an inferred one;
+ * - any other key joins the longest suffix after a colon that is a known
+ * name (for `a:b:c`, `b:c` before `c`);
+ * - a key matching nothing is dropped - unknown is unknown, never
+ * guessed onto a nearest-looking name;
+ * - when several rows join the same known name, the higher weight wins,
+ * so the result never depends on row order.
+ *
+ * Pure: the inputs are not mutated and the values are the decay weights
+ * unchanged, so an empty usage list yields an empty map.
+ */
+export function skillUsageWeights(
+ usage: ReadonlyArray<SkillUsage>,
+ knownNames: ReadonlySet<string>,
+): ReadonlyMap<string, number> {
+ const weights = new Map<string, number>();
+ for (const [name, rows] of joinUsageRows(usage, knownNames)) {
+ for (const row of rows) {
+ if ((weights.get(name) ?? 0) < row.weight) weights.set(name, row.weight);
+ }
+ }
+ return weights;
+}
+
+/**
+ * Tunables for {@link skillUsageRankingWeights}. The defaults mirror the
+ * shared decay curve's (`decayWeight`, `./continuity/usage-signal.ts`):
+ * the recency half of the ranking weight is the same curve, so the only
+ * thing the ranking builder changes is how frequency enters.
+ */
+export interface SkillUsageRankingOptions {
+ /** Injected clock, epoch ms. Default `Date.now()`. */
+ readonly nowMs?: number;
+ /** Exponential half-life of the recency decay, in days. Default 30. */
+ readonly halfLifeDays?: number;
+ /** Lower clamp so a weight never reads as zero. Default 0.02. */
+ readonly minWeight?: number;
+}
+
+const DAY_MS = 86_400_000;
+const RANKING_HALF_LIFE_DAYS = 30;
+const RANKING_MIN_WEIGHT = 0.02;
+
+/**
+ * Join usage rows onto the discovered names with a ranking weight that does
+ * not saturate (the t_5d1ec8a8 follow-up to review finding M5).
+ *
+ * Why not {@link skillUsageWeights}: its values are the decay weights, and
+ * that weight is frequency multiplied into an age decay and then CLAMPED at
+ * 1 - a skill invoked once within the last few days and one invoked three
+ * hundred times this week both clamp, tie, and let the name tie-break
+ * decide, so among recently used skills the ordering sees recency only.
+ * This builder keeps the clamp out of the frequency term:
+ *
+ * weight = recency(row) * log1p(count) / log1p(maxCount)
+ *
+ * where `recency(row)` is the shared curve's age half - `0.5 ** (ageDays /
+ * halfLifeDays)` measured from the row's last dated invocation, or 1 when
+ * the row carries no date at all (the same creation-baseline convention the
+ * decay curve applies) - and `maxCount` is the largest invocation count
+ * among the rows that JOIN a known name, so an unjoined heavy row can never
+ * shrink the joined ones. The ratio is 1 for the most-invoked joined row
+ * and falls off logarithmically below it; when every joined count is 1 it
+ * is 1 everywhere and the map is pure recency, so normalisation only
+ * separates, never inverts. The result is clamped to
+ * `[minWeight, 1]` - bounded like the decay weight, but the cap is now
+ * reachable only at full recency, not at one recent invocation.
+ *
+ * Same join rule, purity contract and order-independence as
+ * {@link skillUsageWeights} (several rows on one name: the strongest
+ * normalised weight wins); no I/O, and the clock enters only through the
+ * `nowMs` option, so a pinned input always yields the same map.
+ */
+export function skillUsageRankingWeights(
+ usage: ReadonlyArray<SkillUsage>,
+ knownNames: ReadonlySet<string>,
+ opts: SkillUsageRankingOptions = {},
+): ReadonlyMap<string, number> {
+ const weights = new Map<string, number>();
+ const joined = joinUsageRows(usage, knownNames);
+ if (joined.size === 0) return weights;
+ const nowMs = opts.nowMs ?? Date.now();
+ const halfLifeMs = Math.max(1, (opts.halfLifeDays ?? RANKING_HALF_LIFE_DAYS) * DAY_MS);
+ const minWeight = clamp01(opts.minWeight ?? RANKING_MIN_WEIGHT);
+ let maxCount = 1;
+ for (const rows of joined.values()) {
+ for (const row of rows) maxCount = Math.max(maxCount, row.invocationCount);
+ }
+ const maxLog = Math.log1p(maxCount);
+ for (const [name, rows] of joined) {
+ let best = 0;
+ for (const row of rows) {
+ const frequency = Math.log1p(Math.max(0, row.invocationCount)) / maxLog;
+ best = Math.max(best, recencyFactor(row, nowMs, halfLifeMs) * frequency);
+ }
+ weights.set(name, Math.min(1, Math.max(minWeight, best)));
+ }
+ return weights;
+}
+
+/**
+ * The age half of the shared decay curve for one usage row. Kept beside the
+ * join rather than read back off `SkillUsage.weight` because that export is
+ * the saturated value - the clamp this builder exists to bypass is baked
+ * into it, and the frequency term is not invertible through a clamp.
+ */
+function recencyFactor(row: SkillUsage, nowMs: number, halfLifeMs: number): number {
+ if (row.lastInvokedAtMs === null) return 1;
+ const ageMs = Math.max(0, nowMs - row.lastInvokedAtMs);
+ return Math.pow(0.5, ageMs / halfLifeMs);
+}
+
+/**
+ * Group usage rows by the known name each joins, exact joins before
+ * inferred ones. The shared join rule behind both weight builders; rows
+ * keep their input order inside a group, and a name with an exact join
+ * never receives a suffix row, so neither builder's result can depend on
+ * row order (their per-name reduction is a max).
+ */
+function joinUsageRows(
+ usage: ReadonlyArray<SkillUsage>,
+ knownNames: ReadonlySet<string>,
+): ReadonlyMap<string, ReadonlyArray<SkillUsage>> {
+ const exact = new Set<string>();
+ const joined = new Map<string, SkillUsage[]>();
+ for (const row of usage) {
+ if (!knownNames.has(row.skill)) continue;
+ exact.add(row.skill);
+ const group = joined.get(row.skill);
+ if (group === undefined) joined.set(row.skill, [row]);
+ else group.push(row);
+ }
+ for (const row of usage) {
+ if (knownNames.has(row.skill)) continue;
+ const suffix = suffixKnownName(row.skill, knownNames);
+ if (suffix === null || exact.has(suffix)) continue;
+ const group = joined.get(suffix);
+ if (group === undefined) joined.set(suffix, [row]);
+ else group.push(row);
+ }
+ return joined;
+}
+
+/** Longest suffix of `key` after a colon that is a known name, or null. */
+function suffixKnownName(key: string, knownNames: ReadonlySet<string>): string | null {
+ for (let i = key.indexOf(":"); i !== -1; i = key.indexOf(":", i + 1)) {
+ // Suffixes shrink as the colon index advances, so the first hit is the
+ // longest match.
+ const suffix = key.slice(i + 1);
+ if (knownNames.has(suffix)) return suffix;
+ }
+ return null;
+}
+
/**
* Join invocations back to the offers that produced them.
*
diff --git a/src/core/config.ts b/src/core/config.ts
index e51414b9..810f1bd1 100644
--- a/src/core/config.ts
+++ b/src/core/config.ts
@@ -810,6 +810,23 @@ export function resolveSkillAutoAttach(configPath?: string): boolean {
return resolveConfigFlag("OPEN_SECOND_BRAIN_SKILL_AUTO_ATTACH", "skill_auto_attach", configPath);
}
+/**
+ * Skill-attach usage-ordering gate (Agent Surface Suite, t_5d1ec8a8).
+ * Default OFF: skills_attach ranks purely by the lexical scorer unless
+ * `skills_attach_usage_ordering: "true"` (or the matching env override),
+ * so the default offer ordering stays byte-identical. When on, observed
+ * `skill_invoked` usage reorders lexical near-ties under the bounded
+ * composite in `surface/skill-attach.ts`; the continuity read still only
+ * happens when the auto-attach gate above is on too.
+ */
+export function resolveSkillsAttachUsageOrdering(configPath?: string): boolean {
+ return resolveConfigFlag(
+ "OPEN_SECOND_BRAIN_SKILLS_ATTACH_USAGE_ORDERING",
+ "skills_attach_usage_ordering",
+ configPath,
+ );
+}
+
/**
* Context-pack focus wiring gate (Agent Surface Suite, t_5b478e47).
* Default OFF: brain_context_pack ignores the active search focus
diff --git a/src/core/doctor-readiness.ts b/src/core/doctor-readiness.ts
index 2dafe28c..dfe21d23 100644
--- a/src/core/doctor-readiness.ts
+++ b/src/core/doctor-readiness.ts
@@ -96,10 +96,12 @@ import {
type CommandProbeOutcome,
} from "./install/command-probe.ts";
import { OSB_KEY_FULL, OSB_KEY_WRITER } from "./install/json-merge.ts";
+import { parseJsoncObject } from "./install/jsonc.ts";
import { readManifest } from "./install/manifest.ts";
import { buildPayload } from "./install/payload.ts";
import { defaultRegistry } from "./install/registry.ts";
import { registerAllAdapters } from "./install/adapters/all.ts";
+import { looksLikeServerEntry } from "./install/adapters/opencode.ts";
import {
AGENT_INSTRUCTION_FILES,
WRITEBACK_CONTRACT_FINDING,
@@ -636,9 +638,12 @@ function flattenReason(message: string): string {
/**
* Top-level JSON objects an Open Second Brain MCP registration may live under: the
* json-merge default (`mcpServers` - cursor, kiro, gemini-cli and the
- * generic printout) and opencode's `mcp`.
+ * generic printout), opencode's legacy `mcp`, and opencode V2's native
+ * `mcp.servers` - the one dotted key, resolved through nested objects,
+ * so a healthy V2 install is probed instead of reported as having no
+ * entry.
*/
-const JSON_MCP_TOP_LEVEL_KEYS: ReadonlyArray<string> = ["mcpServers", "mcp"];
+const JSON_MCP_TOP_LEVEL_KEYS: ReadonlyArray<string> = ["mcpServers", "mcp", "mcp.servers"];
/** The Open Second Brain entry names, as JSON keys and as `[mcp_servers.<name>]` tables. */
const OSB_ENTRY_KEYS: ReadonlySet<string> = new Set([OSB_KEY_FULL, OSB_KEY_WRITER]);
@@ -700,7 +705,8 @@ function statusForProbeOutcome(outcome: CommandProbeOutcome): ReadinessStatus {
/**
* What is registered, and does it still resolve? Reads the install
* manifest, re-reads every recorded client config, extracts the Open Second Brain
- * `command`/`args` the install wrote (JSON `mcpServers`/`mcp` keys, or the
+ * `command`/`args` the install wrote (JSON `mcpServers`, opencode's legacy
+ * `mcp`, opencode V2's nested `mcp.servers`, or the
* `[mcp_servers.*]` TOML tables grok and codex write), and probes each
* command word via `command-probe.ts`.
*
@@ -880,10 +886,23 @@ function extractRegisteredCommands(raw: string): CommandExtraction {
return extractFromTomlConfig(raw);
}
+/** Walk a (possibly dotted) key path through parsed JSON objects; null when any hop is missing or not an object. */
+function resolveJsonKeyPath(root: Record<string, unknown>, dottedKey: string): unknown {
+ let current: unknown = root;
+ for (const segment of dottedKey.split(".")) {
+ if (current === null || typeof current !== "object" || Array.isArray(current)) return null;
+ current = (current as Record<string, unknown>)[segment] ?? null;
+ }
+ return current;
+}
+
/**
* Read the Open Second Brain entries out of a JSON client config. Returns `null` when
* the text is not JSON at all, so the TOML reader gets its turn - grok
* and codex record the very same Open Second Brain names as `[mcp_servers.*]` tables.
+ * A JSONC config (opencode V2's `.jsonc`, comments and trailing commas)
+ * parses through the vendored editor; text neither reader accepts is
+ * not JSON.
*/
function extractFromJsonConfig(raw: string): CommandExtraction | null {
// Editors may save a BOM at the head; JSON.parse refuses it (the same
@@ -893,7 +912,11 @@ function extractFromJsonConfig(raw: string): CommandExtraction | null {
try {
parsed = JSON.parse(stripped);
} catch {
- return null;
+ try {
+ parsed = parseJsoncObject(raw);
+ } catch {
+ return null;
+ }
}
if (parsed === null || typeof parsed !== "object" || Array.isArray(parsed)) {
return { kind: "none" };
@@ -901,11 +924,32 @@ function extractFromJsonConfig(raw: string): CommandExtraction | null {
const root = parsed as Record<string, unknown>;
const entries: RegisteredCommandEntry[] = [];
const malformed: string[] = [];
- for (const topKey of JSON_MCP_TOP_LEVEL_KEYS) {
- const block = root[topKey];
+ // The resolved shape's key owns the probe: a V2 file that still holds
+ // legacy top-level copies would otherwise have the same entry name
+ // scanned twice, and a stale legacy copy reported as a broken command
+ // beside its healthy native twin. The native block is scanned alone
+ // when it is present AND is the native map - the same judgment the
+ // opencode adapter's `shapeIsV2` makes (its `looksLikeServerEntry`,
+ // shared here so both readers resolve one file to one shape): a block
+ // carrying type/command/url directly on it is a legacy user server
+ // that happens to be named `servers`, the file keeps the legacy shape,
+ // and the legacy keys are scanned (entry names deduped, first block
+ // wins) instead.
+ const native = resolveJsonKeyPath(root, "mcp.servers");
+ const scanKeys =
+ native !== null &&
+ typeof native === "object" &&
+ !Array.isArray(native) &&
+ !looksLikeServerEntry(native)
+ ? ["mcp.servers"]
+ : JSON_MCP_TOP_LEVEL_KEYS.filter((topKey) => topKey !== "mcp.servers");
+ const seen = new Set<string>();
+ for (const topKey of scanKeys) {
+ const block = resolveJsonKeyPath(root, topKey);
if (block === null || typeof block !== "object" || Array.isArray(block)) continue;
for (const [key, value] of Object.entries(block as Record<string, unknown>)) {
- if (!OSB_ENTRY_KEYS.has(key)) continue;
+ if (!OSB_ENTRY_KEYS.has(key) || seen.has(key)) continue;
+ seen.add(key);
const normalized = normalizeOnDiskEntry(value);
if (normalized === null) malformed.push(`${topKey}.${key}`);
else entries.push({ key, ...normalized });
diff --git a/src/core/install/adapters/opencode.ts b/src/core/install/adapters/opencode.ts
index 7acc4186..f8cbb00a 100644
--- a/src/core/install/adapters/opencode.ts
+++ b/src/core/install/adapters/opencode.ts
@@ -6,7 +6,32 @@
* MCP servers live in `opencode.json` (global copy under
* `${XDG_CONFIG_HOME:-$HOME/.config}/opencode/`) beneath the `mcp` key,
* each entry shaped `{type: "local", command: [bin, ...args],
- * environment?, enabled}`.
+ * environment?, enabled}`. The V2 docs replace the `enabled` field with
+ * `disabled`, so an entry written at the native `mcp.servers` shape
+ * carries `disabled: false` and never `enabled`.
+ *
+ * V2 hosts read the native `mcp.servers` shape and `.jsonc` config
+ * files. The choice is a property of the on-disk file, not of the
+ * machine: a config that carries an `mcp.servers` object is written at
+ * the native path (an existing legacy top-level declaration is never
+ * shadowed), everything else keeps the V1 top-level `mcp` key. Apply
+ * and verify resolve the shape through the same function, so a fresh
+ * install can never report drift against itself. Files bearing JSONC
+ * syntax (comments or trailing commas) are edited through the vendored
+ * token-offset editor (`../jsonc.ts`) so operator comments survive
+ * byte-for-byte; plain JSON at the V1 shape keeps the shared json-merge
+ * body exactly as before. When only `opencode.jsonc` exists it is the
+ * resolved config path; when both (or neither) exist, `opencode.json`
+ * wins, so a fresh install still creates the V1 file both host
+ * generations read.
+ *
+ * An existing healthy top-level registration is NOT migrated when
+ * `mcp.servers` appears: V2 hosts keep reading a legacy declaration, so
+ * migration would churn every install for zero benefit. The first
+ * `--check` after such a shape change reports drift once and the first
+ * re-apply is refused through the user-modified-block guard - the
+ * operator forces it, and that re-apply cleans our own shadowed legacy
+ * copies (never user keys) from the top-level block.
*
* Releases up to v1.3.0 wrote `~/.config/opencode/mcp.json` with an
* `mcpServers` key β€” a file opencode never reads. `apply` migrates our
@@ -15,26 +40,50 @@
* debugging sessions.
*/
-import { existsSync, lstatSync, mkdirSync, readFileSync, rmSync } from "node:fs";
+import { existsSync, lstatSync, mkdirSync, readFileSync, rmSync, statSync } from "node:fs";
import { dirname, join } from "node:path";
import { atomicWriteFileSync } from "../../fs-atomic.ts";
import { createJsonMcpAdapter } from "./_json-mcp.ts";
+import { payloadWithRuntimeIdentity } from "../identity.ts";
+import {
+ JsoncEditError,
+ hasJsoncSyntax,
+ parseJsoncObject,
+ removeJsoncEntry,
+ setJsoncEntry,
+} from "../jsonc.ts";
import { OSB_KEY_FULL, OSB_KEY_WRITER } from "../json-merge.ts";
-import { recordEntry, readManifest } from "../manifest.ts";
+import { recordEntry, readManifest, removeEntry } from "../manifest.ts";
import { OPENCODE_PLUGIN_FILENAME, installedPluginContent } from "../opencode-plugin-asset.ts";
+import { deepJsonEquals, expectedPayloadFromEnv } from "../payload-equals.ts";
+import { payloadForHost } from "../payload-host.ts";
+import { handshakeNote, probeHost, probeRefutedVerdict, probeRefutes } from "../host-probe.ts";
import { defaultRegistry } from "../registry.ts";
-import type {
- ApplyOpts,
- ApplyResult,
- InstallEnv,
- InstallPlan,
- McpPayload,
- McpServerEntry,
- UninstallResult,
- VerifyResult,
+import {
+ InstallError,
+ type ApplyOpts,
+ type ApplyResult,
+ type DetectResult,
+ type InstallEnv,
+ type InstallPlan,
+ type InstallStep,
+ type ManifestEntry,
+ type McpPayload,
+ type McpServerEntry,
+ type UninstallResult,
+ type VerifyResult,
} from "../types.ts";
+const CONFIG_FILENAME = "opencode.json";
+const JSONC_FILENAME = "opencode.jsonc";
+
+/** The native V2 registration path: top-level `mcp` with a `servers` object. */
+const V2_SHAPE_PATH: ReadonlyArray<string> = Object.freeze(["mcp", "servers"]);
+/** The legacy registration path this adapter shipped first. */
+const V1_SHAPE_PATH: ReadonlyArray<string> = Object.freeze(["mcp"]);
+const FIX_HINT = "o2b install --target opencode --apply";
+
function opencodeDir(env: InstallEnv): string {
const xdg = env.env["XDG_CONFIG_HOME"];
const base = xdg && xdg.length > 0 ? xdg : join(env.home, ".config");
@@ -42,7 +91,12 @@ function opencodeDir(env: InstallEnv): string {
}
function configPath(env: InstallEnv): string {
- return join(opencodeDir(env), "opencode.json");
+ const dir = opencodeDir(env);
+ const jsonc = join(dir, JSONC_FILENAME);
+ // `.jsonc` is the config only when it is the only file present; with
+ // both (or neither) the `.json` file keeps today's behavior.
+ if (existsSync(jsonc) && !existsSync(join(dir, CONFIG_FILENAME))) return jsonc;
+ return join(dir, CONFIG_FILENAME);
}
function legacyConfigPath(env: InstallEnv): string {
@@ -50,10 +104,11 @@ function legacyConfigPath(env: InstallEnv): string {
}
/**
- * Canonical `McpServerEntry` β†’ opencode `mcp` entry. opencode takes the
- * full argv as one `command` array and calls the env map `environment`;
- * `enabled: true` is explicit so an operator toggling the server off
- * shows up as drift instead of silently staying off after re-apply.
+ * Canonical `McpServerEntry` β†’ opencode `mcp` entry, V1 shape. opencode
+ * takes the full argv as one `command` array and calls the env map
+ * `environment`; `enabled: true` is explicit so an operator toggling the
+ * server off shows up as drift instead of silently staying off after
+ * re-apply.
*/
export function serializeOpencodeEntry(entry: McpServerEntry): Record<string, unknown> {
return {
@@ -64,6 +119,570 @@ export function serializeOpencodeEntry(entry: McpServerEntry): Record<string, un
};
}
+/**
+ * The same entry at the native V2 shape. The V2 field list replaces V1's
+ * `enabled` with `disabled` ("Use `disabled`, not an `enabled` field"),
+ * so a V2 entry never carries `enabled`; `disabled: false` is written
+ * explicitly so an operator toggling the server off shows up as drift
+ * instead of silently staying off after re-apply.
+ */
+export function serializeOpencodeEntryV2(entry: McpServerEntry): Record<string, unknown> {
+ return {
+ type: "local",
+ command: [entry.command, ...entry.args],
+ ...(entry.env && Object.keys(entry.env).length > 0 ? { environment: { ...entry.env } } : {}),
+ disabled: false,
+ };
+}
+
+/** The entry serializer the resolved config shape takes. */
+function serializerFor(v2: boolean): (entry: McpServerEntry) => Record<string, unknown> {
+ return v2 ? serializeOpencodeEntryV2 : serializeOpencodeEntry;
+}
+
+/**
+ * What the resolved config file looks like to this adapter. `parsed` is
+ * null when neither the plain-JSON nor the JSONC parse accepts the
+ * text; callers decide per verb whether that is drift (verify, detect)
+ * or a named refusal (apply, uninstall).
+ */
+interface ConfigState {
+ readonly exists: boolean;
+ readonly raw: string;
+ /** The text carries comments or trailing commas: only the editor may rewrite it. */
+ readonly jsonc: boolean;
+ /** The file carries an `mcp.servers` object: the native V2 shape is the target. */
+ readonly v2: boolean;
+ readonly parsed: Record<string, unknown> | null;
+}
+
+const ABSENT_CONFIG: ConfigState = Object.freeze({
+ exists: false,
+ raw: "",
+ jsonc: false,
+ v2: false,
+ parsed: null,
+});
+
+function resolveConfigState(env: InstallEnv): ConfigState {
+ const path = configPath(env);
+ let raw: string;
+ try {
+ raw = readFileSync(path, "utf8");
+ } catch {
+ return ABSENT_CONFIG;
+ }
+ let parsed: Record<string, unknown> | null = null;
+ try {
+ parsed = parseJsoncObject(raw);
+ } catch {
+ parsed = null;
+ }
+ return {
+ exists: true,
+ raw,
+ jsonc: hasJsoncSyntax(raw),
+ v2: shapeIsV2(parsed),
+ parsed,
+ };
+}
+
+/**
+ * Whether a value looks like a server entry: an object naming a type, a
+ * command or a url. Exported so the doctor's registered-commands probe
+ * asks this module's shape question instead of its own: the probe scans
+ * `mcp.servers` alone only when this predicate calls the block the
+ * native map, so one file resolves to one shape in both readers.
+ */
+export function looksLikeServerEntry(value: unknown): boolean {
+ if (value === null || typeof value !== "object" || Array.isArray(value)) return false;
+ const record = value as Record<string, unknown>;
+ return (
+ Object.hasOwn(record, "type") ||
+ Object.hasOwn(record, "command") ||
+ Object.hasOwn(record, "url")
+ );
+}
+
+/**
+ * Whether `mcp.servers` is the native V2 map of servers, and not a
+ * legacy user server that happens to be named `servers`. The honest
+ * minimal test: the native shape maps NAMES to entries, so a block that
+ * is itself an entry - `type`, `command` or `url` sitting directly on
+ * it - is that user's server, and the file keeps the legacy shape. An
+ * empty block is the native shape before any server is declared.
+ */
+function shapeIsV2(parsed: Record<string, unknown> | null): boolean {
+ if (parsed === null) return false;
+ const servers = blockAtPath(parsed, V2_SHAPE_PATH);
+ if (servers === null) return false;
+ return !looksLikeServerEntry(servers);
+}
+
+/** Walk a dotted shape path through parsed objects; null when any segment is missing or not an object. */
+function blockAtPath(
+ parsed: Record<string, unknown>,
+ shapePath: ReadonlyArray<string>,
+): Record<string, unknown> | null {
+ let current: unknown = parsed;
+ for (const segment of shapePath) {
+ if (current === null || typeof current !== "object" || Array.isArray(current)) return null;
+ current = (current as Record<string, unknown>)[segment];
+ }
+ if (current === null || typeof current !== "object" || Array.isArray(current)) return null;
+ return current as Record<string, unknown>;
+}
+
+/**
+ * Whether the shape path's FIRST missing segment makes it absent, as
+ * opposed to present but not an object. Detect reads this distinction
+ * the way the shared body's `readMcpBlock` does: a config that simply
+ * does not carry the key has never heard of us (not-installed), while a
+ * key holding the wrong shape is a modification of our registration
+ * site (drift). `blockAtPath` deliberately collapses the two, so this is
+ * the second half of its answer.
+ */
+function blockIsAbsent(parsed: Record<string, unknown>, shapePath: ReadonlyArray<string>): boolean {
+ let current: unknown = parsed;
+ for (const segment of shapePath) {
+ if (current === null || typeof current !== "object" || Array.isArray(current)) return false;
+ const next = (current as Record<string, unknown>)[segment];
+ if (next === undefined) return true;
+ current = next;
+ }
+ return false;
+}
+
+/**
+ * The editor route owns every write whose file carries JSONC syntax or
+ * whose shape is the native V2 key. Plain JSON at the V1 shape keeps
+ * the shared json-merge body byte-for-byte.
+ */
+function routesThroughEditor(state: ConfigState): boolean {
+ return state.jsonc || state.v2;
+}
+
+function hasOsbKeyIn(block: Record<string, unknown> | null): boolean {
+ // Own-property checks: whether the file carries our keys is a question
+ // about the block itself, and an `in` test would read a prototype
+ // chain a crafted document could have forged.
+ return (
+ block !== null && (Object.hasOwn(block, OSB_KEY_FULL) || Object.hasOwn(block, OSB_KEY_WRITER))
+ );
+}
+
+/** Our keys under either shape: a shape change on an install we own is still a modification of it. */
+function hasOsbKeyAnywhere(parsed: Record<string, unknown>): boolean {
+ return (
+ hasOsbKeyIn(blockAtPath(parsed, V2_SHAPE_PATH)) ||
+ hasOsbKeyIn(blockAtPath(parsed, V1_SHAPE_PATH))
+ );
+}
+
+function canonicalUnderShape(
+ parsed: Record<string, unknown>,
+ shapePath: ReadonlyArray<string>,
+ payload: McpPayload,
+): boolean {
+ const block = blockAtPath(parsed, shapePath);
+ if (block === null) return false;
+ const serialize = serializerFor(shapePath === V2_SHAPE_PATH);
+ if (!Object.hasOwn(block, OSB_KEY_FULL) || !Object.hasOwn(block, OSB_KEY_WRITER)) return false;
+ return (
+ deepJsonEquals(block[OSB_KEY_FULL], serialize(payload.full)) &&
+ deepJsonEquals(block[OSB_KEY_WRITER], serialize(payload.writer))
+ );
+}
+
+/** Canonical for the guard means the target shape matches AND, on V2, no shadowed legacy copies of ours remain. */
+function canonicalForGuard(
+ parsed: Record<string, unknown>,
+ v2: boolean,
+ payload: McpPayload,
+): boolean {
+ if (!canonicalUnderShape(parsed, v2 ? V2_SHAPE_PATH : V1_SHAPE_PATH, payload)) return false;
+ if (v2 && hasOsbKeyIn(blockAtPath(parsed, V1_SHAPE_PATH))) return false;
+ return true;
+}
+
+/** The payload as this target's config must hold it: host dimensions, then the runtime-identity rule. */
+function payloadForOpencode(payload: McpPayload, env: InstallEnv): McpPayload {
+ return payloadWithRuntimeIdentity(payloadForHost("opencode", payload, env), "opencode");
+}
+
+/** The verify-side reconstruction, rebuilt from the `InstallEnv` alone. */
+function expectedPayloadForOpencode(env: InstallEnv): McpPayload {
+ return payloadWithRuntimeIdentity(expectedPayloadFromEnv(env, "opencode"), "opencode");
+}
+
+function ownedKeysFor(shapePath: ReadonlyArray<string>): ReadonlyArray<string> {
+ const prefix = shapePath.join(".");
+ return [`${prefix}.${OSB_KEY_FULL}`, `${prefix}.${OSB_KEY_WRITER}`];
+}
+
+function fileMtimeMs(path: string): number | null {
+ try {
+ return statSync(path).mtimeMs;
+ } catch {
+ return null;
+ }
+}
+
+function readFileConfig(path: string): string {
+ try {
+ return readFileSync(path, "utf8");
+ } catch {
+ return "";
+ }
+}
+
+function refusable(e: unknown, path: string): Error {
+ if (e instanceof JsoncEditError) return new JsoncEditError(`${path}: ${e.message}`);
+ return e instanceof Error ? e : new JsoncEditError(`${path}: ${String(e)}`);
+}
+
+function applyViaEditor(
+ env: InstallEnv,
+ rawPayload: McpPayload,
+ opts: ApplyOpts,
+ state: ConfigState,
+): ApplyResult {
+ const path = configPath(env);
+ if (state.parsed === null) {
+ // Ambiguous or malformed config: refused unchanged, named, no
+ // partial write.
+ throw new JsoncEditError(`${path}: config file is not parseable as JSON or JSONC`);
+ }
+ const payload = payloadForOpencode(rawPayload, env);
+ const manifestEntry = readManifest(env.vault).installs["opencode"];
+ // Safety net, editor route: if the on-disk content differs from
+ // canonical AND mtime is newer than manifest.applied_at AND the user
+ // didn't pass --force, refuse. Key presence is checked across BOTH
+ // shapes so a host-side shape change on an install we own counts as a
+ // modification - the one-time drift the docs describe.
+ if (
+ manifestEntry &&
+ !canonicalForGuard(state.parsed, state.v2, payload) &&
+ hasOsbKeyAnywhere(state.parsed) &&
+ !opts.force
+ ) {
+ const appliedAt = Date.parse(manifestEntry.applied_at);
+ const mtime = fileMtimeMs(path) ?? 0;
+ if (Number.isFinite(appliedAt) && mtime > appliedAt + 1000) {
+ throw new InstallError(
+ `opencode: ${path} appears hand-edited after the last install ` +
+ `(mtime newer than manifest applied_at). Refusing to overwrite.`,
+ "opencode",
+ "user-modified-block",
+ "re-run with --force to overwrite, or run `o2b uninstall --target opencode --apply` first",
+ );
+ }
+ }
+ const shapePath = state.v2 ? V2_SHAPE_PATH : V1_SHAPE_PATH;
+ const serialize = serializerFor(state.v2);
+ let next = state.raw;
+ try {
+ next = setJsoncEntry(next, shapePath, OSB_KEY_FULL, serialize(payload.full));
+ next = setJsoncEntry(next, shapePath, OSB_KEY_WRITER, serialize(payload.writer));
+ if (state.v2) {
+ // Our own shadowed copies under the legacy top-level key would
+ // outlive the write; they are ours to clean, user keys stay.
+ next = removeJsoncEntry(next, V1_SHAPE_PATH, OSB_KEY_FULL);
+ next = removeJsoncEntry(next, V1_SHAPE_PATH, OSB_KEY_WRITER);
+ }
+ } catch (e) {
+ throw refusable(e, path);
+ }
+ const contentChanged = next !== state.raw;
+ if (!opts.dryRun && contentChanged) {
+ atomicWriteFileSync(path, next);
+ }
+
+ // Re-apply with byte-identical content: keep the previous
+ // `applied_at` so the user-modified-block detector continues to
+ // compare disk mtime against the actual install moment.
+ const existing = readManifest(env.vault).installs["opencode"];
+ const appliedAt = !contentChanged && existing ? existing.applied_at : env.now.toISOString();
+ const manifest: ManifestEntry = {
+ target: "opencode",
+ applied_at: appliedAt,
+ operation: "json-merge",
+ config_path: path,
+ owned_keys: ownedKeysFor(shapePath),
+ };
+ if (!opts.dryRun && (contentChanged || !existing)) {
+ recordEntry(env.vault, manifest);
+ }
+ return {
+ target: "opencode",
+ manifest,
+ steps_executed: opts.dryRun || !contentChanged ? 0 : 1,
+ };
+}
+
+function verifyViaEditor(env: InstallEnv): VerifyResult {
+ const path = configPath(env);
+ const stored = readManifest(env.vault).installs["opencode"];
+ if (!stored) {
+ return {
+ target: "opencode",
+ status: "not-installed",
+ details: ["no install manifest entry"],
+ fix_hint: null,
+ };
+ }
+ if (!existsSync(path)) {
+ return {
+ target: "opencode",
+ status: "drift",
+ details: [`config file missing: ${path}`],
+ fix_hint: FIX_HINT,
+ };
+ }
+ let parsed: Record<string, unknown>;
+ try {
+ parsed = parseJsoncObject(readFileConfig(path));
+ } catch {
+ return {
+ target: "opencode",
+ status: "drift",
+ details: [`config file is not parseable as JSON or JSONC: ${path}`],
+ fix_hint: FIX_HINT,
+ };
+ }
+ const v2 = shapeIsV2(parsed);
+ const serialize = serializerFor(v2);
+ const shapeKey = (v2 ? V2_SHAPE_PATH : V1_SHAPE_PATH).join(".");
+ const block = blockAtPath(parsed, v2 ? V2_SHAPE_PATH : V1_SHAPE_PATH);
+ if (block === null) {
+ return {
+ target: "opencode",
+ status: "drift",
+ details: [`${shapeKey} is not a JSON object: ${path}`],
+ fix_hint: FIX_HINT,
+ };
+ }
+ const hasFull = Object.hasOwn(block, OSB_KEY_FULL);
+ const hasWriter = Object.hasOwn(block, OSB_KEY_WRITER);
+ if (!hasFull || !hasWriter) {
+ return {
+ target: "opencode",
+ status: "drift",
+ details: [
+ `${hasFull ? "" : OSB_KEY_FULL + " key missing; "}${hasWriter ? "" : OSB_KEY_WRITER + " key missing"}`.trim(),
+ ],
+ fix_hint: FIX_HINT,
+ };
+ }
+ const expected = expectedPayloadForOpencode(env);
+ if (
+ !deepJsonEquals(block[OSB_KEY_FULL], serialize(expected.full)) ||
+ !deepJsonEquals(block[OSB_KEY_WRITER], serialize(expected.writer))
+ ) {
+ return {
+ target: "opencode",
+ status: "drift",
+ details: [`${path}: OSB keys differ from canonical payload`],
+ fix_hint: FIX_HINT,
+ };
+ }
+ // Apply treats our leftover copies under the legacy top-level key as
+ // non-canonical in a V2 file (the guard refuses to count them clean,
+ // and re-apply removes them), so verify must not call the same state
+ // ok: the file an operator would get from re-apply is not the file on
+ // disk.
+ if (v2) {
+ const legacy = blockAtPath(parsed, V1_SHAPE_PATH);
+ const shadowed =
+ legacy === null
+ ? []
+ : [OSB_KEY_FULL, OSB_KEY_WRITER].filter((key) => Object.hasOwn(legacy, key));
+ if (shadowed.length > 0) {
+ return {
+ target: "opencode",
+ status: "drift",
+ details: [
+ `${path}: legacy top-level copies of ${shadowed.join(", ")} remain beside the native mcp.servers entries`,
+ ],
+ fix_hint: FIX_HINT,
+ };
+ }
+ }
+ // The same host-probe composition the shared body applies: the file
+ // was compared and matches, so a refuting probe reads as a host that
+ // has not reloaded the config - never as a lost registration.
+ const probe = probeHost("opencode", env);
+ if (probeRefutes(probe)) {
+ const verdict = probeRefutedVerdict({
+ target: "opencode",
+ label: "opencode",
+ artifactMatches: true,
+ });
+ return {
+ target: "opencode",
+ status: verdict.status,
+ details: [`${path}: matches the canonical payload, but ${handshakeNote(probe)}`],
+ fix_hint: verdict.fixHint,
+ };
+ }
+ return {
+ target: "opencode",
+ status: "ok",
+ details: [`${path}: both OSB keys match the canonical payload (${handshakeNote(probe)})`],
+ fix_hint: null,
+ };
+}
+
+function uninstallViaEditor(
+ env: InstallEnv,
+ opts: ApplyOpts & { fromSnippet?: boolean },
+): UninstallResult {
+ const path = configPath(env);
+ const stored = readManifest(env.vault).installs["opencode"];
+ const skipped: Array<readonly [string, string]> = [];
+ const removed_keys: string[] = [];
+ const removed_paths: string[] = [];
+ if (!stored && !opts.fromSnippet) {
+ throw new InstallError(
+ "opencode: no install manifest entry found. " +
+ `Pass --force-from-snippet to remove based on the canonical payload.`,
+ "opencode",
+ "manifest-missing",
+ "o2b uninstall --target opencode --apply --force-from-snippet",
+ );
+ }
+ if (!existsSync(path)) {
+ skipped.push([path, "config file no longer present"]);
+ if (!opts.dryRun) removeEntry(env.vault, "opencode");
+ return { target: "opencode", removed_keys, removed_paths, skipped };
+ }
+ const raw = readFileConfig(path);
+ if (parseJsoncObjectSafe(raw) === null) {
+ throw new JsoncEditError(`${path}: config file is not parseable as JSON or JSONC`);
+ }
+ // Remove what is ours under either shape, exactly: user keys are
+ // never touched, and an absent key is a byte-identical no-op.
+ let next = raw;
+ try {
+ for (const shapePath of [V2_SHAPE_PATH, V1_SHAPE_PATH]) {
+ for (const key of [OSB_KEY_FULL, OSB_KEY_WRITER]) {
+ const after = removeJsoncEntry(next, shapePath, key);
+ if (after !== next) {
+ removed_keys.push(`${shapePath.join(".")}.${key}`);
+ next = after;
+ }
+ }
+ }
+ } catch (e) {
+ throw refusable(e, path);
+ }
+ if (!opts.dryRun && next !== raw) {
+ atomicWriteFileSync(path, next);
+ }
+ if (!opts.dryRun) removeEntry(env.vault, "opencode");
+ return { target: "opencode", removed_keys, removed_paths, skipped };
+}
+
+function parseJsoncObjectSafe(raw: string): Record<string, unknown> | null {
+ try {
+ return parseJsoncObject(raw);
+ } catch {
+ return null;
+ }
+}
+
+function detectViaEditor(env: InstallEnv, state: ConfigState): DetectResult {
+ const path = configPath(env);
+ if (!state.exists) {
+ return {
+ target: "opencode",
+ status: "not-installed",
+ configPath: path,
+ notes: ["config file missing"],
+ };
+ }
+ if (state.parsed === null) {
+ return {
+ target: "opencode",
+ status: "drift",
+ configPath: path,
+ notes: ["config file is not parseable as JSON or JSONC"],
+ };
+ }
+ const shapePath = state.v2 ? V2_SHAPE_PATH : V1_SHAPE_PATH;
+ const shapeKey = shapePath.join(".");
+ const block = blockAtPath(state.parsed, shapePath);
+ if (block === null) {
+ // An ABSENT key is a config that has never heard of us - the same
+ // verdict base.detect reaches for identical plain-JSON content
+ // (readMcpBlock's `?? {}`). Reporting drift here would make
+ // `o2b update`, which skips only not-installed targets, perform a
+ // full install into an opencode that was never installed. Only a
+ // PRESENT-but-non-object block is drift.
+ if (blockIsAbsent(state.parsed, shapePath)) {
+ return { target: "opencode", status: "not-installed", configPath: path, notes: [] };
+ }
+ return {
+ target: "opencode",
+ status: "drift",
+ configPath: path,
+ notes: [`${shapeKey} is not a JSON object`],
+ };
+ }
+ const hasFull = Object.hasOwn(block, OSB_KEY_FULL);
+ const hasWriter = Object.hasOwn(block, OSB_KEY_WRITER);
+ if (!hasFull && !hasWriter) {
+ // Our keys under the OTHER shape are an owned install at a site the
+ // resolved shape does not read, not an absent one: verify names that
+ // state drift, re-apply removes the shadowed copies, and a
+ // not-installed verdict here would make `o2b update`, which skips
+ // only not-installed targets, skip the repair. Neither block
+ // holding our keys stays the "never heard of us" verdict.
+ if (hasOsbKeyAnywhere(state.parsed)) {
+ return {
+ target: "opencode",
+ status: "drift",
+ configPath: path,
+ notes: [
+ `our keys sit under ${(state.v2 ? V1_SHAPE_PATH : V2_SHAPE_PATH).join(".")}; ${shapeKey} lacks them`,
+ ],
+ };
+ }
+ return { target: "opencode", status: "not-installed", configPath: path, notes: [] };
+ }
+ if (hasFull && hasWriter) {
+ return {
+ target: "opencode",
+ status: "installed",
+ configPath: path,
+ notes: [`both OSB keys present under ${shapeKey}`],
+ };
+ }
+ return {
+ target: "opencode",
+ status: "drift",
+ configPath: path,
+ notes: [`partial OSB install: ${hasFull ? "writer key missing" : "full-server key missing"}`],
+ };
+}
+
+function editorPlanStep(state: ConfigState, rawPayload: McpPayload, env: InstallEnv): InstallStep {
+ const path = configPath(env);
+ const shapeKey = (state.v2 ? V2_SHAPE_PATH : V1_SHAPE_PATH).join(".");
+ const preserved = state.jsonc ? " (JSONC comments preserved)" : "";
+ // The PREVIEW prints the args that will actually be written, the same
+ // contract the shared body's plan states.
+ const payload = payloadForOpencode(rawPayload, env);
+ return {
+ kind: "json-merge",
+ path,
+ preview:
+ `json-merge two keys into ${shapeKey} at ${path}${preserved}: ` +
+ `${OSB_KEY_FULL} β†’ ${payload.full.command} ${payload.full.args.join(" ")}; ` +
+ `${OSB_KEY_WRITER} β†’ ${payload.writer.command} ${payload.writer.args.join(" ")}`,
+ };
+}
+
/**
* Best-effort removal of our keys from the legacy `mcp.json`. Never
* throws: a malformed or absent file is left as-is β€” migration is an
@@ -118,6 +737,9 @@ const base = createJsonMcpAdapter({
label: "opencode",
topLevelKey: "mcp",
resolveConfigPath: configPath,
+ // The shared body serves only the plain-JSON V1 route (the editor
+ // route owns every JSONC or V2-shaped file), so the V1 entry shape is
+ // the right serialization here.
serializeEntry: serializeOpencodeEntry,
runtimeIdentity: true,
postNotes: ["Restart opencode to load the new MCP servers and the Open Second Brain plugin."],
@@ -126,9 +748,17 @@ const base = createJsonMcpAdapter({
export const opencodeAdapter = {
...base,
+ detect(env: InstallEnv): DetectResult {
+ const state = resolveConfigState(env);
+ return routesThroughEditor(state) ? detectViaEditor(env, state) : base.detect(env);
+ },
+
plan(payload: McpPayload, env: InstallEnv): InstallPlan {
const basePlan = base.plan(payload, env);
- const steps = [...basePlan.steps];
+ const state = resolveConfigState(env);
+ const steps = routesThroughEditor(state)
+ ? [editorPlanStep(state, payload, env), ...basePlan.steps.slice(1)]
+ : [...basePlan.steps];
steps.push({
kind: "file-copy",
path: pluginPath(env),
@@ -146,7 +776,10 @@ export const opencodeAdapter = {
},
apply(plan: InstallPlan, payload: McpPayload, env: InstallEnv, opts: ApplyOpts): ApplyResult {
- const result = base.apply(plan, payload, env, opts);
+ const state = resolveConfigState(env);
+ const result = routesThroughEditor(state)
+ ? applyViaEditor(env, payload, opts, state)
+ : base.apply(plan, payload, env, opts);
migrateLegacyMcpJson(env, opts);
const plugin = pluginPath(env);
@@ -165,9 +798,10 @@ export const opencodeAdapter = {
atomicWriteFileSync(plugin, expected);
pluginWritten = 1;
}
- // The base body records ownership of the two JSON keys; extend the
- // entry with the plugin file so verify and uninstall track it too.
- const stored = readManifest(env.vault).installs[base.target] ?? result.manifest;
+ // The write path records ownership of the two JSON keys; extend
+ // the entry with the plugin file so verify and uninstall track it
+ // too.
+ const stored = readManifest(env.vault).installs[result.manifest.target] ?? result.manifest;
const manifest = { ...stored, owned_paths: [plugin] };
recordEntry(env.vault, manifest);
return {
@@ -180,7 +814,8 @@ export const opencodeAdapter = {
},
verify(env: InstallEnv): VerifyResult {
- const baseResult = base.verify(env);
+ const state = resolveConfigState(env);
+ const baseResult = routesThroughEditor(state) ? verifyViaEditor(env) : base.verify(env);
if (baseResult.status !== "ok") return baseResult;
const plugin = pluginPath(env);
const fixHint = "o2b install --target opencode --apply";
@@ -205,7 +840,10 @@ export const opencodeAdapter = {
},
uninstall(env: InstallEnv, opts: ApplyOpts & { fromSnippet?: boolean }): UninstallResult {
- const result = base.uninstall(env, opts);
+ const state = resolveConfigState(env);
+ const result = routesThroughEditor(state)
+ ? uninstallViaEditor(env, opts)
+ : base.uninstall(env, opts);
const plugin = pluginPath(env);
if (existsSync(plugin)) {
try {
diff --git a/src/core/install/jsonc.ts b/src/core/install/jsonc.ts
new file mode 100644
index 00000000..fee4fb37
--- /dev/null
+++ b/src/core/install/jsonc.ts
@@ -0,0 +1,789 @@
+/**
+ * Minimal vendored JSONC editor for runtime config files.
+ *
+ * The repo has exactly one runtime dependency, and the OpenCode V2 config
+ * surface needs a narrow slice of JSONC editing: locate a nested key in a
+ * document that may carry `//` and `/* * /` comments or trailing commas,
+ * splice one entry in, over or out, and keep every byte outside the
+ * spliced range - operator comments included - exactly as it was. A
+ * dependency would be the larger, less honest change for this surface,
+ * so this is the vendored minimum: a tokenizer, a structural parse and
+ * token-offset splices. Whole-root re-serialization is exactly what this
+ * module must never do; `json-merge.ts` remains the write path for
+ * comment-free files, where its JSON-value-level round-trip already
+ * holds.
+ *
+ * Contract:
+ * - Pure text-in/text-out. No fs, no clock, no imports.
+ * - A leading UTF-8 BOM is stripped on read and restored on write, the
+ * same tolerance json-merge applies for Windows-side editors.
+ * - `hasJsoncSyntax` is lexical and total: it answers whether the text
+ * carries comments or trailing commas even when the text is
+ * otherwise malformed, because callers route on it before parsing.
+ * - Malformed input, duplicate keys (anywhere - an ambiguous document
+ * is refused, not interpreted) and a non-object root raise the named
+ * `JsoncEditError`. No partial text is ever emitted.
+ * - Object keys materialize as own properties: a literal `__proto__`
+ * key is data, never the parsed object's prototype - the same
+ * literal-key semantics JSON.parse gives it. Assigning through the
+ * inherited accessor would let a crafted config forge membership
+ * and bracket reads for every downstream `in`-based check.
+ * - Inserted values must be JSON-serializable; comments cannot be
+ * authored through this editor - it exists to PRESERVE operator
+ * comments, not to write them.
+ * - Formatting of inserted bytes: a multi-line object fills at the
+ * indentation of its neighbors (detected unit, 2 as fallback); an
+ * object that occupies a single line stays single-line and is filled
+ * compactly. Untouched bytes are never reformatted.
+ */
+
+/** The named refusal for malformed, ambiguous or uneditable JSONC. */
+export class JsoncEditError extends Error {
+ constructor(message: string) {
+ super(message);
+ this.name = "JsoncEditError";
+ }
+}
+
+const BOM = "\uFEFF";
+const DEFAULT_INDENT_UNIT = 2;
+
+// ----- Tokenizer -------------------------------------------------------------
+
+type TokenKind = "punct" | "string" | "number" | "literal";
+
+interface Token {
+ readonly kind: TokenKind;
+ readonly start: number;
+ /** Offset just past the token. */
+ readonly end: number;
+ /** Punctuation character, decoded string value, or raw text. */
+ readonly text: string;
+}
+
+interface Lex {
+ readonly tokens: ReadonlyArray<Token>;
+ readonly hasComments: boolean;
+ readonly hasTrailingCommas: boolean;
+ /** The first scanning failure, when the text is not tokenizable. */
+ readonly error: string | null;
+}
+
+const PUNCTUATION = new Set(["{", "}", "[", "]", ":", ","]);
+const STRING_ESCAPES = new Set(['"', "\\", "/", "b", "f", "n", "r", "t"]);
+const NUMBER_RE = /^-?(?:0|[1-9]\d*)(?:\.\d+)?(?:[eE][+-]?\d+)?/;
+
+function isWhitespace(c: string): boolean {
+ return c === " " || c === "\t" || c === "\n" || c === "\r";
+}
+
+/** The end offset (exclusive) of the string opening at `open`, or the reason it cannot be scanned. */
+function scanString(body: string, open: number): number | string {
+ let i = open + 1;
+ while (i < body.length) {
+ const c = body[i]!;
+ if (c === '"') return i + 1;
+ if (c === "\\") {
+ const esc = body[i + 1];
+ if (esc === undefined) return `unterminated escape in string at offset ${i}`;
+ if (esc === "u") {
+ if (!/^[0-9a-fA-F]{4}$/.test(body.slice(i + 2, i + 6))) {
+ return `invalid unicode escape in string at offset ${i}`;
+ }
+ i += 6;
+ continue;
+ }
+ if (!STRING_ESCAPES.has(esc)) return `invalid escape in string at offset ${i}`;
+ i += 2;
+ continue;
+ }
+ if (c.charCodeAt(0) < 0x20) return `unescaped control character in string at offset ${i}`;
+ i++;
+ }
+ return `unterminated string at offset ${open}`;
+}
+
+function scan(body: string): Lex {
+ const tokens: Token[] = [];
+ let hasComments = false;
+ let error: string | null = null;
+ let i = 0;
+ while (i < body.length) {
+ const c = body[i]!;
+ if (isWhitespace(c)) {
+ i += 1;
+ continue;
+ }
+ if (c === "/") {
+ const next = body[i + 1];
+ if (next === "/") {
+ hasComments = true;
+ const nl = body.indexOf("\n", i);
+ i = nl === -1 ? body.length : nl;
+ continue;
+ }
+ if (next === "*") {
+ const close = body.indexOf("*/", i + 2);
+ if (close === -1) {
+ error = `unterminated block comment at offset ${i}`;
+ break;
+ }
+ hasComments = true;
+ i = close + 2;
+ continue;
+ }
+ error = `unexpected character "/" at offset ${i}`;
+ break;
+ }
+ if (c === '"') {
+ const end = scanString(body, i);
+ if (typeof end === "string") {
+ error = end;
+ break;
+ }
+ let decoded: string;
+ try {
+ decoded = JSON.parse(body.slice(i, end)) as string;
+ } catch {
+ error = `invalid string at offset ${i}`;
+ break;
+ }
+ tokens.push({ kind: "string", start: i, end, text: decoded });
+ i = end;
+ continue;
+ }
+ if (c === "-" || (c >= "0" && c <= "9")) {
+ // The full remaining body, not a window: the anchored regex stops
+ // at the literal's own end, and a window shorter than a (valid,
+ // exotic) literal would split it into two number tokens and
+ // false-refuse the document as malformed.
+ const match = NUMBER_RE.exec(body.slice(i));
+ if (match === null) {
+ error = `invalid number at offset ${i}`;
+ break;
+ }
+ tokens.push({ kind: "number", start: i, end: i + match[0].length, text: match[0] });
+ i += match[0].length;
+ continue;
+ }
+ let literal: string | null = null;
+ for (const candidate of ["true", "false", "null"]) {
+ if (body.startsWith(candidate, i)) {
+ literal = candidate;
+ break;
+ }
+ }
+ if (literal !== null) {
+ tokens.push({ kind: "literal", start: i, end: i + literal.length, text: literal });
+ i += literal.length;
+ continue;
+ }
+ if (PUNCTUATION.has(c)) {
+ tokens.push({ kind: "punct", start: i, end: i + 1, text: c });
+ i += 1;
+ continue;
+ }
+ error = `unexpected character ${JSON.stringify(c)} at offset ${i}`;
+ break;
+ }
+ let hasTrailingCommas = false;
+ for (let k = 0; k + 1 < tokens.length; k++) {
+ const comma = tokens[k]!;
+ const after = tokens[k + 1]!;
+ if (comma.kind === "punct" && comma.text === "," && after.kind === "punct") {
+ if (after.text === "}" || after.text === "]") hasTrailingCommas = true;
+ }
+ }
+ return { tokens, hasComments, hasTrailingCommas, error };
+}
+
+// ----- Structural parse ------------------------------------------------------
+
+interface ObjectEntry {
+ readonly key: string;
+ /** Offset of the opening quote of the key. */
+ readonly keyStart: number;
+ readonly valueStart: number;
+ readonly valueEnd: number;
+ readonly value: Node;
+}
+
+interface ObjectNode {
+ readonly kind: "object";
+ readonly start: number;
+ readonly end: number;
+ readonly openBrace: number;
+ readonly closeBrace: number;
+ readonly entries: ReadonlyMap<string, ObjectEntry>;
+ readonly order: ReadonlyArray<ObjectEntry>;
+}
+
+interface ArrayNode {
+ readonly kind: "array";
+ readonly start: number;
+ readonly end: number;
+ readonly elements: ReadonlyArray<Node>;
+}
+
+interface LeafNode {
+ readonly kind: "leaf";
+ readonly start: number;
+ readonly end: number;
+ readonly value: unknown;
+}
+
+type Node = ObjectNode | ArrayNode | LeafNode;
+
+interface TokenReader {
+ readonly tokens: ReadonlyArray<Token>;
+ pos: number;
+}
+
+function peek(reader: TokenReader): Token | null {
+ return reader.pos < reader.tokens.length ? reader.tokens[reader.pos]! : null;
+}
+
+function take(reader: TokenReader): Token {
+ const token = peek(reader);
+ if (token === null) throw new JsoncEditError("unexpected end of document");
+ reader.pos += 1;
+ return token;
+}
+
+function takePunct(reader: TokenReader, char: string): Token {
+ const token = take(reader);
+ if (token.kind !== "punct" || token.text !== char) {
+ throw new JsoncEditError(`expected "${char}" at offset ${token.start}`);
+ }
+ return token;
+}
+
+function parseValue(reader: TokenReader): Node {
+ const token = peek(reader);
+ if (token === null) throw new JsoncEditError("expected a value, found end of document");
+ if (token.kind === "punct") {
+ // A value position accepts only the two container openings. Any
+ // other punctuation - the `:` or `,` of a half-edited document
+ // (`{"a": ,}`, `[,]`) - is malformed input, not a null: reading it
+ // as one would let apply proceed on a file no JSON parser accepts.
+ if (token.text !== "{" && token.text !== "[") {
+ throw new JsoncEditError(`expected a value, found "${token.text}" at offset ${token.start}`);
+ }
+ return token.text === "{" ? parseObject(reader) : parseArray(reader);
+ }
+ take(reader);
+ if (token.kind === "string") {
+ return { kind: "leaf", start: token.start, end: token.end, value: token.text };
+ }
+ if (token.kind === "number") {
+ return { kind: "leaf", start: token.start, end: token.end, value: Number(token.text) };
+ }
+ const value = token.text === "true" ? true : token.text === "false" ? false : null;
+ return { kind: "leaf", start: token.start, end: token.end, value };
+}
+
+function parseObject(reader: TokenReader): ObjectNode {
+ const open = takePunct(reader, "{");
+ const entries = new Map<string, ObjectEntry>();
+ const order: ObjectEntry[] = [];
+ let close = peek(reader);
+ if (close !== null && close.kind === "punct" && close.text === "}") {
+ take(reader);
+ return {
+ kind: "object",
+ start: open.start,
+ end: close.end,
+ openBrace: open.start,
+ closeBrace: close.start,
+ entries,
+ order,
+ };
+ }
+ for (;;) {
+ const key = take(reader);
+ if (key.kind !== "string") {
+ throw new JsoncEditError(`expected a string object key at offset ${key.start}`);
+ }
+ takePunct(reader, ":");
+ const value = parseValue(reader);
+ if (entries.has(key.text)) {
+ throw new JsoncEditError(`duplicate key "${key.text}" at offset ${key.start}`);
+ }
+ const entry: ObjectEntry = {
+ key: key.text,
+ keyStart: key.start,
+ valueStart: value.start,
+ valueEnd: value.end,
+ value,
+ };
+ entries.set(key.text, entry);
+ order.push(entry);
+ const separator = peek(reader);
+ if (separator !== null && separator.kind === "punct" && separator.text === ",") {
+ take(reader);
+ const after = peek(reader);
+ if (after !== null && after.kind === "punct" && after.text === "}") {
+ take(reader);
+ close = after;
+ break;
+ }
+ continue;
+ }
+ const closing = takePunct(reader, "}");
+ close = closing;
+ break;
+ }
+ return {
+ kind: "object",
+ start: open.start,
+ end: close!.end,
+ openBrace: open.start,
+ closeBrace: close!.start,
+ entries,
+ order,
+ };
+}
+
+function parseArray(reader: TokenReader): ArrayNode {
+ const open = takePunct(reader, "[");
+ const elements: Node[] = [];
+ let close = peek(reader);
+ if (close !== null && close.kind === "punct" && close.text === "]") {
+ take(reader);
+ return { kind: "array", start: open.start, end: close.end, elements };
+ }
+ for (;;) {
+ elements.push(parseValue(reader));
+ const separator = peek(reader);
+ if (separator !== null && separator.kind === "punct" && separator.text === ",") {
+ take(reader);
+ const after = peek(reader);
+ if (after !== null && after.kind === "punct" && after.text === "]") {
+ take(reader);
+ close = after;
+ break;
+ }
+ continue;
+ }
+ close = takePunct(reader, "]");
+ break;
+ }
+ return { kind: "array", start: open.start, end: close!.end, elements };
+}
+
+function parseRoot(lex: Lex): ObjectNode {
+ if (lex.error !== null) throw new JsoncEditError(lex.error);
+ const reader: TokenReader = { tokens: lex.tokens, pos: 0 };
+ const root = parseValue(reader);
+ const trailing = peek(reader);
+ if (trailing !== null) {
+ throw new JsoncEditError(`unexpected content after the root value at offset ${trailing.start}`);
+ }
+ if (root.kind !== "object") throw new JsoncEditError("expected a JSON object at the root");
+ return root;
+}
+
+// ----- Text helpers ------------------------------------------------------------
+
+function stripBom(text: string): { body: string; hadBom: boolean } {
+ return text.charCodeAt(0) === 0xfeff
+ ? { body: text.slice(1), hadBom: true }
+ : { body: text, hadBom: false };
+}
+
+function restoreBom(text: string, hadBom: boolean): string {
+ return hadBom ? BOM + text : text;
+}
+
+function isSpaceOrTab(c: string): boolean {
+ return c === " " || c === "\t";
+}
+
+/**
+ * Horizontal whitespace a separator scan may cross: a CRLF file's
+ * carriage returns sit between a separator comma and the entry that
+ * follows it, so a walk-back that stopped at `\r` would miss the comma
+ * entirely.
+ */
+function isHorizontalWs(c: string): boolean {
+ return c === " " || c === "\t" || c === "\r";
+}
+
+/** Characters that can begin a JSON token; anything else opens a comment. */
+const TOKEN_START = /["{}[],:0-9tfn-]/;
+
+/**
+ * Width of the first space-indented line that starts with a token, the
+ * unit `json-merge` detects too; 2 as fallback. A line whose first
+ * non-space byte opens a comment carries the author's prose layout, not
+ * the file's indentation step - a leading block comment must not shrink
+ * the unit to its own star's column.
+ */
+function indentUnit(text: string): number {
+ for (const line of text.split("\n")) {
+ const match = /^( +)(.)/.exec(line);
+ if (match === null) continue;
+ if (TOKEN_START.test(match[2]!)) return match[1]!.length;
+ }
+ return DEFAULT_INDENT_UNIT;
+}
+
+/** Leading whitespace of the line containing `offset` (callers pass offsets at line starts). */
+function lineIndent(text: string, offset: number): string {
+ const lineStart = offset > 0 ? text.lastIndexOf("\n", offset - 1) + 1 : 0;
+ let end = lineStart;
+ while (end < text.length && isSpaceOrTab(text[end]!)) end += 1;
+ return text.slice(lineStart, end);
+}
+
+function splice(text: string, start: number, end: number, inserted: string): string {
+ return text.slice(0, start) + inserted + text.slice(end);
+}
+
+/**
+ * The value as inserted bytes: pretty-printed at the detected unit and
+ * re-indented under the entry's key. Scalars stay on the key's line.
+ */
+function renderValue(value: unknown, unit: number, keyIndent: string): string {
+ const rendered = JSON.stringify(value, null, unit);
+ if (rendered === undefined) {
+ throw new JsoncEditError("value is not JSON-serializable");
+ }
+ return unit === 0 ? rendered : rendered.replace(/\n/g, "\n" + keyIndent);
+}
+
+// ----- Entry insertion, replacement and removal ---------------------------------
+
+/**
+ * Where the last entry's line ends, and whether a separator comma sits
+ * on it. The splice point for a new entry is past that line's newline,
+ * so the entry's own trailing line comment stays annotating the entry
+ * instead of moving to the inserted one. A block comment that starts on
+ * the value's line and runs past its newline pushes the line end past
+ * its close, so the new entry never lands inside the comment - and the
+ * scan never crosses the object's closing brace. Comments never
+ * tokenize, so a comma reached outside them is code by construction.
+ */
+function trailingLineOf(
+ text: string,
+ valueEnd: number,
+ closeBrace: number,
+): { lineEnd: number; separator: boolean } {
+ const firstNewline = text.indexOf("\n", valueEnd);
+ let lineEnd = firstNewline === -1 ? text.length : firstNewline;
+ let separator = false;
+ let i = valueEnd;
+ while (i < lineEnd) {
+ const c = text[i]!;
+ if (isWhitespace(c)) {
+ i += 1;
+ continue;
+ }
+ if (c === "/" && text[i + 1] === "/") break; // the rest of the line is comment content
+ if (c === "/" && text[i + 1] === "*") {
+ const close = text.indexOf("*/", i + 2);
+ const commentEnd = close === -1 ? Math.min(closeBrace, text.length) : close + 2;
+ if (commentEnd > lineEnd) {
+ const nl = text.indexOf("\n", commentEnd);
+ lineEnd = Math.min(nl === -1 ? text.length : nl, closeBrace);
+ }
+ i = Math.min(commentEnd, text.length);
+ continue;
+ }
+ if (c === ",") {
+ separator = true;
+ i += 1;
+ continue;
+ }
+ break; // a code byte that is neither separator nor comment cannot follow a parsed value
+ }
+ return { lineEnd, separator };
+}
+
+/**
+ * Splice one new entry at the end of `obj`. A single-line object stays
+ * single-line (compact value); a multi-line object fills at its
+ * neighbors' indentation. The new entry opens the line after the last
+ * entry's own line: a separator comma is added at the old value end
+ * only when the last entry does not already carry one, and any comment
+ * sharing that line keeps its place.
+ */
+function insertEntry(text: string, obj: ObjectNode, key: string, value: unknown): string {
+ const keyText = JSON.stringify(key);
+ if (obj.order.length === 0) {
+ const between = text.slice(obj.openBrace + 1, obj.closeBrace);
+ if (!between.includes("\n")) {
+ const rendered = JSON.stringify(value);
+ if (rendered === undefined) throw new JsoncEditError("value is not JSON-serializable");
+ return splice(text, obj.openBrace + 1, obj.openBrace + 1, keyText + ": " + rendered);
+ }
+ const childIndent = lineIndent(text, obj.closeBrace) + " ".repeat(indentUnit(text));
+ return splice(
+ text,
+ obj.openBrace + 1,
+ obj.openBrace + 1,
+ "\n" + childIndent + keyText + ": " + renderValue(value, indentUnit(text), childIndent),
+ );
+ }
+ const last = obj.order[obj.order.length - 1]!;
+ const between = text.slice(last.valueEnd, obj.closeBrace);
+ if (!between.includes("\n")) {
+ const rendered = JSON.stringify(value);
+ if (rendered === undefined) throw new JsoncEditError("value is not JSON-serializable");
+ // A separator comma straight after the value (single-line
+ // trailing-comma style) is not doubled: the entry slots in behind it.
+ let i = last.valueEnd;
+ while (i < text.length && isSpaceOrTab(text[i]!)) i += 1;
+ if (text[i] === ",") {
+ return splice(text, i + 1, i + 1, " " + keyText + ": " + rendered);
+ }
+ return splice(text, last.valueEnd, last.valueEnd, ", " + keyText + ": " + rendered);
+ }
+ const { lineEnd, separator } = trailingLineOf(text, last.valueEnd, obj.closeBrace);
+ const keyIndent = lineIndent(text, last.keyStart);
+ const entry = keyIndent + keyText + ": " + renderValue(value, indentUnit(text), keyIndent);
+ // head keeps the value's line - separator and comment included - with
+ // a comma added at the old value end only when there is none; the new
+ // entry opens the following line, ahead of the untouched tail.
+ const head =
+ text.slice(0, last.valueEnd) + (separator ? "" : ",") + text.slice(last.valueEnd, lineEnd);
+ return head + "\n" + entry + text.slice(lineEnd);
+}
+
+/**
+ * Splice over exactly the existing entry's value range, leaving the key
+ * and its line untouched. A value that occupies a single line is
+ * replaced compactly: re-placing a compact entry with a pretty-printed
+ * one would make every no-op re-apply rewrite bytes.
+ */
+function replaceEntry(text: string, entry: ObjectEntry, value: unknown): string {
+ const rendered = text.slice(entry.valueStart, entry.valueEnd).includes("\n")
+ ? renderValue(value, indentUnit(text), lineIndent(text, entry.keyStart))
+ : JSON.stringify(value);
+ if (rendered === undefined) {
+ throw new JsoncEditError("value is not JSON-serializable");
+ }
+ return splice(text, entry.valueStart, entry.valueEnd, rendered);
+}
+
+/**
+ * Whether the tokenizer emitted a comma at exactly `offset`. Comment
+ * bytes never tokenize, so this is what separates a separator comma from
+ * a `,` that merely closes an operator comment line.
+ */
+function isCommaTokenAt(tokens: ReadonlyArray<Token>, offset: number): boolean {
+ for (const token of tokens) {
+ if (token.start === offset) return token.kind === "punct" && token.text === ",";
+ if (token.start > offset) return false;
+ }
+ return false;
+}
+
+/**
+ * Splice out one entry, commas included, without touching a comment that
+ * shares the line. When the entry is alone on its line(s) the whole line
+ * collapses so no hole is left behind.
+ */
+function removeEntry(text: string, tokens: ReadonlyArray<Token>, entry: ObjectEntry): string {
+ let start = entry.keyStart;
+ let end = entry.valueEnd;
+ let trailingComma = false;
+ // The separator may sit at the head of a FOLLOWING line (comma-first
+ // style), so the forward scan crosses newlines the way the walk-back
+ // below does, and it steps over comment ranges: a trailing `// note`
+ // sharing the entry's line hides the next line's leading comma, and a
+ // comma reached past a comment is code - the comment's own bytes are
+ // skipped by range, never scanned. Consuming that comma is what keeps
+ // a comma-first document parseable once the entry (and its comment)
+ // are gone.
+ let j = end;
+ for (;;) {
+ while (j < text.length && isWhitespace(text[j]!)) j += 1;
+ if (text[j] === "," && isCommaTokenAt(tokens, j)) {
+ end = j + 1;
+ trailingComma = true;
+ break;
+ }
+ if (text[j] === "/" && text[j + 1] === "/") {
+ const nl = text.indexOf("\n", j);
+ if (nl === -1) break;
+ j = nl + 1;
+ continue;
+ }
+ if (text[j] === "/" && text[j + 1] === "*") {
+ const close = text.indexOf("*/", j + 2);
+ if (close === -1) break;
+ j = close + 2;
+ continue;
+ }
+ break;
+ }
+ if (!trailingComma) {
+ let k = start;
+ while (k > 0 && isHorizontalWs(text[k - 1]!)) k -= 1;
+ if (k > 0 && text[k - 1] === ",") {
+ start = k - 1;
+ } else if (k > 0 && text[k - 1] === "\n") {
+ // The separating comma may close the previous line instead
+ // (`..., }\n "ours": ...`); consuming it is what restores the
+ // original bytes when the removed entry was last in its object.
+ // A comment between the comma and the entry stops the walk-back,
+ // and the leftover trailing comma stays - valid JSONC either way.
+ // A comma that is the last byte of a COMMENT line is comment
+ // content, not a separator: only a comma the tokenizer emitted
+ // may be consumed, so the operator's bytes stay exactly as they
+ // were.
+ let m = k - 1;
+ while (m > 0 && isHorizontalWs(text[m - 1]!)) m -= 1;
+ if (m > 0 && text[m - 1] === "," && isCommaTokenAt(tokens, m - 1)) start = m - 1;
+ }
+ }
+ const lineStart = start > 0 ? text.lastIndexOf("\n", start - 1) + 1 : 0;
+ const newline = text.indexOf("\n", end);
+ const lineEnd = newline === -1 ? text.length : newline;
+ const prefix = text.slice(lineStart, start);
+ const suffix = text.slice(end, lineEnd);
+ const aloneOnLine = [...prefix, ...suffix].every(isHorizontalWs);
+ // Collapse the whole line(s) the entry occupies, its terminating
+ // newline included, so no hole is left - the prefix already ends with
+ // the previous line's newline.
+ const collapseEnd = newline === -1 ? text.length : newline + 1;
+ return aloneOnLine
+ ? text.slice(0, lineStart) + text.slice(collapseEnd)
+ : text.slice(0, start) + text.slice(end);
+}
+
+/** The literal for a missing intermediate object: the remaining path down to the entry. */
+function nestedLiteral(remaining: ReadonlyArray<string>, key: string, value: unknown): unknown {
+ let out: Record<string, unknown> = { [key]: value };
+ for (let i = remaining.length - 1; i >= 0; i -= 1) {
+ out = { [remaining[i]!]: out };
+ }
+ return out;
+}
+
+function setInObject(
+ text: string,
+ root: ObjectNode,
+ path: ReadonlyArray<string>,
+ key: string,
+ value: unknown,
+): string {
+ let current = root;
+ for (let depth = 0; depth < path.length; depth += 1) {
+ const segment = path[depth]!;
+ const entry = current.entries.get(segment);
+ if (entry === undefined) {
+ return insertEntry(text, current, segment, nestedLiteral(path.slice(depth + 1), key, value));
+ }
+ if (entry.value.kind !== "object") {
+ throw new JsoncEditError(`"${segment}" at offset ${entry.valueStart} is not a JSON object`);
+ }
+ current = entry.value;
+ }
+ const existing = current.entries.get(key);
+ return existing === undefined
+ ? insertEntry(text, current, key, value)
+ : replaceEntry(text, existing, value);
+}
+
+function removeFromObject(
+ text: string,
+ tokens: ReadonlyArray<Token>,
+ root: ObjectNode,
+ path: ReadonlyArray<string>,
+ key: string,
+): string {
+ let current = root;
+ for (const segment of path) {
+ const entry = current.entries.get(segment);
+ if (entry === undefined || entry.value.kind !== "object") return text;
+ current = entry.value;
+ }
+ const entry = current.entries.get(key);
+ return entry === undefined ? text : removeEntry(text, tokens, entry);
+}
+
+// ----- Public surface -----------------------------------------------------------
+
+/**
+ * Whether the text carries JSON-only-rejected syntax: comments or
+ * trailing commas. Lexical and total - a malformed document still gets
+ * the flags found before the first scanning failure, because callers
+ * route on this answer before any parse.
+ */
+export function hasJsoncSyntax(text: string): boolean {
+ const { body } = stripBom(text);
+ const lex = scan(body);
+ return lex.hasComments || lex.hasTrailingCommas;
+}
+
+/**
+ * Parse JSONC text into a plain object. Duplicate keys anywhere, a
+ * non-object root and malformed input raise `JsoncEditError`.
+ */
+export function parseJsoncObject(text: string): Record<string, unknown> {
+ const { body } = stripBom(text);
+ return toPlainObject(parseRoot(scan(body)));
+}
+
+/**
+ * An object node's entries as a plain record. Split from the general
+ * value case so the object-root contract of `parseJsoncObject` is
+ * satisfied by construction - the root is statically an ObjectNode, so
+ * the record needs no cast and no runtime re-check.
+ *
+ * Each key is written as its own data property. The plain assignment
+ * `out[key] = ...` routes a key named `__proto__` through the inherited
+ * accessor and makes the crafted value the accumulator's prototype -
+ * prototype injection. `defineProperty` keeps every key, that one
+ * included, a real own property: the parse result matches what
+ * JSON.parse hands out for the same document, and no downstream read
+ * can see keys the file does not carry.
+ */
+function toPlainObject(node: ObjectNode): Record<string, unknown> {
+ const out: Record<string, unknown> = {};
+ for (const entry of node.order) {
+ Object.defineProperty(out, entry.key, {
+ value: toPlainValue(entry.value),
+ enumerable: true,
+ writable: true,
+ configurable: true,
+ });
+ }
+ return out;
+}
+
+function toPlainValue(node: Node): unknown {
+ if (node.kind === "leaf") return node.value;
+ if (node.kind === "array") return node.elements.map(toPlainValue);
+ return toPlainObject(node);
+}
+
+/**
+ * Insert or replace the entry `key` under the object at `path`, creating
+ * missing intermediate objects, and return the new text. Every byte
+ * outside the spliced range - comments and formatting included - is
+ * preserved as it was.
+ */
+export function setJsoncEntry(
+ text: string,
+ path: ReadonlyArray<string>,
+ key: string,
+ value: unknown,
+): string {
+ const { body, hadBom } = stripBom(text);
+ const next = setInObject(body, parseRoot(scan(body)), path, key, value);
+ return restoreBom(next, hadBom);
+}
+
+/**
+ * Remove the entry `key` from the object at `path` and return the new
+ * text. An absent key or an absent path is a byte-identical no-op.
+ */
+export function removeJsoncEntry(text: string, path: ReadonlyArray<string>, key: string): string {
+ const { body, hadBom } = stripBom(text);
+ const lex = scan(body);
+ const next = removeFromObject(body, lex.tokens, parseRoot(lex), path, key);
+ return restoreBom(next, hadBom);
+}
diff --git a/src/core/search/index.ts b/src/core/search/index.ts
index f7172064..c6b784ad 100644
--- a/src/core/search/index.ts
+++ b/src/core/search/index.ts
@@ -293,6 +293,9 @@ const DEFAULTS = {
trigramPrefilterEnabled: false,
trigramPrefilterMinChunks: 5000,
trigramPrefilterMaxSelectivity: 0.5,
+ // Per-source-session pool cap (t_bb6ce095): off at 0, which never runs
+ // the phase and adds no frontmatter reads.
+ poolMaxPerSession: 0,
rerankTopK: 20,
rerankMinScore: 0,
};
@@ -667,6 +670,19 @@ function validateResolvedConfig(config: ResolvedSearchConfig, extraBodySource: s
min: 0,
});
}
+ // Per-source-session pool cap (t_bb6ce095): optional (absent reads as
+ // the off value 0), and never negative - a negative cap would drop
+ // every identified row, which is a misconfiguration, not an off switch.
+ // No upper bound here by design (review L4): a value at or above the
+ // pool width the query resolves cannot drop a row from that pool, and
+ // the assembly treats it as off - the phase never runs - while the
+ // resolved value still folds into the search fingerprint, so a change
+ // around that boundary can never serve a stale cached row.
+ if (config.recall.poolMaxPerSession !== undefined) {
+ validateIntegerRange(config.recall.poolMaxPerSession, "search_pool_max_per_session", {
+ min: 0,
+ });
+ }
validateIntegerRange(config.semantic.concurrency, "embedding_concurrency", {
min: 1,
});
@@ -1354,6 +1370,21 @@ export function resolveSearchConfig(opts: {
"search_pool_multiplier",
{ min: 1, max: 10 },
);
+ // Per-source-session pool cap (t_bb6ce095). No parse-time range: the
+ // integer-range line in `validateResolvedConfig` owns the refusal of
+ // config values, and a per-query override is judged by the same rules
+ // (finite, integer, >= 0) at the assembly's read site
+ // (`resolveSessionPoolCap`).
+ const poolMaxPerSession = parseInteger(
+ envOrConfig(
+ env,
+ config,
+ "OPEN_SECOND_BRAIN_SEARCH_POOL_MAX_PER_SESSION",
+ "search_pool_max_per_session",
+ ),
+ DEFAULTS.poolMaxPerSession,
+ "search_pool_max_per_session",
+ );
const selfTuningEnabled = parseBool(
envOrConfig(env, config, "OPEN_SECOND_BRAIN_SEARCH_SELF_TUNING", "search_self_tuning_enabled"),
false,
@@ -1465,6 +1496,11 @@ export function resolveSearchConfig(opts: {
trigramPrefilterEnabled,
trigramPrefilterMinChunks,
trigramPrefilterMaxSelectivity,
+ // Only the off value stays absent, so exact-shape assertions on the
+ // resolved config keep holding - the relationalRerankPin pattern. A
+ // negative value is spread through so `validateResolvedConfig` owns
+ // its refusal, exactly as it judges a programmatic override.
+ ...(poolMaxPerSession !== DEFAULTS.poolMaxPerSession ? { poolMaxPerSession } : {}),
});
const freshen: ResolvedFreshenConfig = Object.freeze({
diff --git a/src/core/search/pipeline/assemble.ts b/src/core/search/pipeline/assemble.ts
index 7452a30f..bc51176a 100644
--- a/src/core/search/pipeline/assemble.ts
+++ b/src/core/search/pipeline/assemble.ts
@@ -18,6 +18,7 @@ import { rankResults } from "../ranker.ts";
import { applyExactStateBarrier, type FrontmatterCache } from "../result-filters.ts";
import { semanticPoolSize } from "../semantic-phase.ts";
import { applyTemporalBridge } from "../temporal-bridge.ts";
+import { applySessionPoolCap, resolveSessionPoolCap } from "./session-pool-cap.ts";
import { applyPoolFilters, resolvePoolFilters, type FilterContext } from "./pool-filters.ts";
import { RETRIEVAL_DEGRADATION, noteDegradation } from "../retrieval-trail.ts";
import type { RetrievalDegradationSink } from "../retrieval-trail.ts";
@@ -49,6 +50,9 @@ const DUPLICATE_KEY_SEPARATOR = ":";
const NO_TRAVERSAL_HOPS = 0;
const MMR_OFF_LAMBDA = 1;
+/** The per-source-session pool cap is off at zero rows per session. */
+const POOL_CAP_OFF = 0;
+
/**
* One row past the cap: enough to SEE truncation, never enough to change
* the answer. See {@link assembleRankedResults} for why the cap is
@@ -106,6 +110,14 @@ export interface AssemblyInput {
interface Assembly {
readonly preVisibility: number;
readonly prePoolFilters: number;
+ /**
+ * Rows that survived the caller's own filters, BEFORE the session cap
+ * ran over them. The backfill's visibility signal and the trail's
+ * scope-drop count both read this pre-cap count: the cap is not a
+ * caller scope, and lumping its drops in here would report the cap as
+ * one.
+ */
+ readonly filterVisible: number;
readonly visible: ReadonlyArray<BrainSearchResult>;
/** Whether the cap truncated the pool, as opposed to the pool running out. */
readonly capHit: boolean;
@@ -113,6 +125,10 @@ interface Assembly {
readonly mergedAway: number;
/** Ranked rows the caller's relevance floor removed. */
readonly floorDropped: number;
+ /** Filter-passing rows the per-source-session cap dropped. */
+ readonly sessionCapped: number;
+ /** The widest group the cap judged this pass, for the re-widen width. */
+ readonly widestGroupRows: number;
}
/** The location record a merged-away duplicate leaves on its survivor. */
@@ -244,9 +260,19 @@ export function assembleRankedResults(input: AssemblyInput): ReadonlyArray<Brain
);
const maxHops = opts.maxHops ?? config.recall.maxHops;
const traversalActive = maxHops > NO_TRAVERSAL_HOPS;
+ // Per-source-session pool cap (t_bb6ce095): on at a positive cap. The
+ // value in force is validated at this read site (review CR) - the
+ // per-query override used to bypass the config validation, so 1.5
+ // turned the cap on with a fractional comparison and NaN read as off.
+ const poolCap = resolveSessionPoolCap(
+ opts.poolMaxPerSession ?? config.recall.poolMaxPerSession ?? POOL_CAP_OFF,
+ );
+ const capConfigured = poolCap > POOL_CAP_OFF;
const baseRankLimit =
filters.canDropRows || hasStructuredExclusions ? semanticPoolSize(limit) : limit;
- const rankLimit =
+ // The pool width the other recall phases need, judged as if the cap
+ // were off.
+ const rankLimitWithoutCap =
mmrActive || traversalActive || crossEncoderActive
? Math.max(
baseRankLimit,
@@ -255,9 +281,25 @@ export function assembleRankedResults(input: AssemblyInput): ReadonlyArray<Brain
crossEncoderActive ? config.rerank.topK : 0,
)
: baseRankLimit;
+ // When the cap is on it joins the widening, because a cap over an
+ // UNwidened pool merely truncates sooner - the ranked rows it needs to
+ // spread the window across sessions would sit below a rankLimit equal
+ // to `limit`.
+ const capWideRankLimit = capConfigured
+ ? Math.max(rankLimitWithoutCap, limit * POOL_LIMIT_MULTIPLIER, POOL_MIN_WIDTH)
+ : rankLimitWithoutCap;
+ // Review L4: a cap at or above the pool width it would judge cannot
+ // drop a row from that pool - acting on it would read frontmatter for
+ // every row to remove nothing. It is treated as off: the phase never
+ // runs, and the pool keeps the width the other phases chose. The
+ // configured value still folds into the config fingerprint and the
+ // per-query cache key, so a change around this boundary can never
+ // serve a stale cached row.
+ const capActive = capConfigured && poolCap < capWideRankLimit;
+ const rankLimit = capActive ? capWideRankLimit : rankLimitWithoutCap;
- // Rank β†’ traverse β†’ diversify β†’ property filter β†’ visibility scope,
- // for a given candidate cap. Returns the pre-visibility count, the
+ // Rank β†’ traverse β†’ diversify β†’ the caller's filters β†’ the session
+ // cap, for a given candidate cap. Returns the pre-visibility count, the
// post-visibility list, and whether the cap was actually hit (so the
// caller can tell "the pool ran out" from "the cap truncated more").
const assemble = (rankCap: number): Assembly => {
@@ -346,11 +388,39 @@ export function assembleRankedResults(input: AssemblyInput): ReadonlyArray<Brain
if (rerankActive) {
ranked = rerankByRelevance(ranked).slice();
}
+ // The caller's own filters (status, property, degree, reach,
+ // visibility, ownership, session/project scope) run BEFORE the cap
+ // (review M4): only a row the filters admit consumes its group's
+ // quota, so a session whose first rows fail a requested filter is not
+ // erased from the answer by its own failing rows, and a query scoped
+ // to one session still gets up to `cap` rows from it. The cap is
+ // removal-only over the already-filtered pool, so the security
+ // property the filters own holds by construction: it can never
+ // surface a row they would withhold. No-op when the cap is off.
+ const filtered = applyPoolFilters(ranked, filters, filterContext);
+ let sessionCapped = 0;
+ let widestGroupRows = 0;
+ let visible = filtered.visible;
+ if (capActive) {
+ const capped = applySessionPoolCap(filtered.visible, {
+ vault: config.vault,
+ capPerSession: poolCap,
+ frontmatterCache: input.frontmatterCache,
+ });
+ visible = capped.results;
+ sessionCapped = capped.dropped;
+ widestGroupRows = capped.widestGroupRows;
+ }
return {
- ...applyPoolFilters(ranked, filters, filterContext),
+ preVisibility: filtered.preVisibility,
+ prePoolFilters: filtered.prePoolFilters,
+ filterVisible: filtered.visible.length,
+ visible,
capHit,
mergedAway: merge.mergedAway,
floorDropped,
+ sessionCapped,
+ widestGroupRows,
};
};
@@ -359,7 +429,7 @@ export function assembleRankedResults(input: AssemblyInput): ReadonlyArray<Brain
// the answer.
let effectiveCap = rankLimit;
let assembled = assemble(rankLimit);
- // Two phases can leave fewer than `limit` rows out of a pool that was
+ // Three phases can leave fewer than `limit` rows out of a pool that was
// capped at `limit`, while more qualifying matches sit deeper in the
// candidate list:
//
@@ -367,31 +437,50 @@ export function assembleRankedResults(input: AssemblyInput): ReadonlyArray<Brain
// above) drops tagged pages, and the reserved-token rule drops pages
// reserved against this caller's reach; untagged vaults never drop a
// row, so this never fires for them,
- // - the exact-duplicate merge folds byte-identical passages away.
+ // - the exact-duplicate merge folds byte-identical passages away,
+ // - the per-source-session cap dropped filter-passing rows (review
+ // M3): the capped pool can hold fewer than `limit` rows even though
+ // the corpus holds more.
//
- // In either case, and only when the narrow cap was actually hit (as
- // opposed to the candidate list simply running out), re-assemble once
- // at the wider cap from the same in-memory candidates - no extra DB
- // fetch. A pool with no dropped and no merged rows never re-assembles,
- // so its results stay byte-identical.
+ // In any of these cases, and only when the narrow cap was actually hit
+ // (as opposed to the candidate list simply running out - without a
+ // truncation there is nothing deeper to admit), re-assemble ONCE at the
+ // wider cap from the same in-memory candidates - no extra DB fetch. A
+ // pool with no dropped and no merged rows never re-assembles, so its
+ // results stay byte-identical.
const visibilityDropped =
- !filters.canDropRows && assembled.visible.length < assembled.prePoolFilters;
+ !filters.canDropRows && assembled.filterVisible < assembled.prePoolFilters;
+ const sessionUnderfilled = assembled.sessionCapped > 0;
if (
assembled.visible.length < limit &&
assembled.capHit &&
- (visibilityDropped || assembled.mergedAway > 0)
+ (visibilityDropped || assembled.mergedAway > 0 || sessionUnderfilled)
) {
const wideCap = Math.max(
semanticPoolSize(limit),
limit * POOL_LIMIT_MULTIPLIER,
POOL_MIN_WIDTH,
+ // The re-widen contract (review M3): outrun the heaviest group the
+ // first pass observed. `widestGroupRows` rows of one group fit in
+ // the width just judged; a window of `limit` rows is refillable
+ // from the groups the cap did not exhaust only if they are
+ // reachable, so rank `limit * (widestGroupRows + 1)` - one more
+ // pass, at a width that covers the heavy group's occupancy as the
+ // first pass's mix observed it. Best-effort, not a guarantee: the
+ // second pass admits deeper rows, so a heavier-than-observed
+ // occupancy (rank skewed hard toward the heavy group) can crowd
+ // the window again and answer short even though the corpus holds
+ // outside rows - and a corpus that holds nothing outside the heavy
+ // group always does. The trail names the final pass's numbers
+ // honestly rather than retrying.
+ sessionUnderfilled ? limit * (assembled.widestGroupRows + 1) : 0,
);
if (wideCap > rankLimit) {
assembled = assemble(wideCap);
effectiveCap = wideCap;
}
}
- noteAssemblyNarrowings(input.degraded, assembled, effectiveCap);
+ noteAssemblyNarrowings(input.degraded, assembled, effectiveCap, poolCap);
return assembled.visible;
}
@@ -405,6 +494,7 @@ function noteAssemblyNarrowings(
sink: RetrievalDegradationSink,
assembled: Assembly,
cap: number,
+ poolCap: number,
): void {
if (assembled.capHit) {
noteDegradation(sink, RETRIEVAL_DEGRADATION.rankCapTruncatedPool, { cap });
@@ -414,13 +504,22 @@ function noteAssemblyNarrowings(
dropped: assembled.floorDropped,
});
}
+ if (assembled.sessionCapped > 0) {
+ noteDegradation(sink, RETRIEVAL_DEGRADATION.sourceSessionCappedRows, {
+ dropped: assembled.sessionCapped,
+ cap: poolCap,
+ });
+ }
// `preVisibility` is the row count before the visibility, ownership and
// composite session/project scopes the CALLER requested ran - the reach
// rule is already counted out of it. The difference is the answer to
// "did a scope remove my results", which nothing could ask before; the
// reach rule is not one of those scopes, and its drop count is withheld
- // rather than published (see `pipeline/pool-filters.ts`).
- const scoped = assembled.preVisibility - assembled.visible.length;
+ // rather than published (see `pipeline/pool-filters.ts`). The comparison
+ // reads the PRE-CAP filtered count (`filterVisible`), never `visible`:
+ // the session cap is not a caller scope, its drops carry their own code
+ // above, and counting them here would report the cap as a scope.
+ const scoped = assembled.preVisibility - assembled.filterVisible;
if (scoped > 0) {
noteDegradation(sink, RETRIEVAL_DEGRADATION.scopeFiltersDroppedRows, {
dropped: scoped,
diff --git a/src/core/search/pipeline/cache-slot.ts b/src/core/search/pipeline/cache-slot.ts
index e64f5242..864534a1 100644
--- a/src/core/search/pipeline/cache-slot.ts
+++ b/src/core/search/pipeline/cache-slot.ts
@@ -274,8 +274,12 @@ const FINGERPRINT_OFF = "off";
* semantic toggle, recall tunables) invalidates cached rows alongside the
* corpus generation. Cache-only knobs (enable/TTL) are excluded - they do
* not change result content.
+ *
+ * Exported for the config tests, which pin that every results-affecting
+ * knob re-keys the fingerprint: a knob missing here serves stale cached
+ * rows.
*/
-function configFingerprint(config: ResolvedSearchConfig): string {
+export function configFingerprint(config: ResolvedSearchConfig): string {
const r = config.recall;
return JSON.stringify({
kw: config.keywordWeight,
@@ -340,6 +344,11 @@ function configFingerprint(config: ResolvedSearchConfig): string {
tri: r.trigramPrefilterEnabled,
triMin: r.trigramPrefilterMinChunks,
triSel: r.trigramPrefilterMaxSelectivity,
+ // The per-source-session pool cap (t_bb6ce095) changes which rows
+ // survive the assembled pool, so a knob change must invalidate cached
+ // rows. Present only when the cap is on (the resolved field is
+ // spread-omitted at 0), so every off key is unchanged.
+ ...(r.poolMaxPerSession !== undefined ? { poolCap: r.poolMaxPerSession } : {}),
// The query embed is fitted to the effective input window with the
// instruction prefix the provider sends counted in, so either one
// changes the text embedded (and whether it was cut): a declared or
diff --git a/src/core/search/pipeline/session-pool-cap.ts b/src/core/search/pipeline/session-pool-cap.ts
new file mode 100644
index 00000000..a72151c2
--- /dev/null
+++ b/src/core/search/pipeline/session-pool-cap.ts
@@ -0,0 +1,164 @@
+/**
+ * The per-source-session pool cap (t_bb6ce095): bound how many ranked
+ * rows one group may contribute to the filtered pool the caller's window
+ * is cut from.
+ *
+ * A row's group key is its SOURCE import session when the note states
+ * one - `session_ref` frontmatter on imported signal notes, `session_id`
+ * on handoff notes - and the row's own PATH otherwise. The fallback is
+ * the review fix (M2): the crowding this cap was built to measure comes
+ * from material that carries no session frontmatter at all - bench
+ * session notes (the LongMemEval and LoCoMo converters write plain
+ * bodies) and the several chunks of one long note - so grouping by
+ * frontmatter alone capped nothing there, byte for byte. All chunks of
+ * one note share a path, so the fallback groups exactly that note. The
+ * three key kinds are namespaced apart (`ref:`, `id:` and `path:`
+ * prefixes), so no two kinds can collide regardless of the value: even a
+ * session value that itself begins with `path:` stays in the session key
+ * space and cannot fuse with the note it names. An unreadable file
+ * falls back to its path too: the path is a real identity even when the
+ * frontmatter behind it cannot be read, and the chunks of one unreadable
+ * note are one group for the same reason.
+ *
+ * Identity rides the per-call frontmatter cache the assemble stage
+ * already builds - one parsed read per path, shared with every other
+ * filter - so the cap adds no new read shape to the pipeline.
+ *
+ * Byte-identity is an OFF-path property only: at the off value the phase
+ * never runs and reads nothing. When the knob is on, every row names a
+ * group (a session or a path), so any vault can have rows capped - there
+ * is no longer a class of vault the cap cannot see into.
+ */
+
+import { readCachedFrontmatterEntry, type FrontmatterCache } from "../result-filters.ts";
+import { SearchError } from "../types.ts";
+import type { BrainSearchResult } from "../types.ts";
+
+/** Frontmatter key naming the SOURCE import session (signal notes). */
+const SESSION_REF_KEY = "session_ref";
+/** Frontmatter key naming the source session (handoff notes). */
+const SESSION_ID_KEY = "session_id";
+/**
+ * Namespaces of the three group-key kinds. One map holds all of them, and
+ * the disjoint prefixes make cross-kind collisions impossible by
+ * construction: whatever a session value says - including a value that
+ * itself begins with one of these prefixes - it lands in its own key
+ * space and cannot fuse with another kind's group.
+ */
+const REF_GROUP_PREFIX = "ref:";
+const ID_GROUP_PREFIX = "id:";
+const PATH_GROUP_PREFIX = "path:";
+
+/** The cap result: surviving rows in ranked order, plus the drop count. */
+export interface SessionPoolCapResult {
+ readonly results: BrainSearchResult[];
+ /** Rows the cap removed, summed across every group. */
+ readonly dropped: number;
+ /**
+ * The largest number of input rows any single group held, whether or
+ * not the cap dropped from it. The caller's re-widen contract (review
+ * M3) reads it: a window the cap under-filled needs a pool wide enough
+ * that the groups it did not exhaust can fill the remaining slots, and
+ * this is the observed occupancy that width has to outrun.
+ */
+ readonly widestGroupRows: number;
+}
+
+/** What the cap reads per row: the vault root, the cap, the shared cache. */
+export interface SessionPoolCapOptions {
+ readonly vault: string;
+ /**
+ * Rows one group may keep, in ranked order. Must be a non-negative
+ * integer; the caller gates the phase on the configured knob being on,
+ * so zero never reaches this module.
+ */
+ readonly capPerSession: number;
+ readonly frontmatterCache: FrontmatterCache;
+}
+
+/**
+ * Validate the cap value in force for one query - the per-query
+ * `poolMaxPerSession` override, else the resolved config value - under
+ * the same rules `validateResolvedConfig` applies to the config key.
+ *
+ * The per-query path used to bypass that gate (review CR): a fractional
+ * value turned the cap on with a fractional comparison (`seen >= 1.5`
+ * kept two rows), NaN silently read as off, and a negative as
+ * drop-every-identified-row. A malformed value is refused by name,
+ * through the same INVALID_INPUT error path the config refusal uses.
+ * The refusal fires at the assemble stage's read site, before any
+ * ranking, cap grouping or result assembly runs and before anything is
+ * written - but after the lane fetch and hydration a refused query has
+ * already paid. `0` stays legal: it is the documented per-query off
+ * switch.
+ */
+export function resolveSessionPoolCap(value: number): number {
+ if (!Number.isFinite(value)) {
+ throw new SearchError(
+ "INVALID_INPUT",
+ `poolMaxPerSession must be a finite number, got '${value}'`,
+ );
+ }
+ if (!Number.isInteger(value)) {
+ throw new SearchError("INVALID_INPUT", `poolMaxPerSession must be an integer, got ${value}`);
+ }
+ if (value < 0) {
+ throw new SearchError("INVALID_INPUT", `poolMaxPerSession must be >= 0, got ${value}`);
+ }
+ return value;
+}
+
+/**
+ * The group key of a ranked row.
+ *
+ * `session_ref` wins over `session_id` when a row carries both (imported
+ * material is what crowds a pool). Only a non-empty string names a
+ * session - an empty or non-typed frontmatter value is absent identity -
+ * and an unreadable file has no frontmatter to speak of, so it lands on
+ * the same path fallback as a note that never carried any.
+ */
+function sessionKey(vault: string, r: BrainSearchResult, cache: FrontmatterCache): string {
+ const { meta } = readCachedFrontmatterEntry(cache, vault, r.path);
+ const ref = meta[SESSION_REF_KEY];
+ if (typeof ref === "string" && ref !== "") return `${REF_GROUP_PREFIX}${ref}`;
+ const id = meta[SESSION_ID_KEY];
+ if (typeof id === "string" && id !== "") return `${ID_GROUP_PREFIX}${id}`;
+ return `${PATH_GROUP_PREFIX}${r.path}`;
+}
+
+/**
+ * Cap every group's contribution to the ranked pool.
+ *
+ * The first {@link SessionPoolCapOptions.capPerSession} rows of each
+ * group survive, in the order the ranker produced; the rest are dropped
+ * and counted, so the caller can name the narrowing and compute the
+ * re-widen width. Pure: the same rows and a same-filled cache answer
+ * identically, and the only cache effect is the read-through fill every
+ * other filter stage already causes.
+ */
+export function applySessionPoolCap(
+ ranked: ReadonlyArray<BrainSearchResult>,
+ opts: SessionPoolCapOptions,
+): SessionPoolCapResult {
+ const kept: BrainSearchResult[] = [];
+ // Input rows per group (the density the re-widen outruns) and kept
+ // rows per group (the quota actually consumed).
+ const groupInput = new Map<string, number>();
+ const groupKept = new Map<string, number>();
+ let widestGroupRows = 0;
+ let dropped = 0;
+ for (const r of ranked) {
+ const key = sessionKey(opts.vault, r, opts.frontmatterCache);
+ const held = (groupInput.get(key) ?? 0) + 1;
+ groupInput.set(key, held);
+ if (held > widestGroupRows) widestGroupRows = held;
+ const seen = groupKept.get(key) ?? 0;
+ if (seen >= opts.capPerSession) {
+ dropped += 1;
+ continue;
+ }
+ groupKept.set(key, seen + 1);
+ kept.push(r);
+ }
+ return { results: kept, dropped, widestGroupRows };
+}
diff --git a/src/core/search/query-cache.ts b/src/core/search/query-cache.ts
index 848e5e46..630d63f6 100644
--- a/src/core/search/query-cache.ts
+++ b/src/core/search/query-cache.ts
@@ -161,6 +161,12 @@ export function buildCacheKey(
// promoted properties need no separate input - they are part of
// `properties`, already canonicalized above.
kind: opts.kind ?? undefined,
+ // Per-source-session pool cap override (t_bb6ce095) partitions the
+ // cache: an explicit `0` forces the cap off for this query, which
+ // differs from the config default. Dropped when absent, so a query
+ // that does not touch the knob keys byte-identically to a pre-knob
+ // row.
+ poolMaxPerSession: opts.poolMaxPerSession ?? undefined,
structuredQuery: canonicalStructuredQuery(opts),
sessionFocus: canonicalSessionFocus(opts),
plan: planHash,
diff --git a/src/core/search/retrieval-trail.ts b/src/core/search/retrieval-trail.ts
index 33f449ea..85857382 100644
--- a/src/core/search/retrieval-trail.ts
+++ b/src/core/search/retrieval-trail.ts
@@ -181,6 +181,18 @@ export const RETRIEVAL_DEGRADATION = Object.freeze({
* looking like a vault with no match.
*/
relevanceFloorDroppedRows: "relevance-floor-dropped-rows",
+ /**
+ * The per-source-session pool cap (t_bb6ce095) dropped ranked rows
+ * whose source import session was already represented at the cap. The
+ * cap runs after the caller's own filters, so only filter-passing rows
+ * consume a session's quota, and it is removal-only: it can never
+ * surface a row those filters would withhold. `detail.dropped` counts
+ * them against `detail.cap`, the per-session cap in force - the FINAL
+ * pass's numbers, because an under-filled window earns one re-widen.
+ * The name says SOURCE session - the import a note came from - so the
+ * code never reads as the caller's session focus.
+ */
+ sourceSessionCappedRows: "source-session-capped-rows",
/**
* Visibility, ownership or session/project scope dropped ranked rows.
* `detail.dropped` counts them against `detail.before`, so a scope that
@@ -225,6 +237,7 @@ export const RETRIEVAL_DEGRADATION_CODES: ReadonlyArray<RetrievalDegradationCode
RETRIEVAL_DEGRADATION.rerankProviderUnavailable,
RETRIEVAL_DEGRADATION.rerankModelSunset,
RETRIEVAL_DEGRADATION.relevanceFloorDroppedRows,
+ RETRIEVAL_DEGRADATION.sourceSessionCappedRows,
RETRIEVAL_DEGRADATION.scopeFiltersDroppedRows,
RETRIEVAL_DEGRADATION.crossVaultOriginFailed,
RETRIEVAL_DEGRADATION.crossVaultChainStopped,
@@ -440,6 +453,8 @@ export function describeRetrievalDegradation(code: RetrievalDegradationCode): st
return "the configured rerank model is past its announced shutdown date, so no rerank request was made and this answer keeps the heuristic order";
case RETRIEVAL_DEGRADATION.relevanceFloorDroppedRows:
return "the requested relevance floor dropped every ranked row it judged, so matches below it are not in this answer";
+ case RETRIEVAL_DEGRADATION.sourceSessionCappedRows:
+ return "the per-source-session pool cap dropped ranked rows whose source import session already held its share of the pool; when that left the window under-filled, the pool was re-widened once before this answer was cut";
case RETRIEVAL_DEGRADATION.scopeFiltersDroppedRows:
return "visibility, ownership or session scope dropped ranked rows, so this answer is narrower than the match set";
case RETRIEVAL_DEGRADATION.crossVaultOriginFailed:
diff --git a/src/core/search/types.ts b/src/core/search/types.ts
index 23f7d6c0..ce5220b4 100644
--- a/src/core/search/types.ts
+++ b/src/core/search/types.ts
@@ -922,6 +922,17 @@ export interface SearchOptions {
* resolved config default; `0` disables traversal for this query.
*/
readonly maxHops?: number;
+ /**
+ * Per-query per-source-session pool cap override (t_bb6ce095). Absent
+ * uses the resolved config default; `0` is the documented off value and
+ * forces the cap off for this query. Validated like the config key: a
+ * fractional, negative or non-finite override is refused by name
+ * (INVALID_INPUT) before the pipeline runs. A value at or above the
+ * pool width the query resolves cannot drop a row and behaves as off,
+ * while still keying the query cache - crossing that boundary can
+ * never serve a stale cached row.
+ */
+ readonly poolMaxPerSession?: number;
/**
* Requested content-visibility scope (v3 / typed graph semantics).
* Pages with no `visibility:` frontmatter are always returned;
@@ -1721,6 +1732,25 @@ export interface ResolvedRecallConfig {
* construct this shape literally) reads as false.
*/
readonly metadataBoostGateEnabled?: boolean;
+ /**
+ * Per-source-session pool cap (t_bb6ce095), resolved from
+ * `search_pool_max_per_session`. The maximum rows ONE group may
+ * contribute to the filtered candidate pool the caller's window is cut
+ * from. A row's group is its source import session (`session_ref`,
+ * else `session_id` frontmatter) or, when the note names neither, its
+ * own path - all chunks of one note form one group, which is what
+ * makes frontmatter-less bench session notes capable. The cap runs
+ * after the caller's own filters, so only filter-passing rows consume
+ * a quota, and it is removal-only: it never surfaces a row those
+ * filters would withhold. 0 is off: the phase never runs and no
+ * frontmatter reads are added, so results are byte-identical. A value
+ * at or above the pool width the query resolves cannot drop a row and
+ * is treated as off, while still folding into the search fingerprint -
+ * crossing that boundary can never serve a stale cached row. Absent
+ * (configs written before the knob construct this shape literally)
+ * reads as 0.
+ */
+ readonly poolMaxPerSession?: number;
}
/** What freshen-on-read does; see `src/core/search/freshen.ts`. */
diff --git a/src/core/surface/skill-attach.ts b/src/core/surface/skill-attach.ts
index a0eae481..dc39cfc3 100644
--- a/src/core/surface/skill-attach.ts
+++ b/src/core/surface/skill-attach.ts
@@ -4,9 +4,16 @@
* Deterministic per-turn skill relevance: score discovered skills
* against the current turn text with the shared lexical scorer and
* render a small Markdown block of the top matches. No LLM in the
- * loop; the same query and skill set always produce the same block.
- * The char budget drops whole trailing entries - a half-rendered
- * skill line would read as a different skill.
+ * loop; the same query, skill set and usage input always produce the
+ * same block. The char budget drops whole trailing entries - a
+ * half-rendered skill line would read as a different skill.
+ *
+ * Ranking is the scorer's by default. When the caller supplies a usage
+ * weight map (t_5d1ec8a8), candidates near the top are reordered by a
+ * bounded composite of lexical score and observed invocation weight
+ * (see {@link SKILL_USAGE_ORDERING_MAX_BOOST}); with the input absent
+ * the output is byte-identical to the scorer's order, so existing
+ * callers are untouched.
*
* Two properties were added in t_ccb05134:
*
@@ -59,6 +66,19 @@ export interface BuildSkillAttachmentOptions {
* false (name 3x + description 1x only).
*/
readonly includeTriggers?: boolean;
+ /**
+ * Observed usage weight per discovered skill name, from
+ * `skillUsageRankingWeights` (`../brain/skill-usage.ts`) - the ranking
+ * weight, which normalises frequency against the largest joined count
+ * and so does not saturate the way the decay weight `deriveSkillUsage`
+ * reports does. When set and
+ * non-empty, candidates near the top are reordered by
+ * {@link SKILL_USAGE_ORDERING_MAX_BOOST}-bounded composite instead of
+ * raw lexical score. Absent or empty keeps the scorer's order
+ * (default off); the `score` field of every item stays the lexical
+ * score either way, and the floor is never crossable by weight.
+ */
+ readonly usageWeight?: ReadonlyMap<string, number>;
}
export const DEFAULT_MAX_SKILLS = 3;
@@ -94,6 +114,20 @@ const OFFER_LINE_BUDGET =
*/
export const DISCRIMINATING_TERM_CORPUS_SHARE = 0.5;
+/**
+ * Largest multiplicative gain a usage weight may add to a candidate's
+ * lexical score when the attach ordering runs with a usage map
+ * (t_5d1ec8a8): the composite is
+ * `score * (1 + SKILL_USAGE_ORDERING_MAX_BOOST * weight)` with weights in
+ * (0, 1], so a candidate rises by at most half again its own lexical
+ * score. Relevance stays primary - a wide lexical gap is never closed by
+ * usage, only the near-ties the scorer cannot see break toward the skill
+ * an agent actually invokes. The floor applies before the composite, so
+ * no weight resurrects a non-discriminating candidate; the reported
+ * `score` stays the untouched lexical score.
+ */
+export const SKILL_USAGE_ORDERING_MAX_BOOST = 0.5;
+
/**
* Whether at least one term this candidate matched separates it from the
* rest of the corpus.
@@ -117,15 +151,41 @@ function emptyAttachment(): SkillAttachment {
* shortlist from the same ranking and never adds anything outside it.
*/
export function rankSkillCandidates(
- opts: Pick<BuildSkillAttachmentOptions, "query" | "skills" | "includeTriggers">,
+ opts: Pick<BuildSkillAttachmentOptions, "query" | "skills" | "includeTriggers" | "usageWeight">,
limit: number,
): SkillAttachItem[] {
const byName = new Map(opts.skills.map((s) => [s.name, s]));
const descriptors = skillDescriptors(opts.skills, opts.includeTriggers);
- const ranked = scoreDescriptors(opts.query, descriptors)
- // The floor filters, it never reorders: ranking stays the scorer's.
- .filter((scored) => hasDiscriminatingMatch(scored, descriptors.length))
- .slice(0, limit);
+ const surviving = scoreDescriptors(opts.query, descriptors)
+ // The floor filters, it never reorders, and no usage weight crosses it:
+ // a candidate dropped here stays dropped. Without a usage map ranking
+ // stays the scorer's; with one, the bounded composite below reorders
+ // the survivors.
+ .filter((scored) => hasDiscriminatingMatch(scored, descriptors.length));
+ const usageWeight = opts.usageWeight;
+ const ranked =
+ usageWeight === undefined
+ ? surviving.slice(0, limit)
+ : surviving
+ .map((scored) => ({
+ scored,
+ // Missing name means no observed invocation: weight 0, which
+ // leaves the composite at the lexical score.
+ composite:
+ scored.score *
+ (1 + SKILL_USAGE_ORDERING_MAX_BOOST * (usageWeight.get(scored.descriptor.name) ?? 0)),
+ }))
+ .toSorted(
+ (a, b) =>
+ b.composite - a.composite ||
+ (a.scored.descriptor.name < b.scored.descriptor.name
+ ? -1
+ : a.scored.descriptor.name > b.scored.descriptor.name
+ ? 1
+ : 0),
+ )
+ .slice(0, limit)
+ .map((entry) => entry.scored);
const items: SkillAttachItem[] = [];
for (const { descriptor, score } of ranked) {
const skill = byName.get(descriptor.name);
diff --git a/src/mcp/skill-tools.ts b/src/mcp/skill-tools.ts
index 5d102776..c6b894a7 100644
--- a/src/mcp/skill-tools.ts
+++ b/src/mcp/skill-tools.ts
@@ -15,6 +15,7 @@ import {
resolveSkillAutoAttach,
resolveSkillsDir,
resolveSkillsAttachTriggers,
+ resolveSkillsAttachUsageOrdering,
resolveTokenImpactLedgerEnabled,
} from "../core/config.ts";
import {
@@ -22,6 +23,7 @@ import {
resolveDecisionModelConfig,
type ResolvedDecisionModelConfig,
} from "../core/decision-model/config.ts";
+import { deriveSkillUsage, skillUsageRankingWeights } from "../core/brain/skill-usage.ts";
import { buildSkillAttachment, type SkillAttachment } from "../core/surface/skill-attach.ts";
import {
buildSkillAttachmentWithDecision,
@@ -172,15 +174,36 @@ function toolSkillsAttach(
}
const includeTriggers = resolveSkillsAttachTriggers(ctx.configPath ?? undefined);
const skills = discoverSkills(rootsFor(ctx));
- const decisionConfig = skillsDecisionConfig(ctx);
- if (decisionConfig === null) {
- return attachResult(buildSkillAttachment({ query, skills, maxSkills, includeTriggers }));
- }
- return buildSkillAttachmentWithDecision({
+ // Usage-ordered offers (t_5d1ec8a8), default off: with the ordering knob
+ // on, the whole continuity store is read exactly once per attach call and
+ // the same weight map feeds both build paths, so the deterministic and
+ // decision-model offers stay coherent. Off, the vault is never read here.
+ // The map is the ranking weight (skillUsageRankingWeights), not the decay
+ // weight deriveSkillUsage reports: that one clamps at 1, so among recently
+ // used skills frequency was invisible and the name tie-break decided. One
+ // pinned clock feeds both derivations, so the counts and the recency half
+ // of the weight never disagree about what "now" is.
+ const nowMs = Date.now();
+ const usageWeight = resolveSkillsAttachUsageOrdering(ctx.configPath ?? undefined)
+ ? skillUsageRankingWeights(
+ deriveSkillUsage(ctx.vault, { nowMs }),
+ new Set(skills.map((s) => s.name)),
+ { nowMs },
+ )
+ : undefined;
+ const attachmentOpts = {
query,
skills,
maxSkills,
includeTriggers,
+ ...(usageWeight !== undefined ? { usageWeight } : {}),
+ };
+ const decisionConfig = skillsDecisionConfig(ctx);
+ if (decisionConfig === null) {
+ return attachResult(buildSkillAttachment(attachmentOpts));
+ }
+ return buildSkillAttachmentWithDecision({
+ ...attachmentOpts,
config: decisionConfig,
tokenImpact: resolveTokenImpactLedgerEnabled(ctx.configPath ?? undefined),
}).then((attachment) => attachResult(attachment, attachment.decisionModel));
@@ -228,7 +251,7 @@ export const SKILL_TOOLS: ReadonlyArray<ToolDefinition> = [
{
name: "skills_attach",
description:
- "Score skills against the current turn text; returns a char-budgeted block of relevant summaries and the offer_id to cite on get_skill (null when none was offered). A candidate matching only terms most of the corpus carries is dropped, not offered. enabled:false unless skill_auto_attach is set.",
+ "Score skills against the turn text; returns a char-budgeted block of relevant summaries and the offer_id to cite on get_skill (null when none). Candidates without a discriminating term are dropped. Usage-ordered when skills_attach_usage_ordering is on. enabled:false unless skill_auto_attach is set.",
inputSchema: {
type: "object",
properties: {
diff --git a/tests/cli/bootstrap.test.ts b/tests/cli/bootstrap.test.ts
index 3316ab09..8fc826a7 100644
--- a/tests/cli/bootstrap.test.ts
+++ b/tests/cli/bootstrap.test.ts
@@ -717,6 +717,21 @@ describe("o2b bootstrap when the adapter apply fails after a mint (opencode)", (
return join(opencodeHome, "opencode", "opencode.json");
}
+ test("bootstrap --target opencode lands in an existing V2 mcp.servers config", async () => {
+ mkdirSync(join(opencodeHome, "opencode"), { recursive: true });
+ writeFileSync(opencodeConfigPath(), JSON.stringify({ mcp: { servers: {} } }, null, 2) + "\n");
+ const r = await runCli(
+ bootstrapArgs(["--target", "opencode", "--agent", OPENCODE_AGENT, "--token"]),
+ { env: { XDG_CONFIG_HOME: opencodeHome } },
+ );
+ expect(r.returncode).toBe(0);
+ const parsed = JSON.parse(readFileSync(opencodeConfigPath(), "utf8"));
+ expect(parsed.mcp.servers["open-second-brain"]).toBeDefined();
+ expect(parsed.mcp.servers["open-second-brain-writer"]).toBeDefined();
+ // No shadowing copy under the legacy top-level key.
+ expect(parsed.mcp["open-second-brain"]).toBeUndefined();
+ }, 20000);
+
test("a rotate into a hand-edited config still shows the material exactly once and names the retry path", async () => {
mkdirSync(opencodeHome, { recursive: true });
const env = { XDG_CONFIG_HOME: opencodeHome };
diff --git a/tests/cli/brain-bench.test.ts b/tests/cli/brain-bench.test.ts
index abafc613..090cecc9 100644
--- a/tests/cli/brain-bench.test.ts
+++ b/tests/cli/brain-bench.test.ts
@@ -10,14 +10,18 @@ import { existsSync, mkdtempSync, readFileSync, readdirSync, rmSync, writeFileSy
import { tmpdir } from "node:os";
import { join } from "node:path";
+import { VERB_HELP } from "../../src/cli/brain/help-text.ts";
import {
benchSuite,
benchSuiteNames,
parseBenchPinnedKnobs,
parseRecallFloorFlag,
+ parseSampleCapFlag,
+ parseSampleSeedFlag,
registerBenchSuite,
} from "../../src/cli/brain/verbs/bench.ts";
import { parseBenchFixture } from "../../src/core/bench/fixture.ts";
+import type { BenchSuiteLoadOptions } from "../../src/core/bench/types.ts";
import { runCli } from "../helpers/run-cli.ts";
let tmp: string;
@@ -444,3 +448,297 @@ describe("bench knob pin and recall floor", () => {
expect(() => parseRecallFloorFlag("-1")).toThrow(/got '-1'/);
});
});
+
+/**
+ * The seeded sampling flags (wiring-shipped-seams wave, t_4501c662):
+ * `--sample-seed` and `--sample-cap` are a PAIR - refused singly and on
+ * any suite that does not declare the sampling capability - and
+ * together they reach the suite loader as
+ * `BenchSuiteLoadOptions { sample }`. Omitting both leaves today's CLI
+ * behavior byte-identical.
+ */
+describe("bench sampling flags", () => {
+ const SAMPLING_SUITE = "sampling-stub";
+ const SAMPLING_FIXTURE = parseBenchFixture({
+ name: "sampling-stub",
+ notes: [{ path: "Brain/notes/a.md", body: "alpha note" }],
+ questions: [
+ { id: "q1", category: "single_hop", query: "alpha", expected_paths: ["Brain/notes/a.md"] },
+ ],
+ });
+ /** Every loader invocation with the options object it received. */
+ const samplingLoaderCalls: Array<{ path: string; options: BenchSuiteLoadOptions }> = [];
+
+ registerBenchSuite(SAMPLING_SUITE, {
+ // The second parameter is OPTIONAL by contract: a suite registered
+ // before an option existed keeps its one-parameter loader and never
+ // sees the request. This stub declares it to record what arrives.
+ loader: (fixturePath: string, options?: BenchSuiteLoadOptions) => {
+ samplingLoaderCalls.push({ path: fixturePath, options: options ?? {} });
+ return { fixture: SAMPLING_FIXTURE };
+ },
+ capabilities: { embeddings: false, sampling: true },
+ });
+
+ beforeEach(() => {
+ samplingLoaderCalls.length = 0;
+ });
+
+ test("the sampling flag validators refuse garbage by name", () => {
+ expect(parseSampleSeedFlag(undefined)).toBeUndefined();
+ expect(parseSampleSeedFlag("run-42")).toBe("run-42");
+ // pr-251 L2: the parser validates but does not transform - the
+ // sampler trims the seed in one place before hashing, so the CLI and
+ // the API path hash the same value for the same input, and a padded
+ // seed reaches the loader verbatim.
+ expect(parseSampleSeedFlag(" seed-1 ")).toBe(" seed-1 ");
+ expect(() => parseSampleSeedFlag(" ")).toThrow(/--sample-seed/);
+ expect(parseSampleCapFlag(undefined)).toBeUndefined();
+ expect(parseSampleCapFlag("12")).toBe(12);
+ expect(() => parseSampleCapFlag("0")).toThrow(/got '0'/);
+ expect(() => parseSampleCapFlag("-2")).toThrow(/got '-2'/);
+ expect(() => parseSampleCapFlag("1.5")).toThrow(/got '1.5'/);
+ expect(() => parseSampleCapFlag("abc")).toThrow(/got 'abc'/);
+ });
+
+ test("--sample-seed alone is refused by name", async () => {
+ const out = await runCli(
+ [
+ "brain",
+ "bench",
+ "memory",
+ "--fixture",
+ "core-recall",
+ "--runs-dir",
+ runsDir,
+ "--sample-seed",
+ "seed-1",
+ ],
+ {},
+ );
+ expect(out.returncode).not.toBe(0);
+ expect(out.stderr).toContain("--sample-seed and --sample-cap must be given together");
+ });
+
+ test("--sample-cap alone is refused by name", async () => {
+ const out = await runCli(
+ [
+ "brain",
+ "bench",
+ "memory",
+ "--fixture",
+ "core-recall",
+ "--runs-dir",
+ runsDir,
+ "--sample-cap",
+ "4",
+ ],
+ {},
+ );
+ expect(out.returncode).not.toBe(0);
+ expect(out.stderr).toContain("--sample-seed and --sample-cap must be given together");
+ });
+
+ test("a non-positive or non-integer cap is refused naming the value", async () => {
+ for (const cap of ["0", "-2", "1.5", "abc"]) {
+ const out = await runCli(
+ [
+ "brain",
+ "bench",
+ "memory",
+ "--fixture",
+ "core-recall",
+ "--sample-seed",
+ "seed-1",
+ "--sample-cap",
+ cap,
+ ],
+ {},
+ );
+ expect(out.returncode).not.toBe(0);
+ expect(out.stderr).toContain(`--sample-cap must be a positive integer, got '${cap}'`);
+ }
+ });
+
+ test("an empty seed is refused naming the flag", async () => {
+ const out = await runCli(
+ [
+ "brain",
+ "bench",
+ "memory",
+ "--fixture",
+ "core-recall",
+ "--sample-seed",
+ " ",
+ "--sample-cap",
+ "4",
+ ],
+ {},
+ );
+ expect(out.returncode).not.toBe(0);
+ expect(out.stderr).toContain("--sample-seed must be a non-empty string");
+ });
+
+ test("both flags without a sampling-capable suite are refused naming the suite", async () => {
+ for (const suite of ["locomo", "surfacing-replay"]) {
+ const out = await runCli(
+ [
+ "brain",
+ "bench",
+ "memory",
+ "--fixture",
+ "core-recall",
+ "--suite",
+ suite,
+ "--sample-seed",
+ "seed-1",
+ "--sample-cap",
+ "4",
+ ],
+ {},
+ );
+ expect(out.returncode).not.toBe(0);
+ expect(out.stderr).toContain(`suite '${suite}' does not declare it`);
+ }
+ // The no-suite default path has no sampling capability either.
+ const noSuite = await runCli(
+ [
+ "brain",
+ "bench",
+ "memory",
+ "--fixture",
+ "core-recall",
+ "--sample-seed",
+ "seed-1",
+ "--sample-cap",
+ "4",
+ ],
+ {},
+ );
+ expect(noSuite.returncode).not.toBe(0);
+ expect(noSuite.stderr).toContain("no --suite was given");
+ });
+
+ test("both flags with a sampling-capable suite reach the loader as a sample request", async () => {
+ const out = await runCli(
+ [
+ "brain",
+ "bench",
+ "memory",
+ "--fixture",
+ "core-recall",
+ "--suite",
+ SAMPLING_SUITE,
+ "--sample-seed",
+ "seed-1",
+ "--sample-cap",
+ "3",
+ "--runs-dir",
+ runsDir,
+ "--json",
+ ],
+ {},
+ );
+ expect(out.returncode).toBe(0);
+ expect(samplingLoaderCalls).toEqual([
+ {
+ path: join("tests", "fixtures", "bench", "core-recall.json"),
+ options: { sample: { seed: "seed-1", cap: 3 } },
+ },
+ ]);
+ const report = JSON.parse(out.stdout) as { fixture: string };
+ expect(report.fixture).toBe("sampling-stub");
+ }, 60_000);
+
+ test("omitting the flags passes empty load options - the off path is unchanged", async () => {
+ const out = await runCli(
+ [
+ "brain",
+ "bench",
+ "memory",
+ "--fixture",
+ "core-recall",
+ "--suite",
+ SAMPLING_SUITE,
+ "--runs-dir",
+ runsDir,
+ "--json",
+ ],
+ {},
+ );
+ expect(out.returncode).toBe(0);
+ expect(samplingLoaderCalls).toEqual([
+ { path: join("tests", "fixtures", "bench", "core-recall.json"), options: {} },
+ ]);
+ }, 60_000);
+
+ test("the longmemeval suite samples through the flags and pins the run identity", async () => {
+ // The committed sample carries 3 eligible questions across 3 types;
+ // a cap of 2 selects 2, the CLI line reports the sampled count, and
+ // the run checkpoint carries the sampling request - so a resumed run
+ // under different sampling options fails the identity guard.
+ const out = await runCli(
+ [
+ "brain",
+ "bench",
+ "memory",
+ "--fixture",
+ "longmemeval-sample",
+ "--suite",
+ "longmemeval",
+ "--sample-seed",
+ "seed-1",
+ "--sample-cap",
+ "2",
+ "--runs-dir",
+ runsDir,
+ ],
+ {},
+ );
+ expect(out.returncode).toBe(0);
+ expect(out.stdout).toContain("longmemeval: recall_all@5");
+ // The sampled text line shows the covered share: the population the
+ // sampler chose from beside the selected count (pr-251 L3). The
+ // whole-dataset line carries neither field.
+ expect(out.stdout).toContain("sample_population 3 sample_selected 2");
+ const runId = /^bench \S+ run (\S+)$/m.exec(out.stdout)?.[1];
+ expect(runId).toBeDefined();
+ const checkpoint = JSON.parse(
+ readFileSync(join(runsDir, runId!, "checkpoint.json"), "utf8"),
+ ) as { sample?: unknown };
+ expect(checkpoint.sample).toEqual({ seed: "seed-1", cap: 2 });
+ }, 60_000);
+});
+
+/**
+ * The help prose's usage block (CodeRabbit, pr-251): it mirrors the
+ * verb's USAGE constant - the usage line plus its 7-space continuation
+ * lines - so a flag the verb accepts is listed there too, and the line
+ * cannot drift back to a subset of the accepted flags.
+ */
+describe("bench help text", () => {
+ test("the usage block lists every flag the verb accepts", () => {
+ const usageBlock = (VERB_HELP["bench"] ?? "")
+ .split("\n")
+ .filter((line) => line.startsWith("usage:") || line.startsWith(" "))
+ .join("\n");
+ for (const flag of [
+ "--fixture",
+ "--suite",
+ "--pin",
+ "--recall-floor",
+ "--sample-seed",
+ "--sample-cap",
+ "--resume",
+ "--runs-dir",
+ "--json",
+ ]) {
+ expect(usageBlock).toContain(flag);
+ }
+ // The sample flags sit in the usage block itself, not only in the
+ // prose below it; the block wraps, so adjacency is checked over the
+ // continuation lines flattened back into one line.
+ const flattened = usageBlock.replaceAll("\n ", " ");
+ expect(flattened).toContain("[--sample-seed <value>] [--sample-cap <n>]");
+ });
+});
diff --git a/tests/cli/install-json-shape.test.ts b/tests/cli/install-json-shape.test.ts
index 883cbfa8..59ad9259 100644
--- a/tests/cli/install-json-shape.test.ts
+++ b/tests/cli/install-json-shape.test.ts
@@ -24,9 +24,9 @@
*/
import { afterEach, beforeEach, describe, expect, test } from "bun:test";
-import { mkdtempSync, rmSync, writeFileSync } from "node:fs";
+import { mkdirSync, mkdtempSync, rmSync, writeFileSync } from "node:fs";
import { tmpdir } from "node:os";
-import { join } from "node:path";
+import { dirname, join } from "node:path";
import { INSTALL_JSON_SCHEMA_VERSION } from "../../src/cli/install/render.ts";
import { runCli as baseRunCli, type RunCliOptions, type RunResult } from "../helpers/run-cli.ts";
@@ -60,6 +60,12 @@ afterEach(() => {
function envBase() {
return {
HOME: home,
+ // The adapter checks XDG_CONFIG_HOME first, so a developer shell or a
+ // CI runner that exports it would otherwise redirect every config
+ // path out of the temp HOME. Pin it inside the sandbox instead of
+ // deleting it: an inherited value could also point the general
+ // config resolution at real user state.
+ XDG_CONFIG_HOME: join(home, ".config"),
OPEN_SECOND_BRAIN_CONFIG: configPath,
VAULT_DIR: vault,
VAULT_AGENT_NAME: "claude-vps",
@@ -178,3 +184,22 @@ describe("every install --json payload names its fields", () => {
CLI_TIMEOUT_MS,
);
});
+
+describe("the opencode V2 config shape in the apply payload", () => {
+ test(
+ "apply to an existing mcp.servers config records the nested owned keys",
+ async () => {
+ const opencodeConfig = join(home, ".config", "opencode", "opencode.json");
+ mkdirSync(dirname(opencodeConfig), { recursive: true });
+ writeFileSync(opencodeConfig, JSON.stringify({ mcp: { servers: {} } }, null, 2) + "\n");
+ const payload = await payloadOf(["install", "--target", "opencode", "--apply", "--json"]);
+ const manifest = payload["manifest"] as Record<string, unknown>;
+ expect(manifest["config_path"]).toBe(opencodeConfig);
+ expect(manifest["owned_keys"]).toEqual([
+ "mcp.servers.open-second-brain",
+ "mcp.servers.open-second-brain-writer",
+ ]);
+ },
+ CLI_TIMEOUT_MS,
+ );
+});
diff --git a/tests/core/bench/longmemeval-sample.test.ts b/tests/core/bench/longmemeval-sample.test.ts
new file mode 100644
index 00000000..94e6b0c3
--- /dev/null
+++ b/tests/core/bench/longmemeval-sample.test.ts
@@ -0,0 +1,283 @@
+/**
+ * Seeded LongMemEval sampling (wiring-shipped-seams wave, t_4501c662):
+ * abstention exclusion before selection, question-type strata with
+ * largest-remainder apportionment, and a determinism contract - the
+ * same seed and cap select the same subset on every call, dataset file
+ * order cannot change it, and no clock or ambient randomness exists.
+ */
+
+import { describe, expect, test } from "bun:test";
+
+import {
+ LONGMEMEVAL_ABSTENTION_TYPE,
+ LongMemEvalSampleError,
+ isLongMemEvalAbstention,
+ sampleLongMemEvalEntries,
+ type LongMemEvalSampleEntry,
+} from "../../../src/core/bench/longmemeval-sample.ts";
+
+/** A minimal entry shaped the way the sampler reads it. */
+function sampleEntry(qId: string, questionType: string): LongMemEvalSampleEntry {
+ return { q_id: qId, question_type: questionType };
+}
+
+/** Three strata of four, so apportionment has remainders to work with. */
+function population(): LongMemEvalSampleEntry[] {
+ const entries: LongMemEvalSampleEntry[] = [];
+ for (const stratum of ["a", "b", "c"]) {
+ for (let i = 1; i <= 4; i += 1) {
+ entries.push(sampleEntry(`${stratum}-${i}`, `type-${stratum}`));
+ }
+ }
+ return entries;
+}
+
+test("the abstention rule keeps both spellings: the explicit type and the official id suffix", () => {
+ expect(isLongMemEvalAbstention(sampleEntry("q1", LONGMEMEVAL_ABSTENTION_TYPE))).toBe(true);
+ expect(isLongMemEvalAbstention(sampleEntry("official_abs", "single-hop"))).toBe(true);
+ expect(isLongMemEvalAbstention(sampleEntry("q1", "single-hop"))).toBe(false);
+ expect(isLongMemEvalAbstention(sampleEntry("absurd", "single-hop"))).toBe(false);
+});
+
+test("abstention entries are excluded before selection and the count flows through", () => {
+ const entries = [
+ sampleEntry("q-keep", "single-hop"),
+ sampleEntry("abs-explicit", "abstention"),
+ sampleEntry("official_abs", "single-hop"),
+ sampleEntry("q-keep-2", "multi-hop"),
+ ];
+ const { entries: selected, receipt } = sampleLongMemEvalEntries(entries, {
+ seed: "seed-1",
+ cap: 10,
+ });
+ expect(selected.map((e) => e.q_id).toSorted()).toEqual(["q-keep", "q-keep-2"]);
+ expect(receipt.abstention_excluded).toBe(2);
+ expect(receipt.population).toBe(2);
+ expect(receipt.selected).toBe(2);
+});
+
+test("strata are the distinct present question_type values, sorted ascending", () => {
+ const entries = [
+ sampleEntry("q1", "temporal-reasoning"),
+ sampleEntry("q2", "single-hop"),
+ sampleEntry("q3", "temporal-reasoning"),
+ ];
+ const { receipt } = sampleLongMemEvalEntries(entries, { seed: "seed-1", cap: 3 });
+ expect(receipt.strata).toEqual([
+ { question_type: "single-hop", population: 1, selected: 1 },
+ { question_type: "temporal-reasoning", population: 2, selected: 2 },
+ ]);
+});
+
+test("the cap is apportioned by largest remainder and its sum is exact", () => {
+ // Populations 1/2/4 over a total of 7 with cap 3: quotas 3/7, 6/7 and
+ // 12/7 leave bases 0/0/1 and 2 surplus seats for the two largest
+ // fractional remainders (beta .857, gamma .714) - alpha's .429 buys
+ // nothing.
+ const entries = [
+ sampleEntry("a-1", "alpha"),
+ sampleEntry("b-1", "beta"),
+ sampleEntry("b-2", "beta"),
+ sampleEntry("c-1", "gamma"),
+ sampleEntry("c-2", "gamma"),
+ sampleEntry("c-3", "gamma"),
+ sampleEntry("c-4", "gamma"),
+ ];
+ const { entries: selected, receipt } = sampleLongMemEvalEntries(entries, {
+ seed: "seed-1",
+ cap: 3,
+ });
+ expect(selected).toHaveLength(3);
+ expect(receipt.selected).toBe(3);
+ expect(receipt.strata).toEqual([
+ { question_type: "alpha", population: 1, selected: 0 },
+ { question_type: "beta", population: 2, selected: 1 },
+ { question_type: "gamma", population: 4, selected: 2 },
+ ]);
+});
+
+test("remainder ties break by stratum name ascending", () => {
+ // Two strata of 2 with cap 1: both quotas are 0.5, so the one surplus
+ // seat goes to the lexicographically first stratum.
+ const entries = [
+ sampleEntry("b-1", "beta"),
+ sampleEntry("b-2", "beta"),
+ sampleEntry("a-1", "alpha"),
+ sampleEntry("a-2", "alpha"),
+ ];
+ const { receipt } = sampleLongMemEvalEntries(entries, { seed: "seed-1", cap: 1 });
+ expect(receipt.strata).toEqual([
+ { question_type: "alpha", population: 2, selected: 1 },
+ { question_type: "beta", population: 2, selected: 0 },
+ ]);
+});
+
+test("mathematically equal remainders tie exactly, so the name tie-break applies", () => {
+ // The reviewer's case (pr-251 L1): total 6, cap 2. The fractional
+ // remainder of pop 4 is 8/6 - 1 and of pop 1 is 2/6 - 0; both are
+ // mathematically 1/3, but as doubles they differ (pop 1 computes
+ // 0.3333333333333333, pop 4 computes 0.33333333333333326), so a float
+ // comparison hands the surplus seat to beta and the documented name
+ // tie-break never applies. The remainders are compared as integers
+ // ((cap*pop) mod total): all three strata tie at 2 and the seat goes
+ // to the lexicographically first stratum, whose quota (4/3) leaves it
+ // one seat short of its population.
+ const entries = [
+ sampleEntry("a-1", "alpha"),
+ sampleEntry("a-2", "alpha"),
+ sampleEntry("a-3", "alpha"),
+ sampleEntry("a-4", "alpha"),
+ sampleEntry("b-1", "beta"),
+ sampleEntry("c-1", "gamma"),
+ ];
+ const { receipt } = sampleLongMemEvalEntries(entries, { seed: "seed-1", cap: 2 });
+ expect(receipt.strata).toEqual([
+ { question_type: "alpha", population: 4, selected: 2 },
+ { question_type: "beta", population: 1, selected: 0 },
+ { question_type: "gamma", population: 1, selected: 0 },
+ ]);
+ expect(receipt.selected).toBe(2);
+});
+
+test("the same seed and cap select the same subset on every call", () => {
+ const entries = population();
+ const first = sampleLongMemEvalEntries(entries, { seed: "run-9", cap: 4 });
+ const second = sampleLongMemEvalEntries(entries, { seed: "run-9", cap: 4 });
+ expect(first.entries.map((e) => e.q_id)).toEqual(second.entries.map((e) => e.q_id));
+ // The module takes no clock and draws no ambient randomness, so the
+ // result is a pure function of (entries, seed, cap) - repeated here
+ // after the first call consumed the PRNG stream.
+ const third = sampleLongMemEvalEntries(entries.toReversed(), { seed: "run-9", cap: 4 });
+ expect(third.entries.map((e) => e.q_id)).toEqual(first.entries.map((e) => e.q_id));
+});
+
+test("a different seed selects a different subset at the same cap", () => {
+ const entries = population();
+ const bySeed = sampleLongMemEvalEntries(entries, { seed: "run-9", cap: 4 });
+ const otherSeed = sampleLongMemEvalEntries(entries, { seed: "run-10", cap: 4 });
+ expect(otherSeed.entries.map((e) => e.q_id)).not.toEqual(bySeed.entries.map((e) => e.q_id));
+});
+
+test("the seed is normalized once, in the sampler: padded input selects the bare subset", () => {
+ // pr-251 L2: the CLI used to trim --sample-seed while the API path
+ // hashed the seed as given, so the same input produced different
+ // subsets depending on the surface. The sampler trims before hashing
+ // - the one normalization point - so padded and bare input select the
+ // identical subset.
+ const entries = population();
+ const bare = sampleLongMemEvalEntries(entries, { seed: "seed-1", cap: 4 });
+ const padded = sampleLongMemEvalEntries(entries, { seed: " seed-1\t", cap: 4 });
+ expect(padded.entries.map((e) => e.q_id)).toEqual(bare.entries.map((e) => e.q_id));
+ expect(padded.receipt).toEqual(bare.receipt);
+});
+
+test("a different cap selects a different subset at the same seed", () => {
+ const entries = population();
+ const byCap = sampleLongMemEvalEntries(entries, { seed: "run-9", cap: 4 });
+ const smallerCap = sampleLongMemEvalEntries(entries, { seed: "run-9", cap: 3 });
+ expect(smallerCap.entries).toHaveLength(3);
+ expect(smallerCap.entries.map((e) => e.q_id)).not.toEqual(byCap.entries.map((e) => e.q_id));
+});
+
+test("dataset file order cannot change the selected subset", () => {
+ const entries = population();
+ const inOrder = sampleLongMemEvalEntries(entries, { seed: "order", cap: 5 });
+ const ids = inOrder.entries.map((e) => e.q_id);
+ expect(sampleLongMemEvalEntries(entries.toReversed(), { seed: "order", cap: 5 }).entries).toEqual(
+ inOrder.entries,
+ );
+ const rotated = [...entries.slice(5), ...entries.slice(0, 5)];
+ expect(
+ sampleLongMemEvalEntries(rotated, { seed: "order", cap: 5 }).entries.map((e) => e.q_id),
+ ).toEqual(ids);
+});
+
+test("a cap at or above the population selects everyone", () => {
+ const entries = [...population(), sampleEntry("abs-1", "abstention")];
+ for (const cap of [12, 50]) {
+ const { entries: selected, receipt } = sampleLongMemEvalEntries(entries, {
+ seed: "seed-1",
+ cap,
+ });
+ expect(selected).toHaveLength(12);
+ expect(receipt.selected).toBe(12);
+ expect(receipt.population).toBe(12);
+ // The clamped cap lands in the receipt too: every stratum reports
+ // exactly its own population - never the raw apportionment of an
+ // unclamped cap, which at cap 50 would report 17 selected in a
+ // stratum of 4 - and the per-stratum selections sum to the
+ // population.
+ expect(receipt.strata).toEqual([
+ { question_type: "type-a", population: 4, selected: 4 },
+ { question_type: "type-b", population: 4, selected: 4 },
+ { question_type: "type-c", population: 4, selected: 4 },
+ ]);
+ expect(receipt.strata.reduce((sum, stratum) => sum + stratum.selected, 0)).toBe(12);
+ }
+});
+
+test("selected entries come back in canonical question-id order", () => {
+ const { entries: selected } = sampleLongMemEvalEntries(population(), {
+ seed: "order-out",
+ cap: 7,
+ });
+ const ids = selected.map((e) => e.q_id);
+ expect(ids).toEqual(ids.toSorted());
+});
+
+test("a population of only abstention entries is a named error", () => {
+ const entries = [sampleEntry("x_abs", "single-hop"), sampleEntry("y", "abstention")];
+ expect(() => sampleLongMemEvalEntries(entries, { seed: "seed-1", cap: 2 })).toThrow(
+ LongMemEvalSampleError,
+ );
+ expect(() => sampleLongMemEvalEntries(entries, { seed: "seed-1", cap: 2 })).toThrow(/abstention/);
+});
+
+test("an empty population is a named error", () => {
+ expect(() => sampleLongMemEvalEntries([], { seed: "seed-1", cap: 2 })).toThrow(
+ LongMemEvalSampleError,
+ );
+});
+
+test("malformed options are refused by name", () => {
+ const entries = population();
+ expect(() => sampleLongMemEvalEntries(entries, { seed: "seed-1", cap: 0 })).toThrow(
+ LongMemEvalSampleError,
+ );
+ expect(() => sampleLongMemEvalEntries(entries, { seed: "seed-1", cap: 1.5 })).toThrow(/cap/);
+ expect(() => sampleLongMemEvalEntries(entries, { seed: "", cap: 2 })).toThrow(/seed/);
+ expect(() => sampleLongMemEvalEntries(entries, { seed: " ", cap: 2 })).toThrow(/seed/);
+});
+
+test("a duplicated question id is a named error, before any order-dependent step", () => {
+ const entries = [...population(), sampleEntry("a-1", "type-a")];
+ expect(() => sampleLongMemEvalEntries(entries, { seed: "seed-1", cap: 4 })).toThrow(
+ LongMemEvalSampleError,
+ );
+ expect(() => sampleLongMemEvalEntries(entries, { seed: "seed-1", cap: 4 })).toThrow(
+ /'a-1' appears twice/,
+ );
+});
+
+test("the sampler is pure: same inputs, same outputs, no input mutation", () => {
+ const entries = population();
+ const snapshot = entries.map((e) => e.q_id);
+ const first = sampleLongMemEvalEntries(entries, { seed: "pure", cap: 6 });
+ const second = sampleLongMemEvalEntries(entries, { seed: "pure", cap: 6 });
+ expect(first.entries.map((e) => e.q_id)).toEqual(second.entries.map((e) => e.q_id));
+ expect(entries.map((e) => e.q_id)).toEqual(snapshot);
+});
+
+describe("receipt fragment", () => {
+ test("per-stratum population and selected counts are carried beside the totals", () => {
+ const { receipt } = sampleLongMemEvalEntries(population(), { seed: "receipt", cap: 5 });
+ expect(receipt.strata).toEqual([
+ { question_type: "type-a", population: 4, selected: 2 },
+ { question_type: "type-b", population: 4, selected: 2 },
+ { question_type: "type-c", population: 4, selected: 1 },
+ ]);
+ expect(receipt.population).toBe(12);
+ expect(receipt.selected).toBe(5);
+ expect(receipt.abstention_excluded).toBe(0);
+ });
+});
diff --git a/tests/core/bench/longmemeval.test.ts b/tests/core/bench/longmemeval.test.ts
index dd1dfcf6..cfd5ba85 100644
--- a/tests/core/bench/longmemeval.test.ts
+++ b/tests/core/bench/longmemeval.test.ts
@@ -23,6 +23,7 @@ import {
parseLongMemEvalDataset,
scoreLongMemEvalRecall,
} from "../../../src/core/bench/longmemeval.ts";
+import { sampleLongMemEvalEntries } from "../../../src/core/bench/longmemeval-sample.ts";
import { benchSearchConfig, runMemoryBench } from "../../../src/core/bench/phases.ts";
import { BENCH_REPORT_SCHEMA, type BenchPinnedKnobs } from "../../../src/core/bench/types.ts";
@@ -508,10 +509,10 @@ describe("scoreLongMemEvalRecall", () => {
});
describe("the longmemeval suite", () => {
- test("is registered with the embeddings capability", () => {
+ test("is registered with the embeddings and sampling capabilities", () => {
const registration = benchSuite("longmemeval");
expect(registration).toBeDefined();
- expect(registration!.capabilities).toEqual({ embeddings: true });
+ expect(registration!.capabilities).toEqual({ embeddings: true, sampling: true });
expect(typeof registration!.loader).toBe("function");
});
@@ -754,3 +755,136 @@ describe("the longmemeval suite", () => {
expect("gold" in first).toBe(false);
}, 20_000);
});
+
+/**
+ * Seeded sampling through the loader (wiring-shipped-seams wave,
+ * t_4501c662): sampling happens PRE-conversion on the parsed entries,
+ * the receipt carries the sample beside the abstention count, and the
+ * no-options path stays byte-identical to the shipped loader.
+ */
+describe("seeded sampling", () => {
+ /**
+ * A synthetic dataset: six questions across six types plus one
+ * abstention, all sharing the minimal valid entry's haystack shape.
+ */
+ function writeSyntheticDataset(): string {
+ const dir = mkdtempSync(join(tmpdir(), "o2b-longmemeval-dataset-"));
+ dirs.push(dir);
+ const path = join(dir, "synthetic.json");
+ const entries = [
+ entry({}),
+ entry({ q_id: "q2", question_type: "multi-hop" }),
+ entry({ q_id: "q3", question_type: "temporal-reasoning" }),
+ entry({ q_id: "q4", question_type: "knowledge-update" }),
+ entry({ q_id: "q5", question_type: "single-session-user" }),
+ entry({ q_id: "q6", question_type: "multi-session" }),
+ entry({ q_id: "abs-1", question_type: "abstention", answer_session_ids: [] }),
+ ];
+ writeFileSync(path, `${JSON.stringify(entries)}\n`, "utf8");
+ return path;
+ }
+
+ test("the no-options loader path returns the shipped conversion", () => {
+ const plain = loadLongMemEvalFixture(SAMPLE);
+ expect(loadLongMemEvalFixture(SAMPLE, {})).toEqual(plain);
+ expect(loadLongMemEvalFixture(SAMPLE, undefined)).toEqual(plain);
+ // The receipt carries no sample fields on the off path.
+ expect(plain.receipt).toEqual({ abstention_excluded: 1 });
+ });
+
+ test("with sample options the sampler runs pre-conversion and the receipt carries the sample", () => {
+ const datasetPath = writeSyntheticDataset();
+ const options = { sample: { seed: "seed-1", cap: 3 } as const };
+ const conversion = loadLongMemEvalFixture(datasetPath, options);
+ // Sampling provably happened BEFORE conversion: the converted
+ // fixture's question count is the sampled count, not the dataset's.
+ const dataset = parseLongMemEvalDataset(JSON.parse(readFileSync(datasetPath, "utf8")));
+ const direct = sampleLongMemEvalEntries(dataset.entries, options.sample);
+ expect(conversion.fixture.questions).toHaveLength(direct.receipt.selected);
+ expect(conversion.fixture.questions.map((q) => q.id)).toEqual(
+ direct.entries.map((e) => e.q_id),
+ );
+ // The receipt mirrors the abstention precedent and adds the sample
+ // beside it. The abstention count is the SAMPLER's - the exclusion
+ // happened before selection, so the conversion's own count is 0.
+ expect(conversion.receipt).toEqual({
+ abstention_excluded: 1,
+ sample_population: direct.receipt.population,
+ sample_selected: direct.receipt.selected,
+ sample_strata: direct.receipt.strata,
+ });
+ expect(conversion.receipt.sample_population).toBe(6);
+ expect(conversion.receipt.sample_selected).toBe(3);
+ // Same options, same subset - the loader adds no nondeterminism.
+ expect(loadLongMemEvalFixture(datasetPath, options).fixture).toEqual(conversion.fixture);
+ });
+
+ test("a sampled run reports the sampled count through the longmemeval family", async () => {
+ const datasetPath = writeSyntheticDataset();
+ const { fixture, receipt } = loadLongMemEvalFixture(datasetPath, {
+ sample: { seed: "seed-1", cap: 3 },
+ });
+ const runsDir = mkdtempSync(join(tmpdir(), "o2b-longmemeval-runs-"));
+ dirs.push(runsDir);
+ const report = await runMemoryBench({
+ fixture,
+ runsDir,
+ suite: "longmemeval",
+ suiteReceipt: receipt,
+ });
+ expect(report.quality.total).toBe(3);
+ // The sampled bookkeeping - selected count, population and the
+ // per-stratum breakdown - rides the named family, so the report
+ // shows what the run's numbers cover. Frozen worked example: six
+ // one-per-type survivors at cap 3 give every stratum quota 0.5, and
+ // the three surplus seats go to the lexicographically first strata.
+ expect(report.longmemeval).toEqual({
+ recall_all_at_5: 1,
+ abstention_excluded: 1,
+ sample_population: 6,
+ sample_selected: 3,
+ sample_strata: [
+ { question_type: "knowledge-update", population: 1, selected: 1 },
+ { question_type: "multi-hop", population: 1, selected: 1 },
+ { question_type: "multi-session", population: 1, selected: 1 },
+ { question_type: "single-hop", population: 1, selected: 0 },
+ { question_type: "single-session-user", population: 1, selected: 0 },
+ { question_type: "temporal-reasoning", population: 1, selected: 0 },
+ ],
+ });
+ // And the family in the persisted report.json carries the same
+ // fields - the receipt is visible where an operator actually reads it.
+ const persisted = JSON.parse(
+ readFileSync(join(runsDir, report.run_id, "report.json"), "utf8"),
+ ) as { longmemeval: Record<string, unknown> };
+ const persistedFamily = persisted.longmemeval!;
+ expect(Object.keys(persistedFamily).toSorted()).toEqual([
+ "abstention_excluded",
+ "recall_all_at_5",
+ "sample_population",
+ "sample_selected",
+ "sample_strata",
+ ]);
+ expect(persistedFamily["sample_population"]).toBe(6);
+ expect(persistedFamily["sample_selected"]).toBe(3);
+ expect(persistedFamily["sample_strata"]).toEqual(report.longmemeval!.sample_strata);
+ }, 20_000);
+
+ test("a whole-dataset run's family carries no sample fields", async () => {
+ const datasetPath = writeSyntheticDataset();
+ const { fixture, receipt } = loadLongMemEvalFixture(datasetPath);
+ const runsDir = mkdtempSync(join(tmpdir(), "o2b-longmemeval-runs-"));
+ dirs.push(runsDir);
+ const report = await runMemoryBench({
+ fixture,
+ runsDir,
+ suite: "longmemeval",
+ suiteReceipt: receipt,
+ });
+ // Spread-omission, not manufactured zeros: the unsampled report's
+ // family names exactly the strict fields and nothing else. The key
+ // set is the pin, not the score.
+ expect(Object.keys(report.longmemeval!)).toEqual(["recall_all_at_5", "abstention_excluded"]);
+ expect(report.longmemeval!.abstention_excluded).toBe(1);
+ }, 20_000);
+});
diff --git a/tests/core/bench/phases.test.ts b/tests/core/bench/phases.test.ts
index ceaf2c59..69ffa4aa 100644
--- a/tests/core/bench/phases.test.ts
+++ b/tests/core/bench/phases.test.ts
@@ -278,6 +278,70 @@ describe("runMemoryBench", () => {
runMemoryBench({ fixture: FIXTURE, runsDir, recallFloor: 1 }),
).resolves.toBeDefined();
}, 60_000);
+
+ test("an invalid sampling request is refused by name before any run state exists", async () => {
+ // The sampling options are part of the run identity, so a malformed
+ // one is refused up front rather than after a full run pays for a
+ // configuration that never existed.
+ for (const sample of [
+ { seed: "seed-1", cap: 0 },
+ { seed: "seed-1", cap: -2 },
+ { seed: "seed-1", cap: 1.5 },
+ { seed: "", cap: 2 },
+ { seed: " ", cap: 2 },
+ ]) {
+ await expect(runMemoryBench({ fixture: FIXTURE, runsDir, sample })).rejects.toThrow(
+ /bench run refused/,
+ );
+ }
+ expect(readdirSync(runsDir)).toHaveLength(0);
+ }, 30_000);
+
+ test("sampling options fold into the run identity end to end", async () => {
+ // Cap 5 sits above the five-question fixture's population, so both
+ // runs would materialize the identical fixture - the OPTIONS alone
+ // must split the run ids.
+ const first = await runMemoryBench({
+ fixture: FIXTURE,
+ runsDir,
+ sample: { seed: "seed-1", cap: 5 },
+ });
+ const second = await runMemoryBench({
+ fixture: FIXTURE,
+ runsDir,
+ sample: { seed: "seed-2", cap: 5 },
+ });
+ expect(first.run_id).not.toBe(second.run_id);
+ // Resuming with the same sampling options reuses the run.
+ const resumed = await runMemoryBench({
+ fixture: FIXTURE,
+ runsDir,
+ resume: first.run_id,
+ sample: { seed: "seed-1", cap: 5 },
+ });
+ expect(resumed.run_id).toBe(first.run_id);
+ expect(readdirSync(runsDir)).toHaveLength(2);
+ }, 30_000);
+
+ test("resume with changed sampling options fails fast on the identity guard", async () => {
+ const first = await runMemoryBench({
+ fixture: FIXTURE,
+ runsDir,
+ sample: { seed: "seed-1", cap: 5 },
+ });
+ await expect(
+ runMemoryBench({
+ fixture: FIXTURE,
+ runsDir,
+ resume: first.run_id,
+ sample: { seed: "seed-1", cap: 3 },
+ }),
+ ).rejects.toThrow(/run identity mismatch/);
+ // And so does resuming a sampled run with no sampling options.
+ await expect(
+ runMemoryBench({ fixture: FIXTURE, runsDir, resume: first.run_id }),
+ ).rejects.toThrow(/run identity mismatch/);
+ }, 30_000);
});
describe("the embeddings capability path", () => {
diff --git a/tests/core/bench/run-store.test.ts b/tests/core/bench/run-store.test.ts
index d921c460..857061a0 100644
--- a/tests/core/bench/run-store.test.ts
+++ b/tests/core/bench/run-store.test.ts
@@ -12,12 +12,13 @@ import { join } from "node:path";
import { parseBenchFixture } from "../../../src/core/bench/fixture.ts";
import {
+ benchRunIdentityHash,
benchVaultDir,
completeBenchPhase,
createBenchRun,
loadBenchRun,
} from "../../../src/core/bench/run-store.ts";
-import type { BenchPinnedKnobs } from "../../../src/core/bench/types.ts";
+import { DEFAULT_BENCH_KNOB_PIN, type BenchPinnedKnobs } from "../../../src/core/bench/types.ts";
let runsDir: string;
@@ -161,3 +162,90 @@ describe("bench run store", () => {
);
});
});
+
+/**
+ * The sampling fold in the run identity (wiring-shipped-seams wave,
+ * t_4501c662): the canonical record spreads `sample` in ONLY when
+ * sampling is set - so a no-sampling run's identity equals the shipped
+ * one byte for byte - and any sampling-option change is a different run
+ * that the resume guard refuses to mix.
+ */
+describe("the sampling fold in the run identity", () => {
+ /** The identity hash values computed before the fold existed. */
+ const FROZEN_NO_SAMPLE_IDENTITY = "d3fbe6ad99439a0e";
+ const FROZEN_FLOOR_IDENTITY = "7b9b430af41eb4a1";
+
+ test("a no-sampling run's identity hash is byte-stable with the shipped fold", () => {
+ expect(benchRunIdentityHash(FIXTURE, DEFAULT_BENCH_KNOB_PIN)).toBe(FROZEN_NO_SAMPLE_IDENTITY);
+ expect(benchRunIdentityHash(FIXTURE, DEFAULT_BENCH_KNOB_PIN, 0.4)).toBe(FROZEN_FLOOR_IDENTITY);
+ });
+
+ test("a sampled run's identity hash differs, and differs by seed and by cap", () => {
+ const base = { seed: "seed-1", cap: 1 };
+ expect(benchRunIdentityHash(FIXTURE, DEFAULT_BENCH_KNOB_PIN, undefined, base)).not.toBe(
+ FROZEN_NO_SAMPLE_IDENTITY,
+ );
+ expect(
+ benchRunIdentityHash(FIXTURE, DEFAULT_BENCH_KNOB_PIN, undefined, {
+ ...base,
+ seed: "seed-2",
+ }),
+ ).not.toBe(benchRunIdentityHash(FIXTURE, DEFAULT_BENCH_KNOB_PIN, undefined, base));
+ expect(
+ benchRunIdentityHash(FIXTURE, DEFAULT_BENCH_KNOB_PIN, undefined, { ...base, cap: 2 }),
+ ).not.toBe(benchRunIdentityHash(FIXTURE, DEFAULT_BENCH_KNOB_PIN, undefined, base));
+ });
+
+ test("two runs differing only in the seed, or only in the cap, get different run ids", () => {
+ const now = new Date("2026-06-03T12:00:00Z");
+ const base = { seed: "seed-1", cap: 1 };
+ // Both caps sit at the one-question fixture's population, so the
+ // materialized fixture is identical - the OPTIONS alone must split
+ // the run ids.
+ const a = createBenchRun(runsDir, FIXTURE, { now, sample: base });
+ const b = createBenchRun(runsDir, FIXTURE, { now, sample: { ...base, seed: "seed-2" } });
+ const c = createBenchRun(runsDir, FIXTURE, { now, sample: { ...base, cap: 2 } });
+ expect(a.runId).not.toBe(b.runId);
+ expect(a.runId).not.toBe(c.runId);
+ // Same options, same id.
+ expect(createBenchRun(runsDir, FIXTURE, { now, sample: base }).runId).toBe(a.runId);
+ });
+
+ test("the checkpoint carries the sampling request", () => {
+ const run = createBenchRun(runsDir, FIXTURE, {
+ now: new Date("2026-06-03T12:00:00Z"),
+ sample: { seed: "seed-1", cap: 3 },
+ });
+ expect(run.checkpoint.sample).toEqual({ seed: "seed-1", cap: 3 });
+ const reloaded = loadBenchRun(runsDir, run.runId);
+ expect(reloaded.checkpoint.sample).toEqual({ seed: "seed-1", cap: 3 });
+ });
+
+ test("a resume whose sampling options changed fails the identity guard", () => {
+ const run = createBenchRun(runsDir, FIXTURE, {
+ now: new Date("2026-06-03T12:00:00Z"),
+ sample: { seed: "seed-1", cap: 2 },
+ });
+ const same = loadBenchRun(runsDir, run.runId, {
+ expectFixture: FIXTURE,
+ sample: { seed: "seed-1", cap: 2 },
+ });
+ expect(same.runId).toBe(run.runId);
+ expect(() =>
+ loadBenchRun(runsDir, run.runId, {
+ expectFixture: FIXTURE,
+ sample: { seed: "seed-1", cap: 3 },
+ }),
+ ).toThrow(/run identity mismatch/);
+ expect(() =>
+ loadBenchRun(runsDir, run.runId, {
+ expectFixture: FIXTURE,
+ sample: { seed: "seed-2", cap: 2 },
+ }),
+ ).toThrow(/run identity mismatch/);
+ // A no-sampling resume against a sampled run mismatches too.
+ expect(() => loadBenchRun(runsDir, run.runId, { expectFixture: FIXTURE })).toThrow(
+ /run identity mismatch/,
+ );
+ });
+});
diff --git a/tests/core/brain/skill-usage.test.ts b/tests/core/brain/skill-usage.test.ts
index eee5b743..070564d4 100644
--- a/tests/core/brain/skill-usage.test.ts
+++ b/tests/core/brain/skill-usage.test.ts
@@ -3,8 +3,16 @@ import { mkdtempSync, rmSync } from "node:fs";
import { tmpdir } from "node:os";
import { join } from "node:path";
-import { appendContinuityRecord } from "../../../src/core/brain/continuity/store.ts";
-import { deriveSkillUsage } from "../../../src/core/brain/skill-usage.ts";
+import {
+ appendContinuityRecord,
+ appendContinuityRecords,
+} from "../../../src/core/brain/continuity/store.ts";
+import {
+ deriveSkillUsage,
+ skillUsageRankingWeights,
+ skillUsageWeights,
+ type SkillUsage,
+} from "../../../src/core/brain/skill-usage.ts";
let vault: string;
@@ -54,3 +62,189 @@ test("distinct invocations in the same second are counted separately", () => {
expect(usage).toHaveLength(1);
expect(usage[0]!.invocationCount).toBe(2);
});
+
+// --- skillUsageWeights (t_5d1ec8a8): the offer-join side of the usage map ---
+
+function usageRow(skill: string, weight: number): SkillUsage {
+ return {
+ skill,
+ invocationCount: 1,
+ offerAttributedCount: 0,
+ lastInvokedAtMs: null,
+ weight,
+ };
+}
+
+test("usage keys that are known names join exactly", () => {
+ const map = skillUsageWeights(
+ [usageRow("codegraph-partner", 0.75)],
+ new Set(["codegraph-partner", "schema-author"]),
+ );
+ expect(map.get("codegraph-partner")).toBe(0.75);
+ expect(map.has("schema-author")).toBe(false);
+});
+
+test("a plugin-qualified usage key joins through its suffix after the colon", () => {
+ const map = skillUsageWeights(
+ [usageRow("open-second-brain:codegraph-partner", 0.5)],
+ new Set(["codegraph-partner"]),
+ );
+ expect(map.get("codegraph-partner")).toBe(0.5);
+});
+
+test("the longest matching suffix wins when several colons exist", () => {
+ const map = skillUsageWeights(
+ [usageRow("plugin:b:codegraph-partner", 0.25)],
+ new Set(["b:codegraph-partner", "codegraph-partner"]),
+ );
+ expect(map.get("b:codegraph-partner")).toBe(0.25);
+ expect(map.has("codegraph-partner")).toBe(false);
+});
+
+test("usage keys matching nothing are dropped", () => {
+ const map = skillUsageWeights(
+ [usageRow("retired-skill", 1), usageRow("never-installed:ghost", 1)],
+ new Set(["codegraph-partner"]),
+ );
+ expect(map.size).toBe(0);
+});
+
+test("map values are the decay weights unchanged", () => {
+ const weights = [1, 0.02, 0.5];
+ const rows = weights.map((w, i) => usageRow(`skill-${i}`, w));
+ const map = skillUsageWeights(rows, new Set(rows.map((r) => r.skill)));
+ expect([...map.values()].toSorted((a, b) => a - b)).toEqual(weights.toSorted((a, b) => a - b));
+});
+
+test("an exact name beats a hotter suffix join when both spellings exist", () => {
+ const map = skillUsageWeights(
+ [usageRow("open-second-brain:codegraph-partner", 0.9), usageRow("codegraph-partner", 0.1)],
+ new Set(["codegraph-partner"]),
+ );
+ expect(map.get("codegraph-partner")).toBe(0.1);
+});
+
+test("an empty usage list yields an empty map", () => {
+ expect(skillUsageWeights([], new Set(["codegraph-partner"])).size).toBe(0);
+});
+
+test("the join is deterministic across repeated calls", () => {
+ const rows = [
+ usageRow("open-second-brain:codegraph-partner", 0.5),
+ usageRow("schema-author", 0.25),
+ usageRow("ghost", 1),
+ ];
+ const names = new Set(["codegraph-partner", "schema-author"]);
+ const a = skillUsageWeights(rows, names);
+ const b = skillUsageWeights(rows, names);
+ expect([...a.entries()]).toEqual([...b.entries()]);
+});
+
+// --- skillUsageRankingWeights (M5): a ranking weight that does not saturate ---
+//
+// The decay weight `SkillUsage.weight` carries is capped at 1, so among
+// RECENTLY used skills frequency is invisible: a skill invoked 300 times
+// this week and one invoked once yesterday both clamp to 1 and the name
+// tie-break decides. The ranking builder normalises the count against the
+// largest joined count so frequency separates them again.
+
+const RANKING_NOW = Date.parse("2026-06-04T00:00:00Z");
+
+/** `count` invocations of one skill, hourly, ending at `latestAt`. */
+function invokeMany(skill: string, count: number, latestAt: string): void {
+ const latest = Date.parse(latestAt);
+ appendContinuityRecords(
+ vault,
+ Array.from({ length: count }, (_, i) => ({
+ kind: "skill_invoked" as const,
+ createdAt: new Date(latest - i * 3_600_000).toISOString(),
+ sourceRefs: [{ id: `sess:${skill}:${i}` }],
+ payload: { skill, agent: "claude", tool: "get_skill" },
+ })),
+ );
+}
+
+function rankingRow(skill: string, count: number, lastInvokedAtMs: number | null): SkillUsage {
+ return {
+ skill,
+ invocationCount: count,
+ offerAttributedCount: 0,
+ lastInvokedAtMs,
+ weight: 1,
+ };
+}
+
+test("the plain decay weights tie a 300-fold and a once-invoked skill, both recent (the saturation defect)", () => {
+ invokeMany("release-heavy", 300, "2026-06-03T23:00:00Z");
+ invokeMany("release-once", 1, "2026-06-03T20:00:00Z");
+ const usage = deriveSkillUsage(vault, { nowMs: RANKING_NOW });
+ const weights = skillUsageWeights(usage, new Set(["release-heavy", "release-once"]));
+ // Both clamp to the cap: this tie is exactly what the ranking builder exists
+ // to break, pinned so a future change to the decay contract shows up here.
+ expect(weights.get("release-heavy")).toBe(1);
+ expect(weights.get("release-once")).toBe(1);
+});
+
+test("the ranking weight ranks the frequently invoked skill first, both recent", () => {
+ invokeMany("release-heavy", 300, "2026-06-03T23:00:00Z");
+ invokeMany("release-once", 1, "2026-06-03T20:00:00Z");
+ const usage = deriveSkillUsage(vault, { nowMs: RANKING_NOW });
+ const map = skillUsageRankingWeights(usage, new Set(["release-heavy", "release-once"]), {
+ nowMs: RANKING_NOW,
+ });
+ expect(map.get("release-heavy")).toBeGreaterThan(map.get("release-once")!);
+ // Bounds: weights stay in (0, 1].
+ expect(map.get("release-once")).toBeGreaterThan(0);
+ expect(map.get("release-heavy")).toBeLessThanOrEqual(1);
+});
+
+test("maxCount is taken over the joined rows, so an unjoined heavy row does not shrink the rest", () => {
+ const rows = [
+ rankingRow("vendor:ghost-heavy", 1000, RANKING_NOW - 60_000), // joins nothing
+ rankingRow("recent-a", 1, null),
+ rankingRow("recent-b", 1, null),
+ ];
+ const map = skillUsageRankingWeights(rows, new Set(["recent-a", "recent-b"]), {
+ nowMs: RANKING_NOW,
+ });
+ // Every joined count is 1, so the ratio is 1 everywhere: undated rows carry
+ // full recency (the same convention the decay curve applies) and are not
+ // scaled down by the 1000-fold row that matched no known name.
+ expect(map.get("recent-a")).toBe(1);
+ expect(map.get("recent-b")).toBe(1);
+});
+
+test("a plugin-qualified frequent invocation outranks a once-used exact join", () => {
+ const rows = [
+ rankingRow("vendor:release-heavy", 300, RANKING_NOW - 60_000),
+ rankingRow("release-once", 1, RANKING_NOW - 60_000),
+ ];
+ const map = skillUsageRankingWeights(rows, new Set(["release-heavy", "release-once"]), {
+ nowMs: RANKING_NOW,
+ });
+ expect(map.get("release-heavy")).toBeGreaterThan(map.get("release-once")!);
+});
+
+test("an ancient invocation floors at the same minimum as the decay curve", () => {
+ const rows = [rankingRow("legacy", 1, Date.parse("1990-01-01T00:00:00Z"))];
+ const map = skillUsageRankingWeights(rows, new Set(["legacy"]), { nowMs: RANKING_NOW });
+ expect(map.get("legacy")).toBe(0.02);
+});
+
+test("an empty usage list yields an empty ranking map", () => {
+ expect(skillUsageRankingWeights([], new Set(["codegraph-partner"])).size).toBe(0);
+ expect(
+ skillUsageRankingWeights([usageRow("ghost", 1)], new Set(["codegraph-partner"])).size,
+ ).toBe(0);
+});
+
+test("the ranking join is deterministic across repeated calls", () => {
+ const rows = [
+ rankingRow("vendor:release-heavy", 300, RANKING_NOW - 60_000),
+ rankingRow("release-once", 1, RANKING_NOW - 3_600_000),
+ ];
+ const names = new Set(["release-heavy", "release-once"]);
+ const a = skillUsageRankingWeights(rows, names, { nowMs: RANKING_NOW });
+ const b = skillUsageRankingWeights(rows, names, { nowMs: RANKING_NOW });
+ expect([...a.entries()]).toEqual([...b.entries()]);
+});
diff --git a/tests/core/doctor-readiness.test.ts b/tests/core/doctor-readiness.test.ts
index 32d0ddf1..e5996fa5 100644
--- a/tests/core/doctor-readiness.test.ts
+++ b/tests/core/doctor-readiness.test.ts
@@ -540,6 +540,155 @@ describe("probeRegisteredCommands", () => {
expect(v.detail).toContain(launcher);
});
+ test("the opencode V2 mcp.servers shape is extracted and probed like a top-level entry", async () => {
+ writeConfig("");
+ const launcher = join(tmp, "bin", "o2b");
+ mkdirSync(dirname(launcher), { recursive: true });
+ writeFileSync(launcher, "");
+ const config = join(home, ".config", "opencode", "opencode.json");
+ mkdirSync(dirname(config), { recursive: true });
+ writeFileSync(
+ config,
+ JSON.stringify({
+ theme: "dark",
+ mcp: {
+ servers: {
+ "open-second-brain": {
+ type: "local",
+ command: [launcher, "mcp", "--vault", tmp],
+ enabled: true,
+ },
+ },
+ },
+ }),
+ );
+ writeManifestEntries({ opencode: manifestEntry("opencode", config) });
+ const v = await probeRegisteredCommands(installedRuntimeOpts());
+ expect(v.status).toBe(READINESS_STATUS.pass);
+ expect(v.detail).toContain("opencode");
+ expect(v.detail).toContain(launcher);
+ });
+
+ test("a V2 config with shadowed legacy copies probes the native entries only", async () => {
+ writeConfig("");
+ const launcher = join(tmp, "bin", "o2b");
+ mkdirSync(dirname(launcher), { recursive: true });
+ writeFileSync(launcher, "");
+ const config = join(home, ".config", "opencode", "opencode.json");
+ mkdirSync(dirname(config), { recursive: true });
+ writeFileSync(
+ config,
+ JSON.stringify({
+ mcp: {
+ // A stale legacy copy of the same entry, beside the native
+ // block: scanning both keys probed the same name twice and
+ // reported the stale command as broken.
+ "open-second-brain": {
+ type: "local",
+ command: [join(tmp, "bin", "gone-o2b"), "mcp"],
+ },
+ servers: {
+ "open-second-brain": {
+ type: "local",
+ command: [launcher, "mcp", "--vault", tmp],
+ enabled: true,
+ },
+ "open-second-brain-writer": {
+ type: "local",
+ command: [launcher, "mcp", "--writer-only", "--vault", tmp],
+ enabled: true,
+ },
+ },
+ },
+ }),
+ );
+ writeManifestEntries({ opencode: manifestEntry("opencode", config) });
+ const v = await probeRegisteredCommands(installedRuntimeOpts());
+ expect(v.status).toBe(READINESS_STATUS.pass);
+ expect(v.detail).toContain(launcher);
+ expect(v.detail).not.toContain("gone-o2b");
+ });
+
+ test("a legacy user server named `servers` keeps the top-level shape and probes as installed", async () => {
+ writeConfig("");
+ const launcher = join(tmp, "bin", "o2b");
+ mkdirSync(dirname(launcher), { recursive: true });
+ writeFileSync(launcher, "");
+ const config = join(home, ".config", "opencode", "opencode.json");
+ mkdirSync(dirname(config), { recursive: true });
+ writeFileSync(
+ config,
+ JSON.stringify({
+ mcp: {
+ "open-second-brain": {
+ type: "local",
+ command: [launcher, "mcp", "--vault", tmp],
+ enabled: true,
+ },
+ "open-second-brain-writer": {
+ type: "local",
+ command: [launcher, "mcp", "--writer-only", "--vault", tmp],
+ enabled: true,
+ },
+ // A legacy user's OWN server that happens to be named `servers`:
+ // type/command sit directly on the block, so the adapter's shape
+ // predicate resolves the file as the V1 top-level shape, not the
+ // native V2 map. The doctor must read the same shape and scan
+ // the top-level keys, or it grades this healthy install as
+ // nothing-to-probe.
+ servers: { type: "local", command: ["uvx", "some-user-server"] },
+ },
+ }),
+ );
+ writeManifestEntries({ opencode: manifestEntry("opencode", config) });
+ const v = await probeRegisteredCommands(installedRuntimeOpts());
+ expect(v.status).toBe(READINESS_STATUS.pass);
+ expect(v.detail).toContain(launcher);
+ });
+
+ test("an opencode.jsonc config with comments is extracted and probed", async () => {
+ writeConfig("");
+ const launcher = join(tmp, "bin", "o2b");
+ mkdirSync(dirname(launcher), { recursive: true });
+ writeFileSync(launcher, "");
+ const config = join(home, ".config", "opencode", "opencode.jsonc");
+ mkdirSync(dirname(config), { recursive: true });
+ writeFileSync(
+ config,
+ `// opencode configuration - operator notes survive\n` +
+ JSON.stringify(
+ {
+ theme: "dark",
+ mcp: {
+ servers: {
+ "open-second-brain": { type: "local", command: [launcher, "mcp"], enabled: true },
+ },
+ },
+ },
+ null,
+ 2,
+ ) +
+ "\n",
+ );
+ writeManifestEntries({ opencode: manifestEntry("opencode", config) });
+ const v = await probeRegisteredCommands(installedRuntimeOpts());
+ expect(v.status).toBe(READINESS_STATUS.pass);
+ expect(v.detail).toContain("opencode");
+ expect(v.detail).toContain(launcher);
+ });
+
+ test("a JSON config with neither registration shape is still skipped with the current wording", async () => {
+ writeConfig("");
+ const config = join(home, ".config", "opencode", "opencode.json");
+ mkdirSync(dirname(config), { recursive: true });
+ writeFileSync(config, JSON.stringify({ theme: "dark" }));
+ writeManifestEntries({ opencode: manifestEntry("opencode", config) });
+ const v = await probeRegisteredCommands(installedRuntimeOpts());
+ expect(v.status).toBe(READINESS_STATUS.skipped);
+ expect(v.detail).toContain("no Open Second Brain command entry found");
+ expect(v.detail).toContain(config);
+ });
+
test("the grok/codex TOML shape is extracted and a missing runner script fails", async () => {
writeConfig("");
const bun = join(tmp, "bin", "bun");
diff --git a/tests/core/install/adapters/opencode.test.ts b/tests/core/install/adapters/opencode.test.ts
index 49aa52bb..fde2f152 100644
--- a/tests/core/install/adapters/opencode.test.ts
+++ b/tests/core/install/adapters/opencode.test.ts
@@ -5,13 +5,23 @@
* `${XDG_CONFIG_HOME:-~/.config}/opencode/opencode.json`, `mcp` key,
* entries shaped `{type: "local", command: [bin, ...args],
* environment?, enabled: true}` (verified against opencode.ai/docs
- * 2026-06-10). Earlier Open Second Brain releases wrote
- * `~/.config/opencode/mcp.json` with an `mcpServers` key - a file
+ * 2026-06-10). At the native V2 `mcp.servers` shape the entry instead
+ * carries `disabled: false` - the V2 field list replaces `enabled` with
+ * `disabled` - and never `enabled`. Earlier Open Second Brain releases
+ * wrote `~/.config/opencode/mcp.json` with an `mcpServers` key - a file
* opencode never reads; apply migrates our keys out of it.
*/
import { describe, expect, test, beforeEach, afterEach } from "bun:test";
-import { mkdtempSync, rmSync, readFileSync, writeFileSync, mkdirSync, existsSync } from "node:fs";
+import {
+ mkdtempSync,
+ rmSync,
+ readFileSync,
+ writeFileSync,
+ mkdirSync,
+ existsSync,
+ utimesSync,
+} from "node:fs";
import { tmpdir } from "node:os";
import { join, dirname } from "node:path";
import { Writable } from "node:stream";
@@ -24,6 +34,8 @@ import {
launcherCommand,
} from "../../../../src/core/install/payload.ts";
import { readManifest } from "../../../../src/core/install/manifest.ts";
+import { InstallError } from "../../../../src/core/install/types.ts";
+import { JsoncEditError, parseJsoncObject } from "../../../../src/core/install/jsonc.ts";
let vault: string;
let home: string;
@@ -82,6 +94,23 @@ function writeJson(path: string, value: unknown) {
writeFileSync(path, JSON.stringify(value, null, 2) + "\n");
}
+function isRecord(value: unknown): value is Record<string, unknown> {
+ return value !== null && typeof value === "object" && !Array.isArray(value);
+}
+
+/**
+ * The `key` member of `value` as a record, or a named failure naming
+ * both - the narrow a `parseJsoncObject` result needs before its JSONC
+ * members (typed `unknown`) can be asserted on.
+ */
+function recordAt(value: unknown, key: string): Record<string, unknown> {
+ const member = isRecord(value) ? value[key] : undefined;
+ if (!isRecord(member)) {
+ throw new Error(`expected "${key}" to be a JSON object, received ${JSON.stringify(member)}`);
+ }
+ return member;
+}
+
describe("opencode adapter - config path", () => {
test("default path is ~/.config/opencode/opencode.json", () => {
const r = opencodeAdapter.detect(env());
@@ -328,3 +357,417 @@ describe("opencode adapter - plan completeness", () => {
expect(withLegacy.steps.some((s) => s.path === legacyPath())).toBe(true);
});
});
+
+function jsoncConfigPath() {
+ return join(home, ".config", "opencode", "opencode.jsonc");
+}
+
+/** A JSONC V2 fixture: header comment, inline comment, trailing comma. */
+function writeJsoncV2Fixture(): string {
+ const text = `// opencode configuration - operator notes survive
+{
+ "theme": "dark", // inline note
+ "mcp": {
+ "servers": {
+ "other": { "type": "remote", "url": "https://x" },
+ },
+ },
+}
+`;
+ mkdirSync(dirname(jsoncConfigPath()), { recursive: true });
+ writeFileSync(jsoncConfigPath(), text);
+ return text;
+}
+
+describe("opencode adapter - V2 mcp.servers shape", () => {
+ test("a config carrying an mcp.servers object applies to mcp.servers and records nested owned_keys", () => {
+ writeJson(configPath(), { mcp: { servers: { other: { type: "remote", url: "https://x" } } } });
+ opencodeAdapter.apply(opencodeAdapter.plan(payload(), env()), payload(), env(), applyOpts());
+ const parsed = JSON.parse(readFileSync(configPath(), "utf8"));
+ expect(parsed.mcp.servers["open-second-brain"].type).toBe("local");
+ expect(parsed.mcp.servers["open-second-brain"].environment.VAULT_AGENT_NAME).toBe(
+ "opencode-dev-agent",
+ );
+ // The V2 field list replaces `enabled` with `disabled`: the native
+ // entry carries `disabled: false` and never an `enabled` field.
+ expect(parsed.mcp.servers["open-second-brain"].disabled).toBe(false);
+ expect(parsed.mcp.servers["open-second-brain"].enabled).toBeUndefined();
+ expect(parsed.mcp.servers["open-second-brain-writer"].disabled).toBe(false);
+ expect(parsed.mcp.servers["open-second-brain-writer"].enabled).toBeUndefined();
+ expect(parsed.mcp.servers.other).toEqual({ type: "remote", url: "https://x" });
+ // No shadowing copy under the legacy top-level key.
+ expect(parsed.mcp["open-second-brain"]).toBeUndefined();
+ expect(readManifest(vault).installs["opencode"]?.owned_keys).toEqual([
+ "mcp.servers.open-second-brain",
+ "mcp.servers.open-second-brain-writer",
+ ]);
+ });
+
+ test("a V1 config whose user server is named servers keeps the legacy shape", () => {
+ // `mcp.servers` holding a server ENTRY (the type/command fields on
+ // the block itself) is a user's server, not the native map of them.
+ writeJson(configPath(), {
+ mcp: { servers: { type: "local", command: ["other-agent", "mcp"], enabled: true } },
+ });
+ opencodeAdapter.apply(opencodeAdapter.plan(payload(), env()), payload(), env(), applyOpts());
+ const parsed = JSON.parse(readFileSync(configPath(), "utf8"));
+ // The user's entry is untouched and ours land at the top level.
+ expect(parsed.mcp.servers.type).toBe("local");
+ expect(parsed.mcp.servers["open-second-brain"]).toBeUndefined();
+ expect(parsed.mcp["open-second-brain"].type).toBe("local");
+ expect(parsed.mcp["open-second-brain"].enabled).toBe(true);
+ expect(readManifest(vault).installs["opencode"]?.owned_keys).toEqual([
+ "mcp.open-second-brain",
+ "mcp.open-second-brain-writer",
+ ]);
+ });
+
+ test("verify reports shadowed legacy copies in a V2 file as drift", () => {
+ writeJson(configPath(), { mcp: { servers: {} } });
+ opencodeAdapter.apply(opencodeAdapter.plan(payload(), env()), payload(), env(), applyOpts());
+ expect(opencodeAdapter.verify(env()).status).toBe("ok");
+ // A stale legacy copy of ours reappears beside the native entries
+ // (an old sync tool, say): apply would remove it as non-canonical,
+ // so verify must not call the same state ok.
+ const parsed = JSON.parse(readFileSync(configPath(), "utf8"));
+ parsed.mcp["open-second-brain"] = { type: "local", command: ["o2b", "mcp"], enabled: true };
+ writeFileSync(configPath(), JSON.stringify(parsed, null, 2) + "\n");
+ const v = opencodeAdapter.verify(env());
+ expect(v.status).toBe("drift");
+ expect(v.details.join(" ")).toContain("legacy");
+ expect(v.details.join(" ")).toContain("open-second-brain");
+ });
+
+ test("detect reports a V2 file whose only copies are shadowed legacy ones as drift", () => {
+ // A V1 install first, then the host's own upgrade adds a native
+ // mcp.servers block: our keys are now registered at a site the
+ // resolved shape does not read. That is an owned install at the
+ // wrong place, not an absent one - verify calls the same state
+ // drift, and a not-installed verdict here would make `o2b update`,
+ // which skips only not-installed targets, skip the repair.
+ writeJson(configPath(), { mcp: {} });
+ opencodeAdapter.apply(opencodeAdapter.plan(payload(), env()), payload(), env(), applyOpts());
+ const parsed = JSON.parse(readFileSync(configPath(), "utf8"));
+ parsed.mcp.servers = { other: { type: "remote", url: "https://x" } };
+ writeFileSync(configPath(), JSON.stringify(parsed, null, 2) + "\n");
+ const d = opencodeAdapter.detect(env());
+ expect(d.status).toBe("drift");
+ expect(d.notes.join(" ")).toContain("mcp");
+ expect(d.notes.join(" ")).toContain("mcp.servers");
+ // verify agrees the same file is drifted.
+ expect(opencodeAdapter.verify(env()).status).toBe("drift");
+ // `o2b update` no longer skips the target (drift, not
+ // not-installed): the repair is the documented forced re-apply, the
+ // guard naming the hand-edit first.
+ let thrown: unknown;
+ try {
+ opencodeAdapter.apply(opencodeAdapter.plan(payload(), env()), payload(), env(), applyOpts());
+ } catch (e) {
+ thrown = e;
+ }
+ expect(thrown).toBeInstanceOf(InstallError);
+ expect((thrown as InstallError).kind).toBe("user-modified-block");
+ opencodeAdapter.apply(opencodeAdapter.plan(payload(), env()), payload(), env(), {
+ ...applyOpts(),
+ force: true,
+ });
+ expect(opencodeAdapter.detect(env()).status).toBe("installed");
+ });
+
+ test("a fresh V2 install verifies clean against itself and detects as installed", () => {
+ writeJson(configPath(), { mcp: { servers: {} } });
+ opencodeAdapter.apply(opencodeAdapter.plan(payload(), env()), payload(), env(), applyOpts());
+ expect(opencodeAdapter.verify(env()).status).toBe("ok");
+ expect(opencodeAdapter.detect(env()).status).toBe("installed");
+ expect(opencodeAdapter.detect(env()).notes.join(" ")).toContain("mcp.servers");
+ });
+
+ test("V2 re-apply is idempotent and executes no steps", () => {
+ writeJson(configPath(), { mcp: { servers: {} } });
+ opencodeAdapter.apply(opencodeAdapter.plan(payload(), env()), payload(), env(), applyOpts());
+ const before = readFileSync(configPath(), "utf8");
+ const second = opencodeAdapter.apply(
+ opencodeAdapter.plan(payload(), env()),
+ payload(),
+ env(),
+ applyOpts(),
+ );
+ expect(second.steps_executed).toBe(0);
+ expect(readFileSync(configPath(), "utf8")).toBe(before);
+ });
+
+ test("V2 uninstall removes exactly the nested keys and keeps user keys", () => {
+ writeJson(configPath(), { mcp: { servers: { other: { type: "remote", url: "https://x" } } } });
+ opencodeAdapter.apply(opencodeAdapter.plan(payload(), env()), payload(), env(), applyOpts());
+ const r = opencodeAdapter.uninstall(env(), applyOpts());
+ const parsed = JSON.parse(readFileSync(configPath(), "utf8"));
+ expect(parsed.mcp.servers["open-second-brain"]).toBeUndefined();
+ expect(parsed.mcp.servers["open-second-brain-writer"]).toBeUndefined();
+ expect(parsed.mcp.servers.other).toEqual({ type: "remote", url: "https://x" });
+ expect(r.removed_keys).toEqual([
+ "mcp.servers.open-second-brain",
+ "mcp.servers.open-second-brain-writer",
+ ]);
+ expect(readManifest(vault).installs["opencode"]).toBeUndefined();
+ });
+
+ test("a V1-shaped config is byte-identical through apply: json-merge serialization, top-level mcp (off proof)", () => {
+ writeJson(configPath(), {
+ $schema: "https://opencode.ai/config.json",
+ mcp: { other: { type: "remote", url: "https://x" } },
+ });
+ const before = readFileSync(configPath(), "utf8");
+ opencodeAdapter.apply(opencodeAdapter.plan(payload(), env()), payload(), env(), applyOpts());
+ const after = readFileSync(configPath(), "utf8");
+ // The json-merge contract: whole-root re-serialization at the detected indent.
+ expect(after).toBe(JSON.stringify(JSON.parse(after), null, 2) + "\n");
+ const parsed = JSON.parse(after);
+ expect(parsed.mcp["open-second-brain"].type).toBe("local");
+ expect(parsed.mcp.servers).toBeUndefined();
+ expect(parsed["$schema"]).toBe("https://opencode.ai/config.json");
+ // The plan preview keeps today's wording for the V1 route.
+ expect(opencodeAdapter.plan(payload(), env()).steps[0]?.preview).toContain("into mcp at ");
+ expect(before).not.toBe(after);
+ });
+
+ test("when only opencode.jsonc exists it is the resolved path and comments survive apply byte-for-byte", () => {
+ const text = writeJsoncV2Fixture();
+ expect(opencodeAdapter.detect(env()).configPath).toBe(jsoncConfigPath());
+ opencodeAdapter.apply(opencodeAdapter.plan(payload(), env()), payload(), env(), applyOpts());
+ const after = readFileSync(jsoncConfigPath(), "utf8");
+ expect(after.startsWith("// opencode configuration - operator notes survive\n")).toBe(true);
+ expect(after).toContain('"theme": "dark", // inline note\n');
+ // The untouched comment-carrying lines are byte-identical; only the
+ // spliced entry is new.
+ const parsed = parseJsoncObject(after);
+ const servers = recordAt(recordAt(parsed, "mcp"), "servers");
+ expect(recordAt(servers, "open-second-brain").type).toBe("local");
+ expect(servers.other).toEqual({ type: "remote", url: "https://x" });
+ expect(opencodeAdapter.verify(env()).status).toBe("ok");
+ expect(text).toContain('"other": { "type": "remote", "url": "https://x" },\n');
+ expect(after).toContain('"other": { "type": "remote", "url": "https://x" },\n');
+ });
+
+ test("a .jsonc file with a V1 shape gets top-level mcp with comments preserved", () => {
+ const text = `// operator notes survive here too
+{
+ "theme": "dark", // inline note
+}
+`;
+ mkdirSync(dirname(jsoncConfigPath()), { recursive: true });
+ writeFileSync(jsoncConfigPath(), text);
+ opencodeAdapter.apply(opencodeAdapter.plan(payload(), env()), payload(), env(), applyOpts());
+ const after = readFileSync(jsoncConfigPath(), "utf8");
+ expect(after.startsWith("// operator notes survive here too\n")).toBe(true);
+ // The comment bytes survive; a comment sitting between the last
+ // entry and the closing brace ends up trailing the splice point,
+ // still inside the object it documents.
+ expect(after).toContain("// inline note");
+ const parsed = parseJsoncObject(after);
+ expect(parsed.theme).toBe("dark");
+ const mcp = recordAt(parsed, "mcp");
+ expect(recordAt(mcp, "open-second-brain").type).toBe("local");
+ expect(mcp.servers).toBeUndefined();
+ expect(opencodeAdapter.verify(env()).status).toBe("ok");
+ });
+
+ test("a commented JSONC config with no mcp key detects as not-installed, like plain JSON", () => {
+ // An operator's hand-written config that merely carries comments: no
+ // mcp key at all. Base detect maps the absent key to not-installed;
+ // the editor route must agree, or `o2b update` - which skips only
+ // not-installed targets - would perform a full install into an
+ // opencode that was never installed.
+ mkdirSync(dirname(jsoncConfigPath()), { recursive: true });
+ writeFileSync(jsoncConfigPath(), `// my notes\n{\n "theme": "dark"\n}\n`);
+ const d = opencodeAdapter.detect(env());
+ expect(d.status).toBe("not-installed");
+ expect(d.notes).toEqual([]);
+ // The plain-JSON twin of the same content agrees, so the verdict
+ // splits on key presence, not on the file's syntax.
+ writeJson(configPath(), { theme: "dark" });
+ expect(opencodeAdapter.detect(env()).status).toBe("not-installed");
+ rmSync(configPath());
+ // A PRESENT-but-non-object mcp block is still drift: the file carries
+ // something where our registration belongs.
+ writeFileSync(jsoncConfigPath(), `// my notes\n{\n "theme": "dark",\n "mcp": "enabled"\n}\n`);
+ const drift = opencodeAdapter.detect(env());
+ expect(drift.status).toBe("drift");
+ expect(drift.notes.join(" ")).toContain("mcp is not a JSON object");
+ });
+
+ test("duplicate top-level keys refuse apply naming the file, without a partial write", () => {
+ const dup = `// ambiguous config
+{
+ "theme": "dark",
+ "theme": "light",
+}
+`;
+ mkdirSync(dirname(jsoncConfigPath()), { recursive: true });
+ writeFileSync(jsoncConfigPath(), dup);
+ let thrown: unknown;
+ try {
+ opencodeAdapter.apply(opencodeAdapter.plan(payload(), env()), payload(), env(), applyOpts());
+ } catch (e) {
+ thrown = e;
+ }
+ expect(thrown).toBeInstanceOf(JsoncEditError);
+ expect((thrown as Error).message).toContain(jsoncConfigPath());
+ expect((thrown as Error).name).toBe("JsoncEditError");
+ expect(readFileSync(jsoncConfigPath(), "utf8")).toBe(dup);
+ });
+
+ test("an mcp.servers appearance is not migrated until re-apply, and the first re-apply refuses through the guard", () => {
+ // A healthy V1 install first.
+ opencodeAdapter.apply(opencodeAdapter.plan(payload(), env()), payload(), env(), applyOpts());
+ // The host upgrades to the native shape: mcp.servers appears, the
+ // file is touched after the manifest's applied_at.
+ const parsed = JSON.parse(readFileSync(configPath(), "utf8"));
+ parsed.mcp.servers = {};
+ writeFileSync(configPath(), JSON.stringify(parsed, null, 2) + "\n");
+ const future = new Date(env().now.getTime() + 60_000);
+ utimesSync(configPath(), future, future);
+
+ // Nothing migrates without an operator re-apply.
+ const before = JSON.parse(readFileSync(configPath(), "utf8"));
+ expect(before.mcp["open-second-brain"]).toBeDefined();
+ expect(before.mcp.servers["open-second-brain"]).toBeUndefined();
+
+ // verify reports the one-time drift: the native shape lacks our entries.
+ expect(opencodeAdapter.verify(env()).status).toBe("drift");
+
+ // The first re-apply refuses through the user-modified-block guard.
+ let thrown: unknown;
+ try {
+ opencodeAdapter.apply(opencodeAdapter.plan(payload(), env()), payload(), env(), applyOpts());
+ } catch (e) {
+ thrown = e;
+ }
+ expect(thrown).toBeInstanceOf(InstallError);
+ expect((thrown as InstallError).kind).toBe("user-modified-block");
+ expect((thrown as Error).message).toContain("hand-edited");
+
+ // The operator's forced re-apply lands the native entries and removes
+ // our shadowed legacy copies.
+ opencodeAdapter.apply(opencodeAdapter.plan(payload(), env()), payload(), env(), {
+ ...applyOpts(),
+ force: true,
+ });
+ const after = JSON.parse(readFileSync(configPath(), "utf8"));
+ expect(after.mcp.servers["open-second-brain"].type).toBe("local");
+ expect(after.mcp["open-second-brain"]).toBeUndefined();
+ expect(after.mcp["open-second-brain-writer"]).toBeUndefined();
+ expect(opencodeAdapter.verify(env()).status).toBe("ok");
+ });
+
+ test("the plan names the resolved shape before any write", () => {
+ // No config: today's fresh-install wording.
+ expect(opencodeAdapter.plan(payload(), env()).steps[0]?.preview).toContain("into mcp at ");
+ writeJson(configPath(), { mcp: { servers: {} } });
+ const v2Plan = opencodeAdapter.plan(payload(), env());
+ expect(v2Plan.steps[0]?.preview).toContain("into mcp.servers at ");
+ expect(v2Plan.steps[0]?.path).toBe(configPath());
+ });
+});
+
+describe("opencode adapter - __proto__ injection", () => {
+ /**
+ * The audit's attack: a cloned or synced config whose only Open
+ * Second Brain registration sits under a literal `__proto__` key. A
+ * host parsing with JSON.parse sees no registration; the adapter must
+ * agree.
+ */
+ function writeCraftedProtoConfig(): string {
+ const text = `{
+ "mcp": {
+ "servers": {
+ "__proto__": {
+ "open-second-brain": { "type": "local", "command": ["evil"], "enabled": true },
+ "open-second-brain-writer": { "type": "local", "command": ["evil"], "enabled": true }
+ }
+ }
+ }
+}
+`;
+ mkdirSync(dirname(configPath()), { recursive: true });
+ writeFileSync(configPath(), text);
+ return text;
+ }
+
+ test("a crafted __proto__ key never reads as an install", () => {
+ writeCraftedProtoConfig();
+ expect(opencodeAdapter.detect(env()).status).toBe("not-installed");
+ expect(opencodeAdapter.verify(env()).status).toBe("not-installed");
+ });
+
+ test("apply heals a polluted file with real own keys instead of refusing", () => {
+ // An owned install first, so the user-modified-block guard is armed.
+ opencodeAdapter.apply(opencodeAdapter.plan(payload(), env()), payload(), env(), applyOpts());
+ writeCraftedProtoConfig();
+ // Pre-fix the in-based guard saw our keys through the injected
+ // prototype and refused with the hand-edited message on content that
+ // registers nothing.
+ opencodeAdapter.apply(opencodeAdapter.plan(payload(), env()), payload(), env(), applyOpts());
+ const parsed = JSON.parse(readFileSync(configPath(), "utf8")) as {
+ mcp: { servers: Record<string, unknown> };
+ };
+ const servers = parsed.mcp.servers;
+ // A JSON.parse host now sees a real registration beside the inert
+ // literal key - which is file content this adapter does not own and
+ // leaves alone.
+ expect(Object.hasOwn(servers, "open-second-brain")).toBe(true);
+ expect(Object.hasOwn(servers, "open-second-brain-writer")).toBe(true);
+ expect(Object.hasOwn(servers, "__proto__")).toBe(true);
+ expect(opencodeAdapter.detect(env()).status).toBe("installed");
+ expect(opencodeAdapter.verify(env()).status).toBe("ok");
+ });
+});
+
+describe("opencode adapter - both-files precedence", () => {
+ test("a legacy opencode.json with our keys outranks a newer opencode.jsonc for every verb", () => {
+ // A real V1 install first: our keys live in opencode.json.
+ opencodeAdapter.apply(opencodeAdapter.plan(payload(), env()), payload(), env(), applyOpts());
+ // The host later creates a newer opencode.jsonc carrying mcp.servers.
+ const jsoncText = `// newer host-managed config
+{
+ "mcp": {
+ "servers": {
+ "other": { "type": "remote", "url": "https://x" },
+ },
+ },
+}
+`;
+ mkdirSync(dirname(jsoncConfigPath()), { recursive: true });
+ writeFileSync(jsoncConfigPath(), jsoncText);
+
+ // detect resolves to the legacy file and finds our keys there.
+ const d = opencodeAdapter.detect(env());
+ expect(d.configPath).toBe(configPath());
+ expect(d.status).toBe("installed");
+
+ // apply services the legacy file; the .jsonc file is never touched.
+ const result = opencodeAdapter.apply(
+ opencodeAdapter.plan(payload(), env()),
+ payload(),
+ env(),
+ applyOpts(),
+ );
+ expect(result.manifest.config_path).toBe(configPath());
+ expect(readFileSync(jsoncConfigPath(), "utf8")).toBe(jsoncText);
+ expect(readManifest(vault).installs["opencode"]?.config_path).toBe(configPath());
+
+ // verify reads the legacy file and reports ok against it.
+ expect(opencodeAdapter.verify(env()).status).toBe("ok");
+
+ // uninstall sweeps the legacy file; the .jsonc file stays byte-identical.
+ const u = opencodeAdapter.uninstall(env(), applyOpts());
+ expect(u.removed_keys).toEqual(["mcp.open-second-brain", "mcp.open-second-brain-writer"]);
+ expect(readFileSync(jsoncConfigPath(), "utf8")).toBe(jsoncText);
+ const after = JSON.parse(readFileSync(configPath(), "utf8")) as {
+ mcp: Record<string, unknown>;
+ };
+ expect(after.mcp["open-second-brain"]).toBeUndefined();
+ expect(after.mcp["open-second-brain-writer"]).toBeUndefined();
+ expect(readManifest(vault).installs["opencode"]).toBeUndefined();
+ expect(opencodeAdapter.detect(env()).status).toBe("not-installed");
+ });
+});
diff --git a/tests/core/install/jsonc.test.ts b/tests/core/install/jsonc.test.ts
new file mode 100644
index 00000000..2dc51960
--- /dev/null
+++ b/tests/core/install/jsonc.test.ts
@@ -0,0 +1,575 @@
+/**
+ * The vendored minimal JSONC editor.
+ *
+ * The repo has exactly one runtime dependency and no JSONC handling, and
+ * the OpenCode V2 config surface needs exactly this narrow edit: locate a
+ * nested key in a JSONC document, splice one entry in or out, and keep
+ * every byte outside the spliced range - comments included - as it was.
+ * These tests pin that contract: token-offset splices, not
+ * re-serialization; named `JsoncEditError` refusals for malformed or
+ * ambiguous input; BOM stripped on read and restored on write.
+ */
+
+import { describe, expect, test } from "bun:test";
+
+import {
+ JsoncEditError,
+ hasJsoncSyntax,
+ parseJsoncObject,
+ removeJsoncEntry,
+ setJsoncEntry,
+} from "../../../src/core/install/jsonc.ts";
+
+const FULL_ENTRY = { type: "local", command: ["o2b", "mcp"], enabled: true };
+const WRITER_ENTRY = {
+ type: "local",
+ command: ["o2b", "mcp", "--writer-only"],
+ enabled: true,
+};
+
+/** A JSONC config with a header comment, an inline comment and a trailing comma. */
+const COMMENTED_CONFIG = `// opencode configuration
+{
+ "theme": "dark",
+ "mcp": {
+ "other": { "type": "remote" },
+ },
+}
+`;
+
+const COMMENTED_CONFIG_WITH_FULL = `// opencode configuration
+{
+ "theme": "dark",
+ "mcp": {
+ "other": { "type": "remote" },
+ "servers": {
+ "open-second-brain": {
+ "type": "local",
+ "command": [
+ "o2b",
+ "mcp"
+ ],
+ "enabled": true
+ }
+ }
+ },
+}
+`;
+
+const COMMENTED_CONFIG_WITH_BOTH = `// opencode configuration
+{
+ "theme": "dark",
+ "mcp": {
+ "other": { "type": "remote" },
+ "servers": {
+ "open-second-brain": {
+ "type": "local",
+ "command": [
+ "o2b",
+ "mcp"
+ ],
+ "enabled": true
+ },
+ "open-second-brain-writer": {
+ "type": "local",
+ "command": [
+ "o2b",
+ "mcp",
+ "--writer-only"
+ ],
+ "enabled": true
+ }
+ }
+ },
+}
+`;
+
+const COMMENTED_CONFIG_WITH_WRITER = `// opencode configuration
+{
+ "theme": "dark",
+ "mcp": {
+ "other": { "type": "remote" },
+ "servers": {
+ "open-second-brain-writer": {
+ "type": "local",
+ "command": [
+ "o2b",
+ "mcp",
+ "--writer-only"
+ ],
+ "enabled": true
+ }
+ }
+ },
+}
+`;
+const REPLACED_FULL_CONFIG = `// opencode configuration
+{
+ "theme": "dark",
+ "mcp": {
+ "other": { "type": "remote" },
+ "servers": {
+ "open-second-brain": {
+ "type": "local",
+ "command": [
+ "o2b",
+ "mcp",
+ "--vault",
+ "/v"
+ ],
+ "enabled": false
+ }
+ }
+ },
+}
+`;
+
+/** Removing the last entry leaves its (now empty) object behind - entries go, keys stay. */
+const EMPTY_SERVERS_CONFIG = `// opencode configuration
+{
+ "theme": "dark",
+ "mcp": {
+ "other": { "type": "remote" },
+ "servers": {
+ }
+ },
+}
+`;
+
+describe("parseJsoncObject", () => {
+ test("parses line comments, block comments, comment-like string content, escapes and trailing commas", () => {
+ const text = `{
+ // a line comment with "quotes" and /* block-like content */
+ "url": "https://example.test/a//b?c=1", /* trailing block comment */
+ "escaped": "line\\nbreak \\"quoted\\" \\\\ backslash",
+ "list": [1, 2,],
+}`;
+ expect(parseJsoncObject(text)).toEqual({
+ url: "https://example.test/a//b?c=1",
+ escaped: 'line\nbreak "quoted" \\ backslash',
+ list: [1, 2],
+ });
+ });
+
+ test("a BOM is stripped on read", () => {
+ const parsed = parseJsoncObject("\uFEFF" + COMMENTED_CONFIG);
+ expect(parsed["theme"]).toBe("dark");
+ });
+
+ test("malformed input raises the named JsoncEditError", () => {
+ for (const text of ['{ "mcp": ', '{ "mcp": }', "{} trailing", '{ "a": 1 } /*', "{"]) {
+ try {
+ parseJsoncObject(text);
+ throw new Error(`expected JsoncEditError for ${JSON.stringify(text)}`);
+ } catch (e) {
+ expect(e).toBeInstanceOf(JsoncEditError);
+ expect((e as Error).name).toBe("JsoncEditError");
+ }
+ }
+ });
+
+ test("punctuation in a value position raises instead of parsing as null", () => {
+ // A missing value is malformed input, not a null: reading `{"a": ,}`
+ // as `{"a": null}` would let apply proceed on a file no JSON parser
+ // accepts. Each reviewed repro, plus the array and mid-object forms.
+ for (const text of ['{"a": ,}', '{"a": :, "b": 1}', "[,]", '{"a": 1, "b": }', "[1, , 2]"]) {
+ try {
+ parseJsoncObject(text);
+ throw new Error(`expected JsoncEditError for ${JSON.stringify(text)}`);
+ } catch (e) {
+ expect(e).toBeInstanceOf(JsoncEditError);
+ expect((e as Error).name).toBe("JsoncEditError");
+ }
+ }
+ // The legal trailing-comma neighbors still parse.
+ expect(parseJsoncObject('{"a": 1,}')).toEqual({ a: 1 });
+ expect(parseJsoncObject('{"a": [1,]}')).toEqual({ a: [1] });
+ });
+
+ test("duplicate keys raise the named error mentioning the key", () => {
+ expect(() => parseJsoncObject('{ "mcp": {}, "mcp": {} }')).toThrow(/mcp/);
+ expect(() => parseJsoncObject('{ "mcp": { "servers": { "k": 1, "k": 2 } } }')).toThrow(/\bk\b/);
+ try {
+ parseJsoncObject('{ "mcp": {}, "mcp": {} }');
+ } catch (e) {
+ expect(e).toBeInstanceOf(JsoncEditError);
+ expect((e as Error).message).toContain("mcp");
+ }
+ });
+
+ test("a non-object root raises the named error", () => {
+ expect(() => parseJsoncObject("[1, 2]")).toThrow(JsoncEditError);
+ expect(() => parseJsoncObject('"just a string"')).toThrow(JsoncEditError);
+ });
+});
+
+describe("parseJsoncObject - __proto__ keys", () => {
+ /**
+ * Both Open Second Brain entry keys with an attacker-chosen command,
+ * as the audit's payload.
+ */
+ const CRAFTED_ENTRIES =
+ '{"open-second-brain":{"type":"local","command":["evil"],"enabled":true},' +
+ '"open-second-brain-writer":{"type":"local","command":["evil"],"enabled":true}}';
+
+ test("a literal __proto__ key stays an inert own property, never the prototype", () => {
+ const parsed = parseJsoncObject(`{"mcp":{"servers":{"__proto__":${CRAFTED_ENTRIES}}}}`);
+ const mcp = parsed["mcp"] as Record<string, unknown>;
+ const servers = mcp["servers"] as Record<string, unknown>;
+ // These are the reads the audit forged: pre-fix, `in` and bracket
+ // access saw the crafted entries through the injected prototype, so
+ // detect reported an install on a file whose real content registers
+ // nothing.
+ expect("open-second-brain" in servers).toBe(false);
+ expect("open-second-brain-writer" in servers).toBe(false);
+ expect(servers["open-second-brain"]).toBeUndefined();
+ expect(servers["open-second-brain-writer"]).toBeUndefined();
+ // The key itself survives as an inert literal, exactly the semantics
+ // JSON.parse gives it.
+ expect(Object.hasOwn(servers, "__proto__")).toBe(true);
+ expect(Object.keys(servers)).toEqual(["__proto__"]);
+ });
+
+ test("a root-level __proto__ carrying a whole mcp tree forges nothing", () => {
+ const parsed = parseJsoncObject(`{"__proto__":{"mcp":{"servers":${CRAFTED_ENTRIES}}}}`);
+ expect("mcp" in parsed).toBe(false);
+ expect(parsed["mcp"]).toBeUndefined();
+ expect(Object.keys(parsed)).toEqual(["__proto__"]);
+ });
+
+ test("the word __proto__ in comments and string values stays legal", () => {
+ const text = '{ /* __proto__ */ "note": "see __proto__ docs", "mcp": { "servers": {} } }';
+ expect(parseJsoncObject(text)).toEqual({ note: "see __proto__ docs", mcp: { servers: {} } });
+ });
+});
+
+describe("hasJsoncSyntax", () => {
+ test("plain JSON is not JSONC", () => {
+ expect(hasJsoncSyntax('{ "mcp": { "servers": {} } }\n')).toBe(false);
+ expect(hasJsoncSyntax('\uFEFF{ "mcp": {} }\n')).toBe(false);
+ });
+
+ test("comment-like content inside a string is not a JSONC feature", () => {
+ expect(hasJsoncSyntax('{ "url": "https://x//not-a-comment", "b": "a/*b*/c" }')).toBe(false);
+ });
+
+ test("comments and trailing commas are JSONC features", () => {
+ expect(hasJsoncSyntax('{ // note\n "a": 1 }')).toBe(true);
+ expect(hasJsoncSyntax('{ "a": 1 } /* tail */')).toBe(true);
+ expect(hasJsoncSyntax('{ "a": 1, }')).toBe(true);
+ expect(hasJsoncSyntax('{ "a": [1, 2,] }')).toBe(true);
+ });
+});
+
+describe("setJsoncEntry", () => {
+ test("inserts one entry under a nested object, splicing at token offsets", () => {
+ expect(
+ setJsoncEntry(COMMENTED_CONFIG, ["mcp", "servers"], "open-second-brain", FULL_ENTRY),
+ ).toBe(COMMENTED_CONFIG_WITH_FULL);
+ });
+
+ test("every byte outside the spliced range survives the insert", () => {
+ const result = setJsoncEntry(
+ COMMENTED_CONFIG,
+ ["mcp", "servers"],
+ "open-second-brain",
+ FULL_ENTRY,
+ );
+ // The header comment and the untouched "theme" line are byte-identical.
+ expect(result.startsWith('// opencode configuration\n{\n "theme": "dark",')).toBe(true);
+ expect(result).toContain('"other": { "type": "remote" },\n');
+ });
+
+ test("creates missing intermediate objects along the path", () => {
+ const text = `{
+ "theme": "dark"
+}
+`;
+ expect(setJsoncEntry(text, ["mcp", "servers"], "k", { enabled: true })).toBe(`{
+ "theme": "dark",
+ "mcp": {
+ "servers": {
+ "k": {
+ "enabled": true
+ }
+ }
+ }
+}
+`);
+ });
+
+ test("replacing an existing entry splices exactly its value range", () => {
+ const updated = {
+ ...FULL_ENTRY,
+ command: [...FULL_ENTRY.command, "--vault", "/v"],
+ enabled: false,
+ };
+ expect(
+ setJsoncEntry(COMMENTED_CONFIG_WITH_FULL, ["mcp", "servers"], "open-second-brain", updated),
+ ).toBe(REPLACED_FULL_CONFIG);
+ });
+
+ test("a single-line object stays single-line when filled", () => {
+ expect(setJsoncEntry('{ "mcp": {} }', ["mcp"], "k", { a: 1 })).toBe(
+ '{ "mcp": {"k": {"a":1}} }',
+ );
+ });
+
+ test("a single-line object with a trailing comma does not gain a doubled comma", () => {
+ const grown = setJsoncEntry('{ "a": 1, }', [], "b", 2);
+ expect(parseJsoncObject(grown)).toEqual({ a: 1, b: 2 });
+ });
+
+ test("an inserted entry does not take over the last entry's line comment", () => {
+ const text = `{
+ "a": {"x": 1} // keep me with a
+}
+`;
+ const result = setJsoncEntry(text, [], "osb", { enabled: true });
+ // The separator lands at the old value end, before the comment, and
+ // the comment keeps annotating a's line - not the inserted entry.
+ expect(result).toContain('"a": {"x": 1}, // keep me with a\n');
+ const commentLine = result.split("\n").find((line) => line.includes("// keep me with a"));
+ expect(commentLine).toContain('"a"');
+ expect(commentLine).not.toContain('"osb"');
+ expect(parseJsoncObject(result)).toEqual({ a: { x: 1 }, osb: { enabled: true } });
+ });
+
+ test("install then uninstall restores a commented trailing-comma line byte for byte", () => {
+ const text = `{
+ "a": 1, // note a
+}
+`;
+ const grown = setJsoncEntry(text, [], "osb", { enabled: true });
+ expect(parseJsoncObject(grown)).toEqual({ a: 1, osb: { enabled: true } });
+ // The inserted entry opens the line after a's, past the comma and
+ // the comment.
+ expect(grown).toContain('"a": 1, // note a\n "osb": {');
+ expect(removeJsoncEntry(grown, [], "osb")).toBe(text);
+ });
+
+ test("an insert never lands inside a block comment that runs past the value's line", () => {
+ const text = `{
+ "a": 1 /* note
+ more note */
+}
+`;
+ const result = setJsoncEntry(text, [], "b", 2);
+ expect(parseJsoncObject(result)).toEqual({ a: 1, b: 2 });
+ expect(result).toContain("/* note\n more note */");
+ });
+
+ test("a leading block comment does not shrink the indent unit", () => {
+ const text = `/*
+ * my config
+ */
+{
+ "a": 1
+}
+`;
+ const result = setJsoncEntry(text, [], "b", { k: 1 });
+ // Two-space steps: the unit comes from the `"a": 1` line, which
+ // starts with a token - not from the comment star's column.
+ expect(result).toContain(' "b": {\n "k": 1\n }');
+ expect(parseJsoncObject(result)).toEqual({ a: 1, b: { k: 1 } });
+ });
+
+ test("replacing a single-line entry keeps it single-line, so re-sets stay byte-stable", () => {
+ // Compact form is JSON.stringify's own, the form this editor writes.
+ const text = `{
+ "mcp": {
+ "servers": {"open-second-brain": {"enabled":true}}
+ }
+}
+`;
+ const once = setJsoncEntry(text, ["mcp", "servers"], "open-second-brain", { enabled: true });
+ expect(once).toBe(text);
+ const twice = setJsoncEntry(once, ["mcp", "servers"], "open-second-brain", { enabled: true });
+ expect(twice).toBe(text);
+ });
+
+ test("a comment-free canonical file re-set with the same entry is byte-identical", () => {
+ const canonical =
+ JSON.stringify({ mcp: { servers: { "open-second-brain": FULL_ENTRY } } }, null, 2) + "\n";
+ expect(setJsoncEntry(canonical, ["mcp", "servers"], "open-second-brain", FULL_ENTRY)).toBe(
+ canonical,
+ );
+ });
+
+ test("a path segment that is not an object raises the named error", () => {
+ expect(() => setJsoncEntry('{ "mcp": 3 }', ["mcp", "servers"], "k", true)).toThrow(
+ JsoncEditError,
+ );
+ });
+
+ test("a non-serializable value raises instead of emitting partial text", () => {
+ expect(() => setJsoncEntry("{}" as string, [], "k", undefined)).toThrow(JsoncEditError);
+ });
+
+ test("malformed input raises the named error rather than emitting partial text", () => {
+ expect(() => setJsoncEntry("{ not json", ["mcp"], "k", true)).toThrow(JsoncEditError);
+ });
+
+ test("a BOM on the input is restored on the output", () => {
+ const result = setJsoncEntry(
+ "\uFEFF" + COMMENTED_CONFIG,
+ ["mcp", "servers"],
+ "open-second-brain",
+ FULL_ENTRY,
+ );
+ expect(result.startsWith("\uFEFF// opencode configuration")).toBe(true);
+ expect(result.slice(1)).toBe(COMMENTED_CONFIG_WITH_FULL);
+ });
+});
+
+describe("removeJsoncEntry", () => {
+ test("removing an entry closes the hole without disturbing neighbors", () => {
+ expect(
+ removeJsoncEntry(COMMENTED_CONFIG_WITH_BOTH, ["mcp", "servers"], "open-second-brain"),
+ ).toBe(COMMENTED_CONFIG_WITH_WRITER);
+ expect(
+ removeJsoncEntry(
+ COMMENTED_CONFIG_WITH_WRITER,
+ ["mcp", "servers"],
+ "open-second-brain-writer",
+ ),
+ ).toBe(EMPTY_SERVERS_CONFIG);
+ });
+
+ test("a set followed by a remove restores the original bytes", () => {
+ const canonical =
+ JSON.stringify({ mcp: { servers: { "open-second-brain": FULL_ENTRY } } }, null, 2) + "\n";
+ const grown = setJsoncEntry(
+ canonical,
+ ["mcp", "servers"],
+ "open-second-brain-writer",
+ WRITER_ENTRY,
+ );
+ expect(grown).not.toBe(canonical);
+ expect(removeJsoncEntry(grown, ["mcp", "servers"], "open-second-brain-writer")).toBe(canonical);
+ });
+
+ test("an absent key or absent path is a byte-identical no-op", () => {
+ expect(removeJsoncEntry(COMMENTED_CONFIG, ["mcp", "servers"], "open-second-brain")).toBe(
+ COMMENTED_CONFIG,
+ );
+ expect(removeJsoncEntry(COMMENTED_CONFIG, ["nope", "deeper"], "open-second-brain")).toBe(
+ COMMENTED_CONFIG,
+ );
+ });
+
+ test("a comment sharing the removed entry's line survives", () => {
+ const text = `{
+ "mcp": {
+ "keep": 1,
+ "osb": 2 /* operator note */
+ }
+}
+`;
+ const result = removeJsoncEntry(text, ["mcp"], "osb");
+ expect(result).toContain("/* operator note */");
+ expect(parseJsoncObject(result)).toEqual({ mcp: { keep: 1 } });
+ });
+
+ test("a BOM on the input is restored on the output", () => {
+ const withBom = "\uFEFF" + COMMENTED_CONFIG_WITH_BOTH;
+ const result = removeJsoncEntry(withBom, ["mcp", "servers"], "open-second-brain");
+ expect(result.startsWith("\uFEFF")).toBe(true);
+ expect(result.slice(1)).toBe(COMMENTED_CONFIG_WITH_WRITER);
+ });
+
+ test("a comma-first document survives removing its comma-free entry", () => {
+ // The separator sits at the head of the FOLLOWING line - valid JSONC.
+ // The removal must consume that following comma, or the collapse of
+ // the entry's line strands it at the head of the object.
+ const text = `{
+ "a": 1
+ , "b": 2
+}
+`;
+ const result = removeJsoncEntry(text, [], "a");
+ expect(parseJsoncObject(result)).toEqual({ b: 2 });
+ // Bytes outside the splice survive: "b"'s line keeps its shape.
+ expect(result).toContain('"b": 2\n}\n');
+ });
+
+ test("a comma-first document survives removing its last entry byte-exactly", () => {
+ const text = `{
+ "a": 1
+ , "b": 2
+}
+`;
+ expect(removeJsoncEntry(text, [], "b")).toBe(`{
+ "a": 1
+}
+`);
+ });
+
+ test("inserting into a comma-first document keeps it parseable", () => {
+ const text = `{
+ "a": 1
+ , "b": 2
+}
+`;
+ const grown = setJsoncEntry(text, [], "c", 3);
+ expect(parseJsoncObject(grown)).toEqual({ a: 1, b: 2, c: 3 });
+ // The comma-first bytes survive the splice elsewhere; the new entry
+ // carries its own separator.
+ expect(grown).toContain(' , "b": 2,\n');
+ });
+
+ test("a trailing comma on a comment line above the entry is never eaten", () => {
+ // The walk-back must treat that comma as comment content, not a
+ // separator: every byte of an operator comment is kept exactly.
+ const text = `{
+ "a": 1,
+ // about b,
+ "b": 2
+}
+`;
+ const result = removeJsoncEntry(text, [], "b");
+ expect(result).toContain("// about b,\n");
+ expect(parseJsoncObject(result)).toEqual({ a: 1 });
+ });
+
+ test("a CRLF trailing-comma document removes its last entry byte-exactly", () => {
+ // \r is horizontal whitespace in the separator scans: a walk-back
+ // that stopped at the carriage return would miss the comma and
+ // strand a trailing comma instead of restoring the bytes.
+ const text = '{\r\n "a": 1,\r\n "osb": 2\r\n}\r\n';
+ expect(removeJsoncEntry(text, [], "osb")).toBe('{\r\n "a": 1\r\n}\r\n');
+ });
+
+ test("a CRLF comma-first document survives removing either entry", () => {
+ const text = '{\r\n "a": 1\r\n , "osb": 2\r\n}\r\n';
+ const withoutFirst = removeJsoncEntry(text, [], "a");
+ expect(parseJsoncObject(withoutFirst)).toEqual({ osb: 2 });
+ const withoutLast = removeJsoncEntry(text, [], "osb");
+ expect(parseJsoncObject(withoutLast)).toEqual({ a: 1 });
+ expect(withoutLast).toBe('{\r\n "a": 1\r\n}\r\n');
+ });
+
+ test("a comma-first separator hiding behind the entry's line comment is consumed", () => {
+ // Removing a first entry that carries a line comment must also take
+ // the next entry's leading comma with it, or the remainder is `{ // c
+ // , "b": 2 }` - JSONC no parser accepts.
+ const text = `{
+ "osb": 1 // note on osb
+ , "b": 2
+}
+`;
+ const result = removeJsoncEntry(text, [], "osb");
+ expect(parseJsoncObject(result)).toEqual({ b: 2 });
+ expect(result).toContain('"b": 2');
+ });
+
+ test("a number literal longer than 64 characters parses instead of false-refusing", () => {
+ const digits65 =
+ "12345678901234567890123456789012345678901234567890123456789012345678901234567";
+ const text = `{\n "big": ${digits65},\n "small": 1\n}\n`;
+ expect(parseJsoncObject(text)).toEqual({ big: Number(digits65), small: 1 });
+ // The editor route too: scanning the literal must not split it into
+ // two tokens and refuse the whole document.
+ expect(setJsoncEntry(text, [], "flag", true)).toContain('"flag": true');
+ });
+});
diff --git a/tests/core/search/config.test.ts b/tests/core/search/config.test.ts
index de5d1e19..a4ebdefd 100644
--- a/tests/core/search/config.test.ts
+++ b/tests/core/search/config.test.ts
@@ -4,6 +4,10 @@ import { tmpdir } from "node:os";
import { join } from "node:path";
import { resolveSearchConfig } from "../../../src/core/search/index.ts";
import { SearchError } from "../../../src/core/search/types.ts";
+import type { SearchOptions } from "../../../src/core/search/types.ts";
+import { configFingerprint } from "../../../src/core/search/pipeline/cache-slot.ts";
+import { buildCacheKey } from "../../../src/core/search/query-cache.ts";
+import { parseBenchPinnedKnobs } from "../../../src/cli/brain/verbs/bench.ts";
let tmp: string;
let configPath: string;
@@ -39,6 +43,7 @@ const ENV_KEYS = [
"OPEN_SECOND_BRAIN_SEARCH_RESUME_REINDEX",
"OPEN_SECOND_BRAIN_SEARCH_CHAIN_STOP",
"OPEN_SECOND_BRAIN_SEARCH_CHAIN_STOP_SCORE",
+ "OPEN_SECOND_BRAIN_SEARCH_POOL_MAX_PER_SESSION",
];
beforeEach(() => {
@@ -414,3 +419,93 @@ test("grace of 0 disables the await window", () => {
const cfg = resolveSearchConfig({ vault: tmp, configPath });
expect(cfg.shutdownGraceMs).toBe(0);
});
+
+// ── Per-source-session pool cap (t_bb6ce095) ─────────────────────────────────
+
+test("the per-session pool cap defaults off and resolves from config and env", () => {
+ writeFileSync(configPath, `vault: "${tmp}"\n`);
+ expect(resolveSearchConfig({ vault: tmp, configPath }).recall.poolMaxPerSession).toBeUndefined();
+
+ writeFileSync(configPath, `vault: "${tmp}"\nsearch_pool_max_per_session: "4"\n`);
+ expect(resolveSearchConfig({ vault: tmp, configPath }).recall.poolMaxPerSession).toBe(4);
+
+ process.env["OPEN_SECOND_BRAIN_SEARCH_POOL_MAX_PER_SESSION"] = "2";
+ expect(resolveSearchConfig({ vault: tmp, configPath }).recall.poolMaxPerSession).toBe(2);
+});
+
+test("a negative per-session pool cap is refused by the resolved-config validation", () => {
+ writeFileSync(configPath, `vault: "${tmp}"\nsearch_pool_max_per_session: "-1"\n`);
+ expect(() => resolveSearchConfig({ vault: tmp, configPath })).toThrow(
+ /search_pool_max_per_session/,
+ );
+});
+
+test("a non-integer per-session pool cap is refused", () => {
+ writeFileSync(configPath, `vault: "${tmp}"\nsearch_pool_max_per_session: "2.5"\n`);
+ expect(() => resolveSearchConfig({ vault: tmp, configPath })).toThrow(
+ /search_pool_max_per_session/,
+ );
+});
+
+test("the resolved field is absent at the off default and present when positive", () => {
+ writeFileSync(configPath, `vault: "${tmp}"\n`);
+ const off = resolveSearchConfig({ vault: tmp, configPath }).recall;
+ // Spread-omitted at 0: exact-shape assertions on the resolved config
+ // keep holding, exactly like the other opt-in recall fields.
+ expect(Object.keys(off)).not.toContain("poolMaxPerSession");
+
+ writeFileSync(configPath, `vault: "${tmp}"\nsearch_pool_max_per_session: "3"\n`);
+ const on = resolveSearchConfig({ vault: tmp, configPath }).recall as unknown as Record<
+ string,
+ unknown
+ >;
+ expect(on["poolMaxPerSession"]).toBe(3);
+});
+
+test("a pool-cap change re-keys the config fingerprint and the per-query cache key", () => {
+ writeFileSync(configPath, `vault: "${tmp}"\n`);
+ const off = resolveSearchConfig({ vault: tmp, configPath });
+ writeFileSync(configPath, `vault: "${tmp}"\nsearch_pool_max_per_session: "2"\n`);
+ const on = resolveSearchConfig({ vault: tmp, configPath });
+
+ // A results-affecting knob must invalidate cached rows: the fingerprint
+ // string differs, so a cached row computed under the old knob value can
+ // never be served under the new one.
+ expect(configFingerprint(on)).not.toBe(configFingerprint(off));
+
+ // The per-query override partitions the cache the same way; dropped
+ // when absent, so a query that does not set it keys byte-identically
+ // to a pre-knob row.
+ const base: SearchOptions = { query: "alpha" };
+ expect(buildCacheKey({ ...base, poolMaxPerSession: 2 }, "p", "fp")).not.toBe(
+ buildCacheKey(base, "p", "fp"),
+ );
+ // An explicit per-query 0 is a forced off, not the config default.
+ expect(buildCacheKey({ ...base, poolMaxPerSession: 0 }, "p", "fp")).not.toBe(
+ buildCacheKey(base, "p", "fp"),
+ );
+
+ // The review-L4 boundary does NOT mute the folds: a value at or above
+ // the query's resolved pool width behaves as off (it cannot drop a row
+ // from that pool), but the value still keys both caches, so a change
+ // around that boundary can never serve a stale cached row.
+ writeFileSync(configPath, `vault: "${tmp}"\nsearch_pool_max_per_session: "10000"\n`);
+ const huge = resolveSearchConfig({ vault: tmp, configPath });
+ expect(configFingerprint(huge)).not.toBe(configFingerprint(off));
+ expect(buildCacheKey({ ...base, poolMaxPerSession: 10_000 }, "p", "fp")).not.toBe(
+ buildCacheKey(base, "p", "fp"),
+ );
+});
+
+test("the bench pin accepts the pool-cap knob name in a recall pin", () => {
+ // The measured-decision-note harness pins recall knobs by name, so the
+ // new knob must join the pin's known recall keys or every pin naming
+ // it is refused.
+ const pin = parseBenchPinnedKnobs('{"recall":{"poolMaxPerSession":2}}');
+ expect(pin.recall?.poolMaxPerSession).toBe(2);
+
+ // A name outside the list is still refused, by name.
+ expect(() => parseBenchPinnedKnobs('{"recall":{"poolCapNonsense":2}}')).toThrow(
+ /poolCapNonsense.*not a known knob/,
+ );
+});
diff --git a/tests/core/search/pool-total.test.ts b/tests/core/search/pool-total.test.ts
index 22dd24b5..7a4272c5 100644
--- a/tests/core/search/pool-total.test.ts
+++ b/tests/core/search/pool-total.test.ts
@@ -13,6 +13,16 @@ import { afterEach, beforeEach, expect, test } from "bun:test";
import { indexVault } from "../../../src/core/search/indexer.ts";
import { search } from "../../../src/core/search/search.ts";
+import { Store } from "../../../src/core/search/store.ts";
+import { assembleRankedResults } from "../../../src/core/search/pipeline/assemble.ts";
+import { collectCandidateSignals } from "../../../src/core/search/pipeline/candidate-signals.ts";
+import { parseBenchPinnedKnobs } from "../../../src/cli/brain/verbs/bench.ts";
+import {
+ RETRIEVAL_DEGRADATION,
+ type RetrievalDegradation,
+} from "../../../src/core/search/retrieval-trail.ts";
+import type { ResolvedRecallConfig, ResolvedSearchConfig } from "../../../src/core/search/types.ts";
+import type { KeywordHit } from "../../../src/core/search/store.ts";
import { createTempVault, makeConfig, writeMd } from "../../helpers/search-fixtures.ts";
/** Matching notes, comfortably above the `limit` the queries below use. */
@@ -78,3 +88,651 @@ test("a query with no candidates still reports zero", async () => {
expect(out.results).toEqual([]);
expect(out.total).toBe(0);
});
+
+// ── per-source-session pool cap (t_bb6ce095) ─────────────────────────────────
+
+/** One recall patch over the harness config, the way trail tests patch it. */
+function withRecall(
+ base: ResolvedSearchConfig,
+ patch: Partial<ResolvedRecallConfig>,
+): ResolvedSearchConfig {
+ return Object.freeze({ ...base, recall: Object.freeze({ ...base.recall, ...patch }) });
+}
+
+/** The crowded fixture: six hot notes in one source session, three elsewhere. */
+const CROWDED_HOT_NOTES = 6;
+const CROWDED_QUERY = "widget calibration";
+
+function writeCrowdedVault(vaultDir: string): void {
+ for (let i = 0; i < CROWDED_HOT_NOTES; i += 1) {
+ writeMd(
+ vaultDir,
+ `a-${i}.md`,
+ `---\ntitle: Crowded ${i}\nsession_ref: sess-a\n---\n\n# Crowded ${i}\n\n` +
+ `The widget calibration routine number ${i}. Widget calibration is repeated here. ` +
+ `Widget calibration matters to this note.\n`,
+ );
+ }
+ for (const session of ["b", "c", "d"]) {
+ writeMd(
+ vaultDir,
+ `${session}.md`,
+ `---\ntitle: Other ${session}\nsession_ref: sess-${session}\n---\n\n# Other ${session}\n\n` +
+ `The widget calibration routine of session ${session}.\n`,
+ );
+ }
+}
+
+/** A clock-free fixture config: the recency layer is amplitude zero. */
+async function indexedCrowdedVault() {
+ const v = createTempVault("pool-cap-crowded");
+ writeCrowdedVault(v.vault);
+ const cold = withRecall(
+ makeConfig({ vault: v.vault, dbPath: v.dbPath, maxHops: 0, mmrLambda: 1 }),
+ {
+ recencyAmplitude: 0,
+ },
+ );
+ await indexVault(cold, {});
+ return { ...v, cold };
+}
+
+function degradationOf(
+ out: { readonly retrievalTrail?: { readonly degraded: ReadonlyArray<RetrievalDegradation> } },
+ code: string,
+): RetrievalDegradation | undefined {
+ return out.retrievalTrail?.degraded.find((d) => d.code === code);
+}
+
+test("the cap off returns today's crowded order byte-for-byte", async () => {
+ const v = await indexedCrowdedVault();
+ try {
+ const off = await search(v.cold, { query: CROWDED_QUERY, limit: LIMIT });
+ const explicitOff = await search(withRecall(v.cold, { poolMaxPerSession: 0 }), {
+ query: CROWDED_QUERY,
+ limit: LIMIT,
+ });
+
+ // The off path is the pre-knob pipeline: an explicit 0 answers with
+ // the default's exact bytes.
+ expect(JSON.stringify(explicitOff)).toBe(JSON.stringify(off));
+ // Frozen pre-change expectation, so the proof is anchored outside
+ // this build: a regression that shifts BOTH arms of the A/B above
+ // identically now goes red. Order and trail identity are pinned -
+ // never score magnitudes. The crowded session takes every window
+ // slot, and the only narrowing the off answer names is the pre-knob
+ // rank-cap truncation, never a session-cap note.
+ expect(off.results.map((r) => r.path)).toEqual(["a-0.md", "a-1.md", "a-2.md"]);
+ expect(off.retrievalTrail?.degraded).toEqual([
+ { code: RETRIEVAL_DEGRADATION.rankCapTruncatedPool, detail: { cap: LIMIT } },
+ ]);
+ } finally {
+ v.cleanup();
+ }
+});
+
+test("the cap on spreads the window across sessions and names its drop", async () => {
+ const v = await indexedCrowdedVault();
+ try {
+ const on = await search(withRecall(v.cold, { poolMaxPerSession: 2 }), {
+ query: CROWDED_QUERY,
+ limit: LIMIT,
+ });
+
+ expect(on.results.length).toBe(LIMIT);
+ // Two crowded-session rows keep the top slots; the rest of the window
+ // reaches other sessions.
+ // The crowd's best-ranked survivor leads whichever a- note the index
+ // ranked first - directory order must not decide the assertion.
+ expect(on.results[0]?.path.startsWith("a-")).toBe(true);
+ expect(on.results.some((r) => !r.path.startsWith("a-"))).toBe(true);
+ const entry = degradationOf(on, RETRIEVAL_DEGRADATION.sourceSessionCappedRows);
+ expect(entry?.detail).toEqual({ dropped: 4, cap: 2 });
+ } finally {
+ v.cleanup();
+ }
+});
+
+test("the per-query override alone activates the cap without a config value", async () => {
+ const v = await indexedCrowdedVault();
+ try {
+ // `cold` carries no poolMaxPerSession at all: the whole cap comes
+ // from the per-query SearchOptions field.
+ const overridden = await search(v.cold, {
+ query: CROWDED_QUERY,
+ limit: LIMIT,
+ poolMaxPerSession: 2,
+ });
+
+ expect(overridden.results.length).toBe(LIMIT);
+ expect(overridden.results[0]?.path.startsWith("a-")).toBe(true);
+ expect(overridden.results.some((r) => !r.path.startsWith("a-"))).toBe(true);
+ const entry = degradationOf(overridden, RETRIEVAL_DEGRADATION.sourceSessionCappedRows);
+ expect(entry?.detail).toEqual({ dropped: 4, cap: 2 });
+ // The same query without the override stays uncapped - the override,
+ // not the fixture, is what capped the answer. (The uncapped run
+ // still carries the pre-existing rank-cap note; the session-cap
+ // note is the one that must be absent.)
+ const plain = await search(v.cold, { query: CROWDED_QUERY, limit: LIMIT });
+ expect(degradationOf(plain, RETRIEVAL_DEGRADATION.sourceSessionCappedRows)).toBeUndefined();
+ expect(JSON.stringify(plain)).not.toBe(JSON.stringify(overridden));
+ } finally {
+ v.cleanup();
+ }
+});
+
+test("the per-query override wins over the config value when both are set", async () => {
+ const v = await indexedCrowdedVault();
+ try {
+ // Tighter than the config: 2 crowded rows survive under config cap
+ // 2, but the query's own cap 1 keeps only the first.
+ const tighter = await search(withRecall(v.cold, { poolMaxPerSession: 2 }), {
+ query: CROWDED_QUERY,
+ limit: LIMIT,
+ poolMaxPerSession: 1,
+ });
+ expect(tighter.results.map((r) => r.path)).toEqual(["a-0.md", "b.md", "c.md"]);
+ expect(degradationOf(tighter, RETRIEVAL_DEGRADATION.sourceSessionCappedRows)?.detail).toEqual({
+ dropped: 5,
+ cap: 1,
+ });
+
+ // Looser than the config: config cap 1 would keep one crowded row,
+ // but the query's own cap 3 keeps three.
+ const looser = await search(withRecall(v.cold, { poolMaxPerSession: 1 }), {
+ query: CROWDED_QUERY,
+ limit: LIMIT,
+ poolMaxPerSession: 3,
+ });
+ expect(looser.results.map((r) => r.path)).toEqual(["a-0.md", "a-1.md", "a-2.md"]);
+ expect(degradationOf(looser, RETRIEVAL_DEGRADATION.sourceSessionCappedRows)?.detail).toEqual({
+ dropped: 3,
+ cap: 3,
+ });
+ } finally {
+ v.cleanup();
+ }
+});
+
+test("an explicit per-query 0 forces the cap off over a config cap", async () => {
+ const v = await indexedCrowdedVault();
+ try {
+ const forcedOff = await search(withRecall(v.cold, { poolMaxPerSession: 2 }), {
+ query: CROWDED_QUERY,
+ limit: LIMIT,
+ poolMaxPerSession: 0,
+ });
+ const off = await search(v.cold, { query: CROWDED_QUERY, limit: LIMIT });
+
+ // The documented forced-off value: the config knob cannot reach past
+ // a per-query 0, and the answer is the default-off run's exact bytes
+ // (rank-cap trail and all - the session-cap note never appears).
+ expect(JSON.stringify(forcedOff)).toBe(JSON.stringify(off));
+ expect(degradationOf(forcedOff, RETRIEVAL_DEGRADATION.sourceSessionCappedRows)).toBeUndefined();
+ } finally {
+ v.cleanup();
+ }
+});
+
+test("a vault with no session identity ranks identically with the cap on", async () => {
+ // The module fixture holds ordinary notes only - no session_ref, no
+ // session_id - so with the cap on, every note is its own PATH group
+ // (the M2 fallback) holding a single chunk, and nothing can drop.
+ const cold = withRecall(config(), { recencyAmplitude: 0 });
+ const off = await search(cold, { query: "widget calibration", limit: LIMIT });
+ const on = await search(withRecall(cold, { poolMaxPerSession: 2 }), {
+ query: "widget calibration",
+ limit: LIMIT,
+ });
+
+ expect(JSON.stringify(on)).toBe(JSON.stringify(off));
+ expect(on.retrievalTrail).toBeUndefined();
+});
+
+test("the cap's drops trigger the one-shot re-widen when the window under-fills", async () => {
+ // Forty matching notes in ONE session: the window cannot fill (cap 2,
+ // limit 3), and the cap's own drops are the review-M3 trigger the older
+ // build lacked - the re-widen runs once at
+ // `limit * (widestGroupRows + 1)` = 3 * 31 = 93, ranks the whole
+ // corpus (40 rows), and reports the FINAL pass: 2 survived, 38
+ // dropped - the first 30-wide pass dropped 28. The answer stays 2 rows
+ // because the corpus holds one session only; the trail names that pass
+ // honestly instead of retrying forever.
+ const v = createTempVault("pool-cap-final");
+ try {
+ for (let i = 0; i < 40; i += 1) {
+ writeMd(
+ v.vault,
+ `solo-${i}.md`,
+ `---\ntitle: Solo ${i}\nsession_ref: sess-a\n---\n\n# Solo ${i}\n\n` +
+ `The widget calibration routine number ${i}.\n`,
+ );
+ }
+ const cold = withRecall(
+ makeConfig({ vault: v.vault, dbPath: v.dbPath, maxHops: 0, mmrLambda: 1 }),
+ { recencyAmplitude: 0, poolMultiplier: 20, poolMaxPerSession: 2 },
+ );
+ await indexVault(cold, {});
+
+ const out = await search(cold, { query: CROWDED_QUERY, limit: LIMIT });
+
+ // The corpus holds nothing outside the one session, so the re-widen
+ // cannot add rows - but it RANKED them: dropped 38 witnesses the
+ // 40-row final pass, never the first pass's 28.
+ expect(out.results.length).toBe(2);
+ const entry = degradationOf(out, RETRIEVAL_DEGRADATION.sourceSessionCappedRows);
+ expect(entry?.detail).toEqual({ dropped: 38, cap: 2 });
+ // Once per answer: the re-widen's second pass replaces the first
+ // pass's note, it never stacks beside it.
+ const capNotes = out.retrievalTrail?.degraded.filter(
+ (d) => d.code === RETRIEVAL_DEGRADATION.sourceSessionCappedRows,
+ );
+ expect(capNotes).toHaveLength(1);
+ } finally {
+ v.cleanup();
+ }
+});
+
+test("the re-widen actually refills the window from deeper sessions", async () => {
+ // The review-M3 repro, ranked deterministically: forty rows of one
+ // session outrank ten single-row sessions, cap 1, limit 3. The first
+ // 30-wide pass keeps one row; the re-widen ranks past the crowded
+ // session and the window fills from the sessions the cap did not
+ // exhaust. Driven through `assembleRankedResults` directly so the rank
+ // order is pinned by the fixture, not by scoring.
+ const v = createTempVault("pool-cap-refill");
+ try {
+ for (let i = 0; i < 30; i += 1) {
+ writeMd(
+ v.vault,
+ `a-${i}.md`,
+ `---\ntitle: Wide ${i}\nsession_ref: sess-a\n---\n\n# Wide ${i}\n\nalpha beta gamma ${i}.\n`,
+ );
+ }
+ for (let i = 0; i < 10; i += 1) {
+ writeMd(
+ v.vault,
+ `b-${i}.md`,
+ `---\ntitle: Deep ${i}\nsession_ref: sess-b-${i}\n---\n\n# Deep ${i}\n\nalpha beta gamma deep ${i}.\n`,
+ );
+ }
+ const base = makeConfig({
+ vault: v.vault,
+ dbPath: v.dbPath,
+ maxHops: 0,
+ mmrLambda: 1,
+ intentEnabled: false,
+ });
+ const cfg = withRecall(base, {
+ recencyAmplitude: 0,
+ poolMaxPerSession: 1,
+ });
+ await indexVault(cfg, {});
+
+ const store = await Store.open(cfg, { mode: "read" });
+ try {
+ const documents = store.listDocuments();
+ const chunkIdFor = (path: string): number => {
+ const doc = documents.get(path);
+ if (doc === undefined) throw new Error(`fixture document missing from index: ${path}`);
+ const first = store.chunksForDocument(doc.id)[0];
+ if (first === undefined) throw new Error(`fixture document has no chunk: ${path}`);
+ return first.id;
+ };
+ const paths = [...documents.keys()].toSorted();
+ const ids = paths.map(chunkIdFor);
+ const hydrated = store.hydrateChunks(ids);
+ // Every crowded row outranks every deep row: bm25 is more negative
+ // for the crowded session, which ranks first.
+ const keywordHits: KeywordHit[] = paths.map((path, at) => ({
+ chunkId: ids[at]!,
+ documentId: hydrated.get(ids[at]!)!.documentId,
+ bm25: path.startsWith("a-") ? -(5 + at / 100) : -1,
+ }));
+ const frontmatterCache = new Map();
+ const signals = collectCandidateSignals({
+ store,
+ config: cfg,
+ ids,
+ hydrated,
+ query: CROWDED_QUERY,
+ frontmatterCache,
+ temporalIntentActive: false,
+ declaredEventTimeMs: () => null,
+ });
+ const degraded: RetrievalDegradation[] = [];
+ const pool = assembleRankedResults({
+ store,
+ config: cfg,
+ opts: { query: CROWDED_QUERY, limit: LIMIT },
+ keywordHits,
+ semanticHits: [],
+ hydrated,
+ signals,
+ relationalRankedChunkIds: [],
+ weightProfile: undefined,
+ sessionFocus: null,
+ semanticEnabled: false,
+ structured: undefined,
+ frontmatterCache,
+ timeRange: null,
+ temporalIntent: null,
+ declaredEventTimeMs: () => null,
+ limit: LIMIT,
+ nowMs: Date.now(),
+ degraded,
+ });
+
+ // The crowded session keeps its one row; every deep session row is
+ // in the pool the window draws from - the re-widen reached them.
+ expect(pool.length).toBe(11);
+ // The fixture's bm25 ladder makes a-9 (last in the sorted paths)
+ // the best-ranked crowded row - the one the cap keeps.
+ expect(pool[0]?.path).toBe("a-9.md");
+ expect(pool.filter((r) => r.path.startsWith("b-"))).toHaveLength(10);
+ // The note carries the FINAL pass's numbers: the crowded session
+ // still drops 29 of its ranked rows (1 kept), now beside the ten
+ // sessions the wider pool admitted.
+ const entry = degraded.find((d) => d.code === RETRIEVAL_DEGRADATION.sourceSessionCappedRows);
+ expect(entry?.detail).toEqual({ dropped: 29, cap: 1 });
+ expect(
+ degraded.filter((d) => d.code === RETRIEVAL_DEGRADATION.sourceSessionCappedRows),
+ ).toHaveLength(1);
+ } finally {
+ await store.close();
+ }
+ } finally {
+ v.cleanup();
+ }
+});
+
+test("a pre-existing backfill under the cap notes the final pass's drops exactly once", async () => {
+ // The harder shape the once-per-answer contract claims: the backfill
+ // fires for its OWN pre-existing reason (default-scope visibility drops
+ // the private half of the session, leaving the window under-filled),
+ // the cap is re-applied over the wider 50-row pool, and the trail
+ // reports THAT pass's numbers - not the first pass's. Forty notes in
+ // one session, half `visibility: private`, cap 2, limit 3: the first
+ // (30-wide) pass sees 15 filter-passing rows and drops 13 of them to
+ // the cap, the second (50-wide) pass ranks all 40, filters to 20, and
+ // drops 18 - so `dropped: 18` is itself the witness that the window
+ // grew and the answer came from the final pass. And because the cap
+ // counts only FILTER-PASSING rows against the session's quota (the
+ // review-M4 ordering), both surviving public rows are in the answer -
+ // the older build spent quota on a private row the filters then
+ // withheld, and answered with one.
+ const v = createTempVault("pool-cap-backfill");
+ try {
+ for (let i = 0; i < 40; i += 1) {
+ const visibility = i % 2 === 1 ? "visibility: private\n" : "";
+ writeMd(
+ v.vault,
+ `solo-${i}.md`,
+ `---\ntitle: Solo ${i}\n${visibility}session_ref: sess-a\n---\n\n# Solo ${i}\n\n` +
+ `The widget calibration routine number ${i}.\n`,
+ );
+ }
+ const cold = withRecall(
+ makeConfig({ vault: v.vault, dbPath: v.dbPath, maxHops: 0, mmrLambda: 1 }),
+ { recencyAmplitude: 0, poolMultiplier: 20, poolMaxPerSession: 2 },
+ );
+ await indexVault(cold, {});
+
+ const out = await search(cold, { query: CROWDED_QUERY, limit: LIMIT });
+
+ // The note names the FINAL pass: 18 dropped over the 50-wide pool's
+ // 20 filter-passing rows, never the first pass's 13. The two
+ // survivors are the two best-ranked PUBLIC rows (solo-1 is private
+ // and filters out before the cap ever sees it).
+ expect(out.results.map((r) => r.path)).toEqual(["solo-0.md", "solo-10.md"]);
+ const entry = degradationOf(out, RETRIEVAL_DEGRADATION.sourceSessionCappedRows);
+ expect(entry?.detail).toEqual({ dropped: 18, cap: 2 });
+ // Once per answer, even when the assemble closure ran twice.
+ const capNotes = out.retrievalTrail?.degraded.filter(
+ (d) => d.code === RETRIEVAL_DEGRADATION.sourceSessionCappedRows,
+ );
+ expect(capNotes).toHaveLength(1);
+ } finally {
+ v.cleanup();
+ }
+});
+
+test("the cap on joins the widening so a cross-encoder query keeps its topK pool", async () => {
+ // Thirty rows of one session ranked ahead of ten of another. With the
+ // cap active and the cross-encoder asking for a 40-wide pool, the
+ // widened rankLimit ranks past the crowded session: the second
+ // session's deep rows are in the pool the reader step draws from. A
+ // composition that lost the topK term would rank only the crowded
+ // session's top 30, and the cap would leave nothing else. Driven
+ // through `assembleRankedResults` directly - the cross-encoder call
+ // itself runs after this stage, so no endpoint is involved.
+ const v = createTempVault("pool-cap-widen");
+ try {
+ for (let i = 0; i < 30; i += 1) {
+ writeMd(
+ v.vault,
+ `a-${i}.md`,
+ `---\ntitle: Wide ${i}\nsession_ref: sess-a\n---\n\n# Wide ${i}\n\nalpha beta gamma ${i}.\n`,
+ );
+ }
+ for (let i = 0; i < 10; i += 1) {
+ writeMd(
+ v.vault,
+ `b-${i}.md`,
+ `---\ntitle: Deep ${i}\nsession_ref: sess-b\n---\n\n# Deep ${i}\n\nalpha beta gamma deep ${i}.\n`,
+ );
+ }
+ const base = makeConfig({
+ vault: v.vault,
+ dbPath: v.dbPath,
+ maxHops: 0,
+ mmrLambda: 1,
+ intentEnabled: false,
+ });
+ const cfg = withRecall(base, {
+ recencyAmplitude: 0,
+ poolMaxPerSession: 2,
+ });
+ const rerankCfg = Object.freeze({
+ ...cfg,
+ rerank: Object.freeze({ ...cfg.rerank, enabled: true, topK: 40 }),
+ });
+ await indexVault(rerankCfg, {});
+
+ const store = await Store.open(rerankCfg, { mode: "read" });
+ try {
+ const documents = store.listDocuments();
+ const chunkIdFor = (path: string): number => {
+ const doc = documents.get(path);
+ if (doc === undefined) throw new Error(`fixture document missing from index: ${path}`);
+ const first = store.chunksForDocument(doc.id)[0];
+ if (first === undefined) throw new Error(`fixture document has no chunk: ${path}`);
+ return first.id;
+ };
+ const paths = [...documents.keys()].toSorted();
+ const ids = paths.map(chunkIdFor);
+ const hydrated = store.hydrateChunks(ids);
+ // Every crowded row outranks every deep row: bm25 is more negative
+ // for the crowded session, which ranks first.
+ const keywordHits: KeywordHit[] = paths.map((path, at) => ({
+ chunkId: ids[at]!,
+ documentId: hydrated.get(ids[at]!)!.documentId,
+ bm25: path.startsWith("a-") ? -(5 + at / 100) : -1,
+ }));
+ const frontmatterCache = new Map();
+ const signals = collectCandidateSignals({
+ store,
+ config: rerankCfg,
+ ids,
+ hydrated,
+ query: CROWDED_QUERY,
+ frontmatterCache,
+ temporalIntentActive: false,
+ declaredEventTimeMs: () => null,
+ });
+ const pool = assembleRankedResults({
+ store,
+ config: rerankCfg,
+ opts: { query: CROWDED_QUERY, limit: LIMIT },
+ keywordHits,
+ semanticHits: [],
+ hydrated,
+ signals,
+ relationalRankedChunkIds: [],
+ weightProfile: undefined,
+ sessionFocus: null,
+ semanticEnabled: false,
+ structured: undefined,
+ frontmatterCache,
+ timeRange: null,
+ temporalIntent: null,
+ declaredEventTimeMs: () => null,
+ limit: LIMIT,
+ nowMs: Date.now(),
+ degraded: [],
+ });
+
+ expect(pool.length).toBe(4); // the cap keeps two rows per session
+ // The widen witness: the deep session's rows were RANKED at all,
+ // which only the topK term of the widened composition allows.
+ expect(pool.some((r) => r.path.startsWith("b-"))).toBe(true);
+ } finally {
+ await store.close();
+ }
+ } finally {
+ v.cleanup();
+ }
+});
+
+test("a bench pin caps frontmatter-less bench session notes (path fallback)", async () => {
+ // The review-M2 repro on the bench this knob was added to measure:
+ // LongMemEval-style session notes carry NO frontmatter (the converter
+ // writes plain bodies - `sessionNoteBody`), and one long session note
+ // splits into several chunks that crowd the pool together. Grouped by
+ // frontmatter alone, the cap changed nothing here, byte for byte; with
+ // the path fallback every chunk of one note is one group, so the pinned
+ // cap drops real rows. The knob NAME and its value semantics ride the
+ // exported pin parser and the resolved search config - the two seams
+ // `--pin '{"recall":{"poolMaxPerSession":N}}'` flows through.
+ const v = createTempVault("pool-cap-bench-pin");
+ try {
+ for (const session of [1, 2, 3]) {
+ const body = Array.from(
+ { length: 300 },
+ (_, i) =>
+ `Turn ${i}: the widget calibration routine number ${i % 40} appears in session ${session} ` +
+ `near marker ${i} of note ${session}, with enough surrounding words to force the chunker ` +
+ `to split this session note into several chunks.`,
+ ).join("\n");
+ writeMd(
+ v.vault,
+ `sessions/q1/session-${session}.md`,
+ `# Session ${session} (question q1)\n\n${body}\n`,
+ );
+ }
+ const base = withRecall(
+ makeConfig({ vault: v.vault, dbPath: v.dbPath, maxHops: 0, mmrLambda: 1 }),
+ { recencyAmplitude: 0 },
+ );
+ await indexVault(base, {});
+
+ const pin = parseBenchPinnedKnobs('{"recall":{"poolMaxPerSession":1}}');
+ expect(pin.recall?.poolMaxPerSession).toBe(1);
+ const pinned = withRecall(base, { poolMaxPerSession: pin.recall?.poolMaxPerSession });
+
+ const uncapped = await search(base, { query: "widget calibration", limit: LIMIT });
+ const capped = await search(pinned, { query: "widget calibration", limit: LIMIT });
+
+ // The uncapped pool is the crowding itself: one frontmatter-less
+ // session note fills the window with its own chunks.
+ expect(uncapped.total).toBeGreaterThanOrEqual(LIMIT);
+ const crowdedPath = uncapped.results[0]?.path;
+ expect(uncapped.results.filter((r) => r.path === crowdedPath).length).toBeGreaterThan(1);
+
+ // NON-ZERO drops: the pin measurably narrows the pool over notes
+ // that carry no session frontmatter at all.
+ const entry = degradationOf(capped, RETRIEVAL_DEGRADATION.sourceSessionCappedRows);
+ expect(entry?.detail?.dropped).toBeGreaterThan(0);
+ // Cap 1 per note: no session note contributes two rows to the answer
+ // any more, and the answer is not the uncapped bytes.
+ const byPath = new Map<string, number>();
+ for (const r of capped.results) byPath.set(r.path, (byPath.get(r.path) ?? 0) + 1);
+ expect([...byPath.values()].every((n) => n === 1)).toBe(true);
+ expect(JSON.stringify(capped)).not.toBe(JSON.stringify(uncapped));
+ } finally {
+ v.cleanup();
+ }
+});
+
+test("a fractional or negative per-query override is refused by name", async () => {
+ // The per-query override used to bypass the config validation: 1.5
+ // turned the cap on with a fractional comparison (seen >= 1.5 kept two
+ // rows), NaN read as off, a negative as drop-everything. The search
+ // entry refuses all three through the same named INVALID_INPUT path
+ // the config key is judged by.
+ const v = await indexedCrowdedVault();
+ try {
+ await expect(
+ search(v.cold, { query: CROWDED_QUERY, limit: LIMIT, poolMaxPerSession: 1.5 }),
+ ).rejects.toThrow(/poolMaxPerSession/);
+ await expect(
+ search(v.cold, { query: CROWDED_QUERY, limit: LIMIT, poolMaxPerSession: Number.NaN }),
+ ).rejects.toThrow(/poolMaxPerSession/);
+ await expect(
+ search(v.cold, { query: CROWDED_QUERY, limit: LIMIT, poolMaxPerSession: -2 }),
+ ).rejects.toThrow(/poolMaxPerSession/);
+ } finally {
+ v.cleanup();
+ }
+});
+
+test("a cap at or above the pool width it would judge is treated as off", async () => {
+ // The review-L4 upper bound: a huge cap turned the phase on, read
+ // frontmatter for every row, and dropped nothing. At or above the
+ // resolved pool width the cap cannot drop a row, so it is off - the
+ // answer is the default-off run's exact bytes and no session-cap note
+ // appears. The configured value still folds into the fingerprint
+ // (pinned in config.test.ts), so crossing this boundary can never
+ // serve a stale cached row.
+ const v = await indexedCrowdedVault();
+ try {
+ const huge = await search(withRecall(v.cold, { poolMaxPerSession: 10_000 }), {
+ query: CROWDED_QUERY,
+ limit: LIMIT,
+ });
+ const off = await search(v.cold, { query: CROWDED_QUERY, limit: LIMIT });
+
+ expect(JSON.stringify(huge)).toBe(JSON.stringify(off));
+ expect(degradationOf(huge, RETRIEVAL_DEGRADATION.sourceSessionCappedRows)).toBeUndefined();
+
+ // The boundary is the width the cap would judge when on - for a
+ // plain limit-3 query, the widened 30. Below it the phase still runs
+ // and bites (the crowded session holds 6 rows, so cap 5 drops one);
+ // at or above it - 30 exactly, one past it, and far past it - the
+ // answer is the off run's bytes.
+ const justUnder = await search(withRecall(v.cold, { poolMaxPerSession: 5 }), {
+ query: CROWDED_QUERY,
+ limit: LIMIT,
+ });
+ expect(degradationOf(justUnder, RETRIEVAL_DEGRADATION.sourceSessionCappedRows)?.detail).toEqual(
+ { dropped: 1, cap: 5 },
+ );
+ const atBoundary = await search(withRecall(v.cold, { poolMaxPerSession: 30 }), {
+ query: CROWDED_QUERY,
+ limit: LIMIT,
+ });
+ expect(JSON.stringify(atBoundary)).toBe(JSON.stringify(off));
+ const onePast = await search(withRecall(v.cold, { poolMaxPerSession: 31 }), {
+ query: CROWDED_QUERY,
+ limit: LIMIT,
+ });
+ expect(JSON.stringify(onePast)).toBe(JSON.stringify(off));
+ const farPast = await search(withRecall(v.cold, { poolMaxPerSession: 120 }), {
+ query: CROWDED_QUERY,
+ limit: LIMIT,
+ });
+ expect(JSON.stringify(farPast)).toBe(JSON.stringify(off));
+ } finally {
+ v.cleanup();
+ }
+});
diff --git a/tests/core/search/retrieval-trail.test.ts b/tests/core/search/retrieval-trail.test.ts
index c8687d2f..f2d9ed8d 100644
--- a/tests/core/search/retrieval-trail.test.ts
+++ b/tests/core/search/retrieval-trail.test.ts
@@ -158,6 +158,59 @@ test("a pool the cap really did cut still names the code and the cap", async ()
// ─── a degraded lane names its code ──────────────────────────────────────────
+test("a session cap that drops rows names them beside the floor's drops", async () => {
+ // Four hot notes in one source session, two weak notes in another: a
+ // floor between the clusters removes the weak session, and the cap
+ // bounds the crowded one - both codes ride the same trail.
+ const v = createTempVault("trail-session-cap");
+ cleanups.push(v.cleanup);
+ for (let i = 0; i < 4; i += 1) {
+ writeMd(
+ v.vault,
+ `a-${i}.md`,
+ "---\ntitle: Hot\nsession_ref: sess-a\n---\n\n# Hot\n\n" +
+ `fox fox fox fox the quick brown fox jumps over note ${i}.\n`,
+ );
+ }
+ for (const b of ["b-0", "b-1"]) {
+ writeMd(
+ v.vault,
+ `${b}.md`,
+ "---\ntitle: Weak\nsession_ref: sess-b\n---\n\n# Weak\n\n" +
+ `A note mostly about cats, with one fox mention (${b}).\n`,
+ );
+ }
+ const cfg = makeConfig({ vault: v.vault, dbPath: v.dbPath, maxHops: 0, mmrLambda: 1 });
+ const cappedCfg = Object.freeze({
+ ...cfg,
+ recall: Object.freeze({ ...cfg.recall, poolMaxPerSession: 1 }),
+ });
+ await indexVault(cappedCfg, {});
+
+ // The score probe runs with the cap OFF: it measures the raw clusters
+ // the floor needs, before any session bound applies.
+ const unfiltered = await search(cfg, { query: "fox", limit: 10 });
+ const hotScores = unfiltered.results.filter((r) => r.path.startsWith("a-")).map((r) => r.score);
+ const weakScores = unfiltered.results.filter((r) => r.path.startsWith("b-")).map((r) => r.score);
+ expect(hotScores.length).toBe(4);
+ expect(weakScores.length).toBe(2);
+ // The floor sits between the clusters: every weak note falls, every
+ // hot note stays - then the cap bounds the hot session to one row.
+ const floor = (Math.min(...hotScores) + Math.max(...weakScores)) / 2;
+
+ const out = await search(cappedCfg, { query: "fox", limit: 10, threshold: floor });
+
+ const capped = out.retrievalTrail?.degraded.find(
+ (d) => d.code === RETRIEVAL_DEGRADATION.sourceSessionCappedRows,
+ );
+ expect(capped?.detail).toEqual({ dropped: 3, cap: 1 });
+ const floored = out.retrievalTrail?.degraded.find(
+ (d) => d.code === RETRIEVAL_DEGRADATION.relevanceFloorDroppedRows,
+ );
+ expect(floored?.detail).toEqual({ dropped: 2 });
+ expect(out.results.map((r) => r.path)).toEqual(["a-0.md"]);
+});
+
test("a trigram lane fault names its code beside the sentence it already pushed", async () => {
const { vault, dbPath } = await indexedVault("trail-trigram");
const cfg = makeConfig({
diff --git a/tests/core/search/session-pool-cap.test.ts b/tests/core/search/session-pool-cap.test.ts
new file mode 100644
index 00000000..ea29071d
--- /dev/null
+++ b/tests/core/search/session-pool-cap.test.ts
@@ -0,0 +1,310 @@
+/**
+ * The per-source-session pool cap (t_bb6ce095): a pure phase over ranked
+ * rows that bounds how many rows one group may contribute to the
+ * filtered pool the caller's window is cut from.
+ *
+ * A row's group key is its SOURCE import session when the note states
+ * one - `session_ref` frontmatter on imported signal notes, `session_id`
+ * on handoff notes - and the row's own PATH otherwise. The fallback is
+ * the review fix (M2): the crowding the cap was built to measure comes
+ * from material that carries no session frontmatter at all (bench
+ * session notes, and the several chunks of one long note), so grouping
+ * by frontmatter alone capped nothing there. Identity is read through
+ * the per-call frontmatter cache the assemble stage already builds, so
+ * the cap adds no new read shape to the pipeline.
+ */
+
+import { afterEach, expect, test } from "bun:test";
+
+import {
+ applySessionPoolCap,
+ resolveSessionPoolCap,
+} from "../../../src/core/search/pipeline/session-pool-cap.ts";
+import { SearchError } from "../../../src/core/search/types.ts";
+import { type FrontmatterCache } from "../../../src/core/search/result-filters.ts";
+import type { BrainSearchResult } from "../../../src/core/search/types.ts";
+import { createTempVault, writeMd } from "../../helpers/search-fixtures.ts";
+
+let nextId = 1;
+function res(path: string, score: number): BrainSearchResult {
+ const id = nextId++;
+ return Object.freeze({
+ documentId: id,
+ chunkId: id,
+ path,
+ title: `Doc ${id}`,
+ content: `body ${id}`,
+ startLine: 1,
+ endLine: 1,
+ score,
+ keywordScore: score,
+ semanticScore: 0,
+ linkBoost: 0,
+ recencyBoost: 0,
+ searchType: "keyword" as const,
+ reasons: Object.freeze([`fts5_bm25: ${score.toFixed(3)}`]),
+ });
+}
+
+let vault = "";
+let cleanup: () => void = () => {};
+
+/** A vault exercising every identity side the cap distinguishes. */
+function seedVault(): string {
+ const v = createTempVault("session-pool-cap");
+ vault = v.vault;
+ cleanup = v.cleanup;
+ writeMd(vault, "a-1.md", "---\ntitle: A1\nsession_ref: sess-a\n---\n\nbody\n");
+ writeMd(vault, "a-2.md", "---\ntitle: A2\nsession_ref: sess-a\n---\n\nbody\n");
+ writeMd(vault, "a-3.md", "---\ntitle: A3\nsession_ref: sess-a\n---\n\nbody\n");
+ writeMd(vault, "b-1.md", "---\ntitle: B1\nsession_ref: sess-b\n---\n\nbody\n");
+ writeMd(vault, "b-2.md", "---\ntitle: B2\nsession_ref: sess-b\n---\n\nbody\n");
+ writeMd(vault, "h-1.md", "---\ntitle: H1\nsession_id: handoff-1\n---\n\nbody\n");
+ writeMd(vault, "h-2.md", "---\ntitle: H2\nsession_id: handoff-1\n---\n\nbody\n");
+ writeMd(vault, "plain-1.md", "---\ntitle: P1\n---\n\nbody\n");
+ writeMd(vault, "plain-2.md", "---\ntitle: P2\n---\n\nbody\n");
+ // An empty string and a non-string are both ABSENT identity: only a
+ // non-empty string names a session.
+ writeMd(vault, "empty-ref.md", '---\ntitle: E\nsession_ref: ""\n---\n\nbody\n');
+ writeMd(vault, "empty-ref-2.md", '---\ntitle: E2\nsession_ref: ""\n---\n\nbody\n');
+ writeMd(vault, "numeric-ref.md", "---\ntitle: N\nsession_ref: 42\n---\n\nbody\n");
+ return vault;
+}
+
+afterEach(() => cleanup());
+
+test("ranked order is preserved and only the first rows per session survive", () => {
+ const v = seedVault();
+ const input = [
+ res("a-1.md", 0.9),
+ res("a-2.md", 0.8),
+ res("b-1.md", 0.7),
+ res("a-3.md", 0.6),
+ res("plain-1.md", 0.5),
+ ];
+
+ const out = applySessionPoolCap(input, {
+ vault: v,
+ capPerSession: 2,
+ frontmatterCache: new Map(),
+ });
+
+ expect(out.results.map((r) => r.path)).toEqual(["a-1.md", "a-2.md", "b-1.md", "plain-1.md"]);
+ expect(out.dropped).toBe(1);
+});
+
+test("rows carrying only session_id group by it", () => {
+ const v = seedVault();
+ const input = [res("h-1.md", 0.9), res("h-2.md", 0.8), res("plain-1.md", 0.7)];
+
+ const out = applySessionPoolCap(input, {
+ vault: v,
+ capPerSession: 1,
+ frontmatterCache: new Map(),
+ });
+
+ expect(out.results.map((r) => r.path)).toEqual(["h-1.md", "plain-1.md"]);
+ expect(out.dropped).toBe(1);
+});
+
+test("session_ref wins over session_id when a row carries both", () => {
+ const v = seedVault();
+ writeMd(v, "both.md", "---\ntitle: B\nsession_ref: sess-a\nsession_id: handoff-1\n---\n\nbody\n");
+ const input = [res("both.md", 0.9), res("a-1.md", 0.8), res("h-1.md", 0.7)];
+
+ const out = applySessionPoolCap(input, {
+ vault: v,
+ capPerSession: 1,
+ frontmatterCache: new Map(),
+ });
+
+ // `both` and `a-1` share sess-a, so the second drops; the session_id
+ // row is a different session and survives.
+ expect(out.results.map((r) => r.path)).toEqual(["both.md", "h-1.md"]);
+ expect(out.dropped).toBe(1);
+});
+
+test("rows without frontmatter identity group by path, so chunks of one note share a group", () => {
+ const v = seedVault();
+ // Two chunks of one frontmatter-less note (distinct chunk ids, one
+ // path) beside a chunk of another: the path fallback is the group, so
+ // the cap keeps one chunk per note.
+ const first = res("plain-1.md", 0.9);
+ const third = res("plain-2.md", 0.7);
+ const input = [first, res("plain-1.md", 0.8), third];
+
+ const out = applySessionPoolCap(input, {
+ vault: v,
+ capPerSession: 1,
+ frontmatterCache: new Map(),
+ });
+
+ expect(out.results).toEqual([first, third]);
+ expect(out.dropped).toBe(1);
+});
+
+test("distinct frontmatter-less notes are distinct path groups", () => {
+ const v = seedVault();
+ const input = [res("plain-1.md", 0.9), res("plain-2.md", 0.8), res("plain-3.md", 0.7)];
+
+ const out = applySessionPoolCap(input, {
+ vault: v,
+ capPerSession: 1,
+ frontmatterCache: new Map(),
+ });
+
+ expect(out.results.map((r) => r.path)).toEqual(["plain-1.md", "plain-2.md", "plain-3.md"]);
+ expect(out.dropped).toBe(0);
+});
+
+test("a session value that begins with the path prefix stays in its own key space", () => {
+ const v = seedVault();
+ // The session value is literally the fallback key of another note: the
+ // two kinds must never fuse regardless of the value, or this session's
+ // quota would be spent on the unrelated note's chunks.
+ writeMd(v, "trap.md", '---\ntitle: T\nsession_ref: "path:plain-1.md"\n---\n\nbody\n');
+ const firstChunk = res("plain-1.md", 0.8);
+ const input = [res("trap.md", 0.9), firstChunk, res("plain-1.md", 0.7)];
+
+ const out = applySessionPoolCap(input, {
+ vault: v,
+ capPerSession: 1,
+ frontmatterCache: new Map(),
+ });
+
+ // `trap` is its own session group; the two plain-1 chunks are the
+ // note's own path group - so the second chunk drops, not both.
+ expect(out.results.map((r) => r.path)).toEqual(["trap.md", "plain-1.md"]);
+ expect(out.results[1]).toBe(firstChunk);
+ expect(out.dropped).toBe(1);
+});
+
+test("an unreadable file's rows group by its path too", () => {
+ const v = seedVault();
+ // `ghost.md` is not on disk, so its frontmatter read is unreadable -
+ // but the path is still a real identity, and the two ghost chunks are
+ // one group for the same reason chunks of one readable note are.
+ const first = res("ghost.md", 0.9);
+ const third = res("plain-1.md", 0.7);
+ const input = [first, res("ghost.md", 0.8), third];
+
+ const out = applySessionPoolCap(input, {
+ vault: v,
+ capPerSession: 1,
+ frontmatterCache: new Map(),
+ });
+
+ expect(out.results).toEqual([first, third]);
+ expect(out.dropped).toBe(1);
+});
+
+test("an empty or non-string frontmatter value falls back to the path group", () => {
+ const v = seedVault();
+ // The empty-identity rows sit BESIDE capped rows: each names no
+ // session, so each is its own path group and survives past the cap -
+ // while the real sess-a rows are capped to one. A non-string value is
+ // absent identity the same way.
+ const input = [
+ res("empty-ref.md", 0.9),
+ res("empty-ref-2.md", 0.85),
+ res("a-1.md", 0.8),
+ res("a-2.md", 0.7),
+ res("numeric-ref.md", 0.6),
+ ];
+
+ const out = applySessionPoolCap(input, {
+ vault: v,
+ capPerSession: 1,
+ frontmatterCache: new Map(),
+ });
+
+ expect(out.results.map((r) => r.path)).toEqual([
+ "empty-ref.md",
+ "empty-ref-2.md",
+ "a-1.md",
+ "numeric-ref.md",
+ ]);
+ expect(out.dropped).toBe(1);
+});
+
+test("the drop count sums across sessions", () => {
+ const v = seedVault();
+ const input = [
+ res("a-1.md", 0.9),
+ res("a-2.md", 0.8),
+ res("a-3.md", 0.7),
+ res("b-1.md", 0.6),
+ res("b-2.md", 0.5),
+ ];
+
+ const out = applySessionPoolCap(input, {
+ vault: v,
+ capPerSession: 1,
+ frontmatterCache: new Map(),
+ });
+
+ expect(out.results.map((r) => r.path)).toEqual(["a-1.md", "b-1.md"]);
+ expect(out.dropped).toBe(3);
+});
+
+test("the widest group's occupancy is reported for the re-widen contract", () => {
+ const v = seedVault();
+ // Three rows in one session beside a lone path-grouped row: the width
+ // the M3 re-widen needs is computed from the heaviest group the pass
+ // observed, dropped-from or not.
+ const out = applySessionPoolCap(
+ [res("a-1.md", 0.9), res("a-2.md", 0.8), res("a-3.md", 0.7), res("plain-1.md", 0.6)],
+ { vault: v, capPerSession: 2, frontmatterCache: new Map() },
+ );
+ expect(out.widestGroupRows).toBe(3);
+
+ const uncrowded = applySessionPoolCap([res("a-1.md", 0.9), res("b-1.md", 0.8)], {
+ vault: v,
+ capPerSession: 2,
+ frontmatterCache: new Map(),
+ });
+ expect(uncrowded.widestGroupRows).toBe(1);
+});
+
+test("a fractional, negative or non-finite cap value is refused by name", () => {
+ // The per-query override used to bypass the config validation, so 1.5
+ // turned the cap on with a fractional comparison and NaN read as off.
+ // The same named refusal the config key gets, at the read site.
+ expect(() => resolveSessionPoolCap(1.5)).toThrow(SearchError);
+ expect(() => resolveSessionPoolCap(1.5)).toThrow(/poolMaxPerSession/);
+ expect(() => resolveSessionPoolCap(-1)).toThrow(/poolMaxPerSession.*>= 0/);
+ expect(() => resolveSessionPoolCap(Number.NaN)).toThrow(/poolMaxPerSession.*finite/);
+ expect(() => resolveSessionPoolCap(Number.POSITIVE_INFINITY)).toThrow(/poolMaxPerSession/);
+ // The off value and a positive integer stay legal.
+ expect(resolveSessionPoolCap(0)).toBe(0);
+ expect(resolveSessionPoolCap(2)).toBe(2);
+});
+
+test("the phase is pure: same inputs, same outputs, reads only through the cache", () => {
+ const v = seedVault();
+ const input = [res("a-1.md", 0.9), res("a-2.md", 0.8), res("b-1.md", 0.7), res("a-3.md", 0.6)];
+ const cache: FrontmatterCache = new Map();
+
+ const first = applySessionPoolCap(input, { vault: v, capPerSession: 2, frontmatterCache: cache });
+ const warmed = applySessionPoolCap(input, {
+ vault: v,
+ capPerSession: 2,
+ frontmatterCache: cache,
+ });
+ const fresh = applySessionPoolCap(input, {
+ vault: v,
+ capPerSession: 2,
+ frontmatterCache: new Map(),
+ });
+
+ // Survivors are the input rows themselves, in order - not copies.
+ expect(first.results[0]).toBe(input[0]);
+ expect(first.results[1]).toBe(input[1]);
+ expect(first.results.map((r) => r.path)).toEqual(["a-1.md", "a-2.md", "b-1.md"]);
+ expect(first.dropped).toBe(1);
+ // A warm cache answers identically, and a cold cache reaches the same
+ // rows: the only cache effect is the read-through fill.
+ expect(warmed).toEqual(first);
+ expect(fresh).toEqual(first);
+ expect(cache.get("a-1.md")?.meta["session_ref"]).toBe("sess-a");
+});
diff --git a/tests/core/surface/skill-attach-decision.test.ts b/tests/core/surface/skill-attach-decision.test.ts
index 03fa0268..a6127adf 100644
--- a/tests/core/surface/skill-attach-decision.test.ts
+++ b/tests/core/surface/skill-attach-decision.test.ts
@@ -12,7 +12,11 @@ import {
appendContinuityRecord,
listContinuityRecords,
} from "../../../src/core/brain/continuity/store.ts";
-import { joinSkillInvocationsToOffers } from "../../../src/core/brain/skill-usage.ts";
+import {
+ deriveSkillUsage,
+ joinSkillInvocationsToOffers,
+ skillUsageRankingWeights,
+} from "../../../src/core/brain/skill-usage.ts";
import {
DecisionProviderError,
DECISION_MODEL_USES,
@@ -566,3 +570,105 @@ test("the skill_invoked join and the report work over enforced offers", async ()
baseline().items.some((i) => i.name === "release-notes") ? 1 : 0,
);
});
+
+// --- usage-ordered coherence (t_5d1ec8a8): one map across both modes ---
+
+/** release-cut invoked through 2026-06-03; changelog-writer once, in 2020. */
+function writeDailyUsageRecords(): void {
+ for (let i = 1; i <= 5; i++) {
+ appendContinuityRecord(vault, {
+ kind: "skill_invoked",
+ createdAt: new Date(Date.parse("2026-06-03T10:00:00Z") - i * 3_600_000).toISOString(),
+ sourceRefs: [{ id: `sess:release-cut:${i}` }],
+ payload: { skill: "release-cut", agent: "claude", tool: "get_skill" },
+ });
+ }
+ appendContinuityRecord(vault, {
+ kind: "skill_invoked",
+ createdAt: "2020-01-01T00:00:00Z",
+ sourceRefs: [{ id: "sess:changelog-writer:1" }],
+ payload: { skill: "changelog-writer", agent: "claude", tool: "get_skill" },
+ });
+}
+
+function pinnedUsageMap(): ReadonlyMap<string, number> {
+ // nowMs is pinned with the records: the ranking weights - and every offer
+ // id derived through them - are a function of exactly these inputs. The
+ // builder is the one the attach tool wires, so this fixture exercises the
+ // shipped weight, not the decay weight deriveSkillUsage reports.
+ return skillUsageRankingWeights(
+ deriveSkillUsage(vault, { nowMs: Date.parse("2026-06-04T00:00:00Z") }),
+ new Set(skills.map((s) => s.name)),
+ { nowMs: Date.parse("2026-06-04T00:00:00Z") },
+ );
+}
+
+test("one usage map drives the baseline, the shadow record and the fallback", async () => {
+ writeDailyUsageRecords();
+ const usageWeight = pinnedUsageMap();
+ const plain = buildSkillAttachment({ query: QUERY, skills });
+ const deterministic = buildSkillAttachment({ query: QUERY, skills, usageWeight });
+ // Daily use reorders the near-tie: the lexically cooler release-cut
+ // (5.67 vs 8.06 here) overtakes the offer under its 1.5x ceiling.
+ expect(deterministic.items.map((i) => i.name)).not.toEqual(plain.items.map((i) => i.name));
+ expect(deterministic.items[0]!.name).toBe("release-cut");
+
+ // Shadow: the returned block is the usage-ordered baseline and the final
+ // stage record reports exactly what deterministic mode would have offered.
+ const shadowProvider = new ScriptedProvider(
+ preferring("release-notes", { "release-notes": 0.9 }),
+ );
+ const shadow = await buildSkillAttachmentWithDecision({
+ query: QUERY,
+ skills,
+ usageWeight,
+ config: config("shadow"),
+ provider: shadowProvider,
+ });
+ const { decisionModel: shadowField, ...shadowAttachment } = shadow;
+ expect(JSON.stringify(shadowAttachment)).toBe(JSON.stringify(deterministic));
+ expect(shadowField).toEqual({ mode: "shadow", applied: false, model: "fake-model-1.2" });
+ const shadowRecord = skillRecords().find((r) => r.payload["final"] === true)!;
+ expect(shadowRecord.payload["deterministic_offered"]).toEqual(
+ deterministic.items.map((i) => i.name),
+ );
+ expect(shadowRecord.payload["deterministic_offer_id"]).toBe(deterministic.offerId);
+
+ // Enforce with a degrade: the fallback offer is the same usage-ordered
+ // baseline, byte for byte.
+ const degradedProvider = new ScriptedProvider(
+ preferring("release-notes", {}),
+ new Map([[0, "http_529" as DecisionDegradeReason]]),
+ );
+ const degraded = await buildSkillAttachmentWithDecision({
+ query: QUERY,
+ skills,
+ usageWeight,
+ config: config("enforce"),
+ provider: degradedProvider,
+ });
+ const { decisionModel, ...attachment } = degraded;
+ expect(attachment).toEqual(deterministic);
+ expect(decisionModel).toMatchObject({ applied: false, degraded: "http_529" });
+});
+
+test("an empty usage map leaves the decision path byte-identical to no map", async () => {
+ const without = new ScriptedProvider(preferring("release-notes", { "release-notes": 0.9 }));
+ const plain = await buildSkillAttachmentWithDecision({
+ query: QUERY,
+ skills,
+ config: config("shadow"),
+ provider: without,
+ });
+ const inertProvider = new ScriptedProvider(preferring("release-notes", { "release-notes": 0.9 }));
+ const inert = await buildSkillAttachmentWithDecision({
+ query: QUERY,
+ skills,
+ usageWeight: new Map(),
+ config: config("shadow"),
+ provider: inertProvider,
+ });
+ const { decisionModel: _plainField, ...plainAttachment } = plain;
+ const { decisionModel: _inertField, ...inertAttachment } = inert;
+ expect(JSON.stringify(inertAttachment)).toBe(JSON.stringify(plainAttachment));
+});
diff --git a/tests/core/surface/skill-attach.test.ts b/tests/core/surface/skill-attach.test.ts
index 63220733..fcfa743b 100644
--- a/tests/core/surface/skill-attach.test.ts
+++ b/tests/core/surface/skill-attach.test.ts
@@ -1,6 +1,10 @@
import { test, expect } from "bun:test";
-import { buildSkillAttachment } from "../../../src/core/surface/skill-attach.ts";
+import {
+ buildSkillAttachment,
+ rankSkillCandidates,
+ SKILL_USAGE_ORDERING_MAX_BOOST,
+} from "../../../src/core/surface/skill-attach.ts";
import type { SkillEntry } from "../../../src/core/surface/skills.ts";
function entry(name: string, description: string, triggers = ""): SkillEntry {
@@ -88,3 +92,121 @@ test("the block is deterministic and headed", () => {
expect(a.block).toBe(b.block);
expect(a.block.startsWith("## Relevant skills")).toBe(true);
});
+
+// --- usage-ordered ranking (t_5d1ec8a8), gated on a usageWeight input ---
+
+const ORDERING_QUERY = "cut the release notes and publish";
+const ORDERING_SKILLS = [
+ entry(
+ "release-one-off",
+ "Cut a software release: bump the version, tag, publish and write notes.",
+ ),
+ entry("release-daily", "Cut a software release: bump the version, tag and publish."),
+ entry("gadget-a", "Repair the workshop gadget."),
+ entry("gadget-b", "Repair the workshop gadget."),
+ entry("gadget-c", "Repair the workshop gadget."),
+ entry("gadget-d", "Repair the workshop gadget."),
+];
+
+const DAILY_HEAVY_USAGE = new Map([
+ ["release-daily", 1],
+ ["release-one-off", 0.05],
+]);
+
+function namesOf(items: ReadonlyArray<{ name: string }>): string[] {
+ return items.map((i) => i.name);
+}
+
+test("the usage boost is capped at one and a half times the lexical score", () => {
+ expect(SKILL_USAGE_ORDERING_MAX_BOOST).toBe(0.5);
+});
+
+test("with no usage map the order stays the scorer's (off proof)", () => {
+ const attachment = buildSkillAttachment({ query: ORDERING_QUERY, skills: ORDERING_SKILLS });
+ // Frozen fixture of today's output: the one-off is lexically hotter, the
+ // corpus-common gadget helpers never pass the discriminating-term floor.
+ expect(namesOf(attachment.items)).toEqual(["release-one-off", "release-daily"]);
+ const ranked = rankSkillCandidates({ query: ORDERING_QUERY, skills: ORDERING_SKILLS }, 10);
+ const scores = ranked.map((i) => i.score);
+ expect(scores).toEqual(scores.toSorted((a, b) => b - a));
+});
+
+test("a daily-used skill outranks a lexically hotter one-off under the composite", () => {
+ const ranked = rankSkillCandidates(
+ { query: ORDERING_QUERY, skills: ORDERING_SKILLS, usageWeight: DAILY_HEAVY_USAGE },
+ 10,
+ );
+ expect(namesOf(ranked)).toEqual(["release-daily", "release-one-off"]);
+});
+
+test("the returned score stays the lexical score", () => {
+ const plain = rankSkillCandidates({ query: ORDERING_QUERY, skills: ORDERING_SKILLS }, 10);
+ const ordered = rankSkillCandidates(
+ { query: ORDERING_QUERY, skills: ORDERING_SKILLS, usageWeight: DAILY_HEAVY_USAGE },
+ 10,
+ );
+ const plainByName = new Map(plain.map((i) => [i.name, i.score]));
+ for (const item of ordered) expect(plainByName.get(item.name)).toBe(item.score);
+});
+
+test("equal composites resolve by name ascending", () => {
+ const twins = [
+ entry("skill-bb", "release helper tool"),
+ entry("skill-aa", "release helper tool"),
+ // Corpus padding so the twins' shared terms stay discriminating (df 2
+ // of n 5 passes the floor) and the floor does not drop them outright.
+ entry("unrelated-one", "tending the garden plants weekly"),
+ entry("unrelated-two", "author schema vocabulary packs"),
+ ];
+ // Identical descriptors score identically; equal usage keeps the composites
+ // equal, so only the name tie-break may order them.
+ const ranked = rankSkillCandidates(
+ {
+ query: "release helper tool",
+ skills: twins,
+ usageWeight: new Map([
+ ["skill-aa", 1],
+ ["skill-bb", 1],
+ ]),
+ },
+ 10,
+ );
+ expect(namesOf(ranked)).toEqual(["skill-aa", "skill-bb"]);
+});
+
+test("usage can never cross the discriminating-term floor", () => {
+ // Every gadget helper matches only corpus-common terms (df > half the
+ // corpus), so the floor drops them; a maximal usage weight changes that
+ // for none of them.
+ const map = new Map([
+ ["gadget-a", 1],
+ ["gadget-b", 1],
+ ["gadget-c", 1],
+ ["gadget-d", 1],
+ ]);
+ const ranked = rankSkillCandidates(
+ { query: `${ORDERING_QUERY} gadget`, skills: ORDERING_SKILLS, usageWeight: map },
+ 10,
+ );
+ for (const gadget of ["gadget-a", "gadget-b", "gadget-c", "gadget-d"]) {
+ expect(namesOf(ranked)).not.toContain(gadget);
+ }
+});
+
+test("the usage-ordered block is deterministic and re-ids the offer", () => {
+ const opts = { query: ORDERING_QUERY, skills: ORDERING_SKILLS, usageWeight: DAILY_HEAVY_USAGE };
+ const a = buildSkillAttachment(opts);
+ const b = buildSkillAttachment(opts);
+ expect(JSON.stringify(a)).toBe(JSON.stringify(b));
+ expect(namesOf(a.items)).toEqual(["release-daily", "release-one-off"]);
+});
+
+test("an empty usage map is inert: today's order and block", () => {
+ const plain = buildSkillAttachment({ query: ORDERING_QUERY, skills: ORDERING_SKILLS });
+ const inert = buildSkillAttachment({
+ query: ORDERING_QUERY,
+ skills: ORDERING_SKILLS,
+ usageWeight: new Map(),
+ });
+ expect(JSON.stringify(inert)).toBe(JSON.stringify(plain));
+});
diff --git a/tests/mcp/skills-attach-decision-tool.test.ts b/tests/mcp/skills-attach-decision-tool.test.ts
index b4606ea1..1f0d9867 100644
--- a/tests/mcp/skills-attach-decision-tool.test.ts
+++ b/tests/mcp/skills-attach-decision-tool.test.ts
@@ -9,6 +9,7 @@ import { mkdirSync, mkdtempSync, rmSync, writeFileSync } from "node:fs";
import { tmpdir } from "node:os";
import { join } from "node:path";
+import { appendContinuityRecord } from "../../src/core/brain/continuity/store.ts";
import {
listDecisionModelCalls,
resetDecisionSpendCache,
@@ -61,8 +62,9 @@ afterEach(async () => {
rmSync(tmp, { recursive: true, force: true });
});
-function writeConfig(uses: string | null, enabled = true): void {
+function writeConfig(uses: string | null, enabled = true, usage = false): void {
const lines = [`vault: "${vault}"`, `skill_auto_attach: "true"`];
+ if (usage) lines.push(`skills_attach_usage_ordering: "true"`);
if (uses !== null) {
lines.push(
`decision_model_enabled: "${enabled}"`,
@@ -176,3 +178,75 @@ test("enforce: a server failure returns today's result with the degrade reason",
expect(JSON.stringify(rest)).toBe(JSON.stringify(plain));
expect(field).toEqual({ mode: "enforce", applied: false, degraded: "http_529" });
});
+
+// --- usage-ordered offers (t_5d1ec8a8) through the decision path ---
+
+/** release-cut invoked daily; changelog-writer once, years ago. */
+function writeUsageRecords(): void {
+ for (let i = 1; i <= 5; i++) {
+ appendContinuityRecord(vault, {
+ kind: "skill_invoked",
+ createdAt: new Date(Date.now() - i * 60_000).toISOString(),
+ sourceRefs: [{ id: `sess:release-cut:${i}` }],
+ payload: { skill: "release-cut", agent: "claude", tool: "get_skill" },
+ });
+ }
+ appendContinuityRecord(vault, {
+ kind: "skill_invoked",
+ createdAt: "2020-01-01T00:00:00Z",
+ sourceRefs: [{ id: "sess:changelog-writer:1" }],
+ payload: { skill: "changelog-writer", agent: "claude", tool: "get_skill" },
+ });
+}
+
+function skillsRecords() {
+ return listDecisionModelCalls(vault).filter((r) => r.payload["use"] === "skills");
+}
+
+test("ordering flag off: usage records change nothing end to end (off proof)", async () => {
+ writeUsageRecords();
+ writeConfig(null);
+ const withRecords = await attach();
+ rmSync(vault, { recursive: true, force: true });
+ mkdirSync(vault, { recursive: true });
+ const withoutRecords = await attach();
+ expect(JSON.stringify(withRecords)).toBe(JSON.stringify(withoutRecords));
+ expect(server.requests).toHaveLength(0);
+});
+
+test("ordering flag on: shadow stays the usage-ordered deterministic offer", async () => {
+ writeUsageRecords();
+ writeConfig(null, true, true);
+ const plain = await attach();
+ const plainSkills = plain["skills"] as Array<{ name: string }>;
+ // The daily skill overtakes: changelog-writer leads lexically (6.80 vs
+ // 5.98 here), release-cut leads once its 1.5x usage ceiling applies.
+ expect(plainSkills[0]!.name).toBe("release-cut");
+ writeConfig(null);
+ const lexical = await attach();
+ expect((lexical["skills"] as Array<{ name: string }>)[0]!.name).toBe("changelog-writer");
+ expect(JSON.stringify(lexical)).not.toBe(JSON.stringify(plain));
+ writeConfig("skills:shadow", true, true);
+ server.setReply(reply);
+ const shadow = await attach();
+ const { decision_model: field, ...rest } = shadow;
+ expect(JSON.stringify(rest)).toBe(JSON.stringify(plain));
+ expect(field).toEqual({ mode: "shadow", applied: false, model: "fake-model-1.0" });
+ const final = skillsRecords().find((r) => r.payload["final"] === true)!;
+ expect(final.payload["deterministic_offered"]).toEqual(plainSkills.map((s) => s.name));
+ expect(final.payload["deterministic_offer_id"]).toBe(plain["offer_id"]);
+});
+
+test("ordering flag on with an empty vault: inert end to end", async () => {
+ writeConfig(null);
+ const off = await attach();
+ writeConfig(null, true, true);
+ const on = await attach();
+ expect(JSON.stringify(on)).toBe(JSON.stringify(off));
+ writeConfig("skills:shadow", true, true);
+ server.setReply(reply);
+ const shadow = await attach();
+ const { decision_model: field, ...rest } = shadow;
+ expect(JSON.stringify(rest)).toBe(JSON.stringify(off));
+ expect(field).toEqual({ mode: "shadow", applied: false, model: "fake-model-1.0" });
+});
diff --git a/tests/mcp/skills-attach-tool.test.ts b/tests/mcp/skills-attach-tool.test.ts
index b81ef67e..d42f24ef 100644
--- a/tests/mcp/skills-attach-tool.test.ts
+++ b/tests/mcp/skills-attach-tool.test.ts
@@ -1,8 +1,15 @@
-import { test, expect, beforeEach, afterEach } from "bun:test";
+import { test, expect, beforeEach, afterEach, spyOn } from "bun:test";
import { mkdtempSync, mkdirSync, rmSync, writeFileSync } from "node:fs";
import { tmpdir } from "node:os";
import { join } from "node:path";
+import {
+ appendContinuityRecord,
+ appendContinuityRecords,
+} from "../../src/core/brain/continuity/store.ts";
+import * as skillUsage from "../../src/core/brain/skill-usage.ts";
+import { resolveSkillsAttachUsageOrdering } from "../../src/core/config.ts";
+import { computeSkillOfferId } from "../../src/core/surface/skill-offer.ts";
import { SKILL_TOOLS } from "../../src/mcp/skill-tools.ts";
import { buildToolTable, findTool } from "../../src/mcp/tools.ts";
import type { ServerContext } from "../../src/mcp/tool-contract.ts";
@@ -71,3 +78,157 @@ test("an irrelevant turn attaches nothing even when enabled", async () => {
test("skills_attach is registered in the full tool table", () => {
expect(() => findTool(buildToolTable("full"), "skills_attach")).not.toThrow();
});
+
+// --- usage-ordered offers (t_5d1ec8a8): the flag and the per-turn wiring ---
+
+const RELEASE_QUERY = "cut the release notes and publish";
+const USAGE_FLAG_ENV = "OPEN_SECOND_BRAIN_SKILLS_ATTACH_USAGE_ORDERING";
+
+function writeSkill(name: string, description: string): void {
+ const dir = join(tmp, "skills", name);
+ mkdirSync(dir, { recursive: true });
+ writeFileSync(
+ join(dir, "SKILL.md"),
+ `---\nname: ${name}\ndescription: ${description}\n---\n\n# ${name}\n`,
+ );
+}
+
+/** Two matching release skills (alpha lexically hotter) plus corpus padding. */
+function writeReleaseSkills(): void {
+ writeSkill(
+ "release-alpha",
+ "Cut a software release: bump the version, tag, publish and write notes.",
+ );
+ writeSkill("release-daily", "Cut a software release: bump the version, tag and publish.");
+ writeSkill("helper-one", "Tending the garden plants weekly.");
+ writeSkill("helper-two", "Author schema vocabulary packs.");
+}
+
+function invoke(skill: string, seq: number, at: string): void {
+ appendContinuityRecord(ctx.vault, {
+ kind: "skill_invoked",
+ createdAt: at,
+ sourceRefs: [{ id: `sess:${skill}:${seq}` }],
+ payload: { skill, agent: "claude", tool: "get_skill" },
+ });
+}
+
+/** release-daily invoked daily, release-alpha once, years ago. */
+function writeUsageRecords(): void {
+ for (let i = 1; i <= 5; i++) {
+ invoke("release-daily", i, new Date(Date.now() - i * 60_000).toISOString());
+ }
+ invoke("release-alpha", 1, "2020-01-01T00:00:00Z");
+}
+
+function flagConfig(flag: boolean): void {
+ writeFileSync(
+ configPath,
+ `vault: "${ctx.vault}"\nskill_auto_attach: "true"${
+ flag ? '\nskills_attach_usage_ordering: "true"' : ""
+ }\n`,
+ );
+}
+
+test("the usage-ordering resolver defaults to off", () => {
+ expect(resolveSkillsAttachUsageOrdering(join(tmp, "missing.yaml"))).toBe(false);
+});
+
+test("the usage-ordering resolver reads the yaml key, only true or 1 truthy", () => {
+ writeFileSync(configPath, 'skills_attach_usage_ordering: "true"\n');
+ expect(resolveSkillsAttachUsageOrdering(configPath)).toBe(true);
+ writeFileSync(configPath, 'skills_attach_usage_ordering: "yes"\n');
+ expect(resolveSkillsAttachUsageOrdering(configPath)).toBe(false);
+ writeFileSync(configPath, 'skills_attach_usage_ordering: "1"\n');
+ expect(resolveSkillsAttachUsageOrdering(configPath)).toBe(true);
+});
+
+test("the usage-ordering env var wins over the yaml key", () => {
+ process.env[USAGE_FLAG_ENV] = "true";
+ try {
+ writeFileSync(configPath, 'skills_attach_usage_ordering: "false"\n');
+ expect(resolveSkillsAttachUsageOrdering(configPath)).toBe(true);
+ } finally {
+ delete process.env[USAGE_FLAG_ENV];
+ }
+});
+
+test("with the ordering flag off, usage records change nothing (off proof)", async () => {
+ writeReleaseSkills();
+ writeUsageRecords();
+ flagConfig(false);
+ const withRecords = (await attach().handler(ctx, { query: RELEASE_QUERY })) as object;
+ rmSync(ctx.vault, { recursive: true, force: true });
+ mkdirSync(ctx.vault, { recursive: true });
+ const withoutRecords = (await attach().handler(ctx, { query: RELEASE_QUERY })) as object;
+ expect(JSON.stringify(withRecords)).toBe(JSON.stringify(withoutRecords));
+});
+
+test("with the flag on and usage records, the offer reorders and the offer id follows", async () => {
+ writeReleaseSkills();
+ writeUsageRecords();
+ flagConfig(true);
+ const result = (await attach().handler(ctx, { query: RELEASE_QUERY })) as {
+ offer_id: string | null;
+ skills: Array<{ name: string; path: string }>;
+ };
+ expect(result.skills.map((s) => s.name)).toEqual(["release-daily", "release-alpha"]);
+ expect(result.offer_id).toBe(
+ computeSkillOfferId(
+ RELEASE_QUERY,
+ result.skills.map((s) => ({ name: s.name, path: s.path })),
+ ),
+ );
+});
+
+test("with the flag on and an empty vault the offer is byte-identical to off", async () => {
+ writeReleaseSkills();
+ flagConfig(false);
+ const off = (await attach().handler(ctx, { query: RELEASE_QUERY })) as object;
+ flagConfig(true);
+ const on = (await attach().handler(ctx, { query: RELEASE_QUERY })) as object;
+ expect(JSON.stringify(on)).toBe(JSON.stringify(off));
+});
+
+test("among recently used skills, the frequently invoked one outranks the once-used one", async () => {
+ // Identical descriptors, so the lexical scores are equal and only the usage
+ // weight can separate the two; "release-alpha" sorts before "release-daily",
+ // so the saturated-weight tie-break the ranking builder replaces would have
+ // offered the once-used skill first.
+ writeSkill("release-alpha", "Cut a software release: bump the version, tag and publish.");
+ writeSkill("release-daily", "Cut a software release: bump the version, tag and publish.");
+ writeSkill("helper-one", "Tending the garden plants weekly.");
+ writeSkill("helper-two", "Author schema vocabulary packs.");
+ appendContinuityRecords(
+ ctx.vault,
+ Array.from({ length: 300 }, (_, i) => ({
+ kind: "skill_invoked" as const,
+ createdAt: new Date(Date.now() - (i + 1) * 60_000).toISOString(),
+ sourceRefs: [{ id: `sess:release-daily:${i}` }],
+ payload: { skill: "release-daily", agent: "claude", tool: "get_skill" },
+ })),
+ );
+ invoke("release-alpha", 1, new Date(Date.now() - 86_400_000).toISOString());
+ flagConfig(true);
+ const result = (await attach().handler(ctx, { query: RELEASE_QUERY })) as {
+ skills: Array<{ name: string }>;
+ };
+ expect(result.skills.map((s) => s.name)).toEqual(["release-daily", "release-alpha"]);
+});
+
+test("deriveSkillUsage runs exactly once per attach call when on, never when off", async () => {
+ writeReleaseSkills();
+ writeUsageRecords();
+ const spy = spyOn(skillUsage, "deriveSkillUsage");
+ try {
+ flagConfig(false);
+ await attach().handler(ctx, { query: RELEASE_QUERY });
+ expect(spy.mock.calls.length).toBe(0);
+ flagConfig(true);
+ await attach().handler(ctx, { query: RELEASE_QUERY });
+ await attach().handler(ctx, { query: RELEASE_QUERY });
+ expect(spy.mock.calls.length).toBe(2);
+ } finally {
+ spy.mockRestore();
+ }
+});
diff --git a/uv.lock b/uv.lock
index 0eab9bfa..363b05e5 100644
--- a/uv.lock
+++ b/uv.lock
@@ -4,5 +4,5 @@ requires-python = ">=3.11"
[[package]]
name = "open-second-brain"
-version = "1.82.0"
+version = "1.83.0"
source = { editable = "." }