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: measured autonomy - a rule-promoting dream pass, model-aware context budgets and honest benchmarks (#269)
Serg Eroshef203591ef2b6
diff --git a/.claude-plugin/plugin.json b/.claude-plugin/plugin.jsonindex 404354ea..f13348fd 100644--- a/.claude-plugin/plugin.json+++ b/.claude-plugin/plugin.json@@ -1,6 +1,6 @@{"name": "open-second-brain",- "version": "1.89.0",+ "version": "1.90.0","description": "Plugin-first second brain package for AI agents and humans.","author": {"name": "Open Second Brain contributors"diff --git a/.codex-plugin/plugin.json b/.codex-plugin/plugin.jsonindex 4f9dadd0..64c3f99a 100644--- a/.codex-plugin/plugin.json+++ b/.codex-plugin/plugin.json@@ -1,6 +1,6 @@{"name": "open-second-brain",- "version": "1.89.0",+ "version": "1.90.0","description": "Plugin-first second brain package for Codex, Hermes, Claude Code, OpenClaw, and other agent runtimes.","author": {"name": "Open Second Brain contributors",diff --git a/CHANGELOG.md b/CHANGELOG.mdindex ca2b4bf1..e6c15cd3 100644--- a/CHANGELOG.md+++ b/CHANGELOG.md@@ -5,6 +5,28 @@ All notable changes to this project will be documented in this file.The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).+## [1.90.0] - 2026-10-20++Open Second Brain 1.90.0 turns the dream pass into a rule promoter, teaches every context budget to read the host model's window instead of guessing it, and makes two benchmarks honest about what they measure. The dream pass can promote one recurring cross-topic rule per owner per day out of confirmed preferences that state the same principle in different topics, behind an opt-in config block whose absence changes nothing. Context packs, preset suggestions, pre-compress guidance and the anticipatory cache resolve their token budgets from a model-aware window resolver - operator declarations first, then a published exact-id table, then a trailing `-1m` suffix, then the 200,000-token default - and each surface discloses which channel decided. The decision model gains a preregistered per-use eval with a measured promotion gate: a `promote` verdict writes a machine-side tuning mark, fail-closed against the spec hash, the fixture hash and the pinned thresholds, and only a valid mark moves a shadow-only use to enforce. Search names how far behind a stale index actually is - a measured document count on the `index-stale` degradation and a new `index_behind` line in `search status` - and the memory bench refuses, by name and before any state is created or any score published, every damaged pre-run and pre-report state it used to fail late on or silently reset. The search query language ships as a versioned JSON Schema artifact with `export` and `check` verbs, and a wikilink's spelling stops reading as ambiguous because an out-of-scope twin shares its basename.++### Fixed++- **A wikilink's spelling stops reading as ambiguous because an out-of-scope twin shares its basename.** Bridge discovery's basename census counted every vault page carrying the name, whatever the operator's scope rules say about it, so a note under an ignored directory - an `ignore_paths` entry, a frozen default ignore the narrow walk does not know, or outside the `include_paths` allowlist - forced the full-path spelling onto links to a uniquely-named in-scope target, and a bare `[[basename]]` resolved to neither. The census now resolves the vault scope once and skips pages whose vault-relative path fails it, beside the entity-status rule it already applied (a quarantined entity page never counted): a page outside the operator's scope is not part of the vault by definition and can no more anchor a wikilink than a missing file would. In-scope twins keep forcing the longer spelling exactly as before, and the census decides the spelling only - naming an out-of-scope target explicitly behaves exactly as it did.++### Changed++- **`brain_context_presets` suggest (and `o2b brain context-presets suggest`) now ranks an explicit `context_window_tokens` - and a model the exact-id table knows - above a matching `model_hints` token.** This is a deliberate order change from the hint-first draft, not a regression: the hint check used to run first, so `gpt-4o-mini` with an explicit 128,000 window answered tight-context from the "mini" hint, and the table-known `gpt-4.1-mini` answered tight-context although every derived budget for it sizes from the declared 1M window - two mappings for one model on two surfaces. The window is authoritative: an explicit `context_window_tokens` is the caller's own number for the deployment at hand, the same figure a derived budget sizes from, and a table row is a published fact - while a hint is a heuristic read off the id, so it answers only when nothing published resolves and never claims a resolved window. The conservative fallback (`tight-context`, low confidence) is unchanged for ids nothing places - and for exactly those ids the pack budget surfaces refuse rather than budget the default window's long-context, so an unrecognised model never gets a budget again.+- **The context-window resolver deliberately builds no window-proportional budgets: it selects between the two existing presets.** The presets tile the window range at 32,000 tokens - `tight-context` below, `long-context` above - so a 128k, a 200k and a 1M window all land in `long-context` and receive the same derived guidance; the widened recognition (the `[1m]` bracket form, provider and region prefixes, dated snapshots, `-vN:N` revision suffixes) changes which bucket an id lands in, never the bucket count. Window-proportional budgeting is its own calibrated change and is not improvised here.++### Added++- **Cross-topic rule promotion in the dream pass, behind an opt-in `cross_topic:` block whose absence is byte-identical to before.** The same-topic merge machinery buckets entries by topic before comparing, so a principle stated once per subject is invisible to it by construction; the new planner inverts that walk and considers pairs only ACROSS distinct topic buckets - confirmed preferences in at least `min_topics` (floor 2) distinct topics whose principle text reaches a jaccard similarity of `jaccard` (floor 0.6) elect one recurring cross-topic rule. The promotion is bounded four ways: sources must share one normalized owner token (ownerless counts as the shared token), so owner-scoped recall never leaks one agent's rules into another's rule body; one promotion per owner token per calendar day, budgeted through a `Brain/cross-topic-rules.json` ledger (a registered state surface) with the date taken from the pass's injected clock, so the same corpus elects the same rule on every machine and a rerun plans nothing; a budgeted-out pass plans nothing; and a source the same pass plans to retire is not eligible, so evidence is never hung off a file the run is about to move. The promoted artifact is an ordinary unconfirmed preference - `provenance: "inferred"`, `evidenced_by` wikilinks to every source, a `related` lineage - written by the dream apply stage through the transactional preference writer with overwrite off, under a content-derived `cross-<sha256-12>` slug so the same source set maps to one file and an already-present or retired slug skips. Sources are never modified or retired, the fired promotion counts as a state change (it rides the dream summary as `cross_topic_rules` and lands one Brain log event beside the ledger write), and a below-threshold pass stays byte-identical: no-op summary, no log write.+- **A model-aware context-window resolver, and every context budget that used to be a caller-declared guess now derives from it.** One pure module turns a host model id plus the operator's declarations into a window number and states for each answer WHAT decided: precedence is the operator's `context.window_tokens` config key, then `OPEN_SECOND_BRAIN_MODEL_CONTEXT_WINDOW`, then a published exact-id table (no family substring ever resolves - "sonnet" matches nothing, which is the defect the module exists to remove; the table carries gpt-4o at 128,000, the gpt-4.1 family at 1,000,000 and the three shipped Claude ids at 200,000, each row with its provenance note, and the id normalizes before the lookup, so provider and region prefixes like `openai/` and `us.anthropic.`, trailing date snapshots like `gpt-4.1-2025-04-14` and Bedrock `-vN:N` revision suffixes still reach the exact row), then the structural tier - a trailing, delimited `1m` suffix (`-1m` / `_1m`, or the trailing `[1m]` bracket form hosts report like `claude-sonnet-5-5[1m]`; a dot-led version fragment like the `4.1m` in `gpt-4.1m` is a version, not a window) - then the 200,000-token default. First-hand declarations - the operator's config key, the environment value, a published table row - pass through unclamped, used exactly as given; only the guessed tiers (the `1m` suffix expansion and the unknown-model default) are held to the [100,000, 1,000,000] band, with any clamp disclosed. The consumers: `brain_context_pack` (and `o2b brain context-pack`) accepts `model` and makes `max_tokens` optional - omitted, the budget is the matching preset's `context_pack.max_tokens` for the resolved window and the response names the deciding channel in `max_tokens_source`, while nothing resolvable - and no id the table, the suffix and the preset hints cannot place - is refused exactly as today, never a silent default; `brain_context_presets` suggest (and the CLI twin) resolves a window from `--model` alone with the source in the reason, an explicit window or a table-known id taking precedence over a hint match (deliberate; see Changed), and an unrecognised id answering the conservative fallback; `brain_pre_compress_pack` closes the unbounded-addendum case with resolver-derived caps, an unparseable window env value keeping the historical unbounded caps beside a named `window_warning`; and the anticipatory cache scales its budget to the resolved window's hundredth part, floored at the 2,000-token constant so it only ever scales up, disclosed when derived and byte-identical when nothing resolves.+- **A preregistered per-use decision-model eval, and a measured gate that is the only path out of shadow.** Each use ships a preregistered spec - fixture reference, seed, split rule, metric, error ceiling, minimum counted n, and the pinned threshold values it measures - with a canonical spec hash; the take is a hash-order split (`sha256Hex(seed + ":" + id)`, dev = the first ceil(0.3 n), membership frozen at preregistration) and the runner verifies the split against the frozen receipt before grading. `o2b decision-model eval run --use <use>` grades the counted split through the configured adapter, caching `decision_model_eval_grade` records stamped with the spec hash, profile, use, seed, item ids, boolean verdicts, metric and counted n (origin `eval`, spend counted toward the daily cost gate, malformed records skipped by the lister with a named note); `o2b decision-model eval list` renders them oldest first in prose or `--json`, and `o2b decision-model check` names the measured state - untuned, measured under spec hash X, or baseline. The verdict is the preregistered three-arm rule - promote only when the counted error meets the ceiling, no-regression against the deterministic baseline holds, and the counted n is met; a short n is its own arm - and a `promote` verdict, and only that, writes a machine-side tuning mark per (threshold profile, use) under the platform state root, outside every vault. Acceptance is fail-closed: the mark is honored only when its spec hash, fixture hash and pinned threshold values all match the installed spec, so a spec edited after the mark was written, a fixture that moved, or thresholds that drifted each put the use back in shadow; no mark file is exactly today's behavior, and a hand-registered tune always wins because the resolver consults the mark only where the source table says untuned. `o2b decision-model doctor` reflects the measured state.+- **A measured index-behind count, on the stale note and in `search status`.** A search that names a stale index (`index-stale`, the index older than ten minutes) now also reports how far behind it is: `detail.behindCount` is the number of documents the next incremental run would add, update or delete, measured under the same gate that fires the code and cached for at most 60 seconds - invalidated by this process's own note writes, so a write from another process can leave the count up to a minute old - by a stat-only walk (one `readdir` plus one `stat` per entry, no content read, no hashing) diffed against the index's stored rows. The count is deliberately an upper bound: a touch-only file (identical bytes, bumped mtime) counts as changed, because "behind" means "what the next run would re-read", not "notes missing from answers". A measured zero rides too; a failed measurement is absent - the note then names the age alone, and a fresh index performs no walk at all. `o2b search status` prints the same census as `index_behind:` in its freshen block (`<n> doc(s)`, or `(not measured)`) and serializes it as `index_behind` in the `--json` freshen object, null when not measured - never a fabricated zero - measured only when an index exists, and without touching the doctor's own freshen check, which reads the state file and picks up no walk cost.+- **Bench-run integrity guards: a closed refusal vocabulary over every damaged pre-run and pre-report state.** Before a run exists, a preflight refuses - by name, on stderr, as `refused (<kind>): <detail>` with a non-zero exit and no run directory left behind - an unusable runs directory (`runs_dir_unusable`), a fresh run whose identity collides with an existing run dir (`run_dir_exists`; the prior checkpoint survives and the detail names `--resume`, where the store used to silently reset it), a resume target whose checkpoint is unparseable (`checkpoint_unparseable`), names a phase this build does not know (`checkpoint_phase_unknown`) or lists phases out of order or duplicated (`checkpoint_phase_order`), a phase marked done whose artifacts are gone or truncated (`run_artifact_missing` - the materialized vault is required exactly while retrieval still has to run against it, the per-question result files once retrieve is done, `report.json` once report is), and a fixture that cross-references a note or session it never defines (`fixture_cross_reference`, which used to score as an ordinary missing-expected FAIL indistinguishable from a real regression). Config resolution and the capability gate moved above run creation, so those refusals leave no run dir behind either. Before any score is counted, and again before the report writes, the persisted trace is validated: a question with no result file (`trace_result_missing`), a truncated or non-JSON one (`trace_result_unparseable`), an id that differs from the question it is stored under (`trace_id_mismatch`), a category-required field absent from a record (`trace_field_absent` - present-but-empty is a legitimate miss and passes), a faulted proactive decision (`trace_faulted_decisions` - the report must never dress harness breakage up as memory behavior), files in `results/` beyond the fixture's question ids (`trace_extra_results`), and a report whose counts disagree with its own trace (`report_counts_mismatch`, recomputed through the same aggregation the report builder uses, so the two cannot drift). Every detail names the repair. What is deliberately not a refusal: score content - an all-questions-failed run is the harness's purpose - and the external judge staying in `error` remains advisory. The guards add zero stdout on success, existing run ids, checkpoints and reports are byte-identical (`fixtureHash` stays content-only), and the per-question results and `report.json` are now written atomically.+- **The search query language ships as a versioned JSON Schema artifact, with `export` and `check` verbs.** `schemas/brain/search-query.schema.json` (`$id brain.search_query.v1`, draft 2020-12) is derived - never hand-edited - from the search-options descriptor, the same typed table that derives the served `brain_search` inputSchema (byte-identically) and the `o2b search` CLI flag table, so the published artifact cannot disagree with either surface; a `$defs.search_query_document` block publishes the grammar of the line-oriented query-document program (the `intent:` / `lex:` / `vec:` / `hyde:` lanes, the intent enum complete against the parser). The artifact documents the per-surface asymmetries the descriptor records instead of flattening them. `o2b search schema export [--stdout]` regenerates the committed file; `o2b search schema check` re-derives and compares - JSON equality, not byte equality, so the repo formatter's layout never reads as drift - exiting 0 clean, 2 on drift with stderr naming which (the property set or the content) and the remedy, and 2 when the file is missing or unreadable, so CI and any operator share one named verdict. The verbs live under the search group deliberately: `o2b brain schema` is the vault schema pack, a wholly unrelated "schema".+## [1.89.0] - 2026-10-19Open Second Brain 1.89.0 makes the derived truth follow the note write. A rename or move rewrites the inbound links it touches to the shortest spelling that still resolves, repairs the bare-name links its carrier-count change would silently repoint, and claims one detached search-index refresh the moment the write lands, so the staleness window starts closing at the write instead of at the next search. Entity anchoring matches the spelling a fact actually uses - "Ada Lovelace" anchors a registry entity reachable as "ada-lovelace" - while a leading-edge word-boundary rule stops the matcher from anchoring inside other words without silencing the inflected forms a token boundary admits. And the anchors a fact carries can follow its source page's outbound links: the anchoring kernel accepts caller-resolved link-derived ids, and a fifth maintenance lane task, `relink`, re-anchors the extracted signals already stored - every lane pass reports what the task would add, and the stored lines change only when the run asks for it.@@ -8665,6 +8687,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.90.0]: https://github.com/itechmeat/open-second-brain/compare/v1.89.0...v1.90.0[1.89.0]: https://github.com/itechmeat/open-second-brain/compare/v1.88.0...v1.89.0[1.88.0]: https://github.com/itechmeat/open-second-brain/compare/v1.87.0...v1.88.0[1.87.0]: https://github.com/itechmeat/open-second-brain/compare/v1.86.2...v1.87.0diff --git a/docs/brainstorm/cycle-20261020/cli-output/claude.md b/docs/brainstorm/cycle-20261020/cli-output/claude.mdnew file mode 100644index 00000000..abf821a3--- /dev/null+++ b/docs/brainstorm/cycle-20261020/cli-output/claude.md@@ -0,0 +1,30 @@+### Variant 1: Substrate-first with live censuses++- **Approach**: A short serial substrate pass lands every shared declarative surface before the feature lanes start: the config quartet in one coherent diff (src/core/brain/types.ts carrying both the `cross_topic` block on BrainDreamConfig at :1450 and the new `context:` block near :2030, the policy parse/validate registration, the config-template entries, and the single config-template-ratchet test update), the env parse helper in src/core/config.ts, the path constants plus the state-surface row for Brain/cross-topic-rules.json, and the search-options-descriptor module with SEARCH_INPUT_SCHEMA derived byte-identically behind an equality test. The five feature lanes then run in parallel on disjoint file sets, consuming the substrate; the model-window resolver is built by the context-window lane itself, and the descriptor's remaining work (CLI flag derivation, the committed schemas/brain artifact, the schema export/check verb, the scoped doc-example tests) proceeds as a normal lane. Census registration stays per-lane as features go; because the substrate pre-registered the riskiest new surface, the only lane expected to add a census row is judge-eval, if it counts the machine-side mark file as a state surface.+- **Trade-offs**:+ - Pros: the single real code collision (the config quartet shared by cross-topic and context-window) is resolved exactly once in one reviewable diff; every commit on the cycle branch stays census-green and bisectable; the config-template ratchet is satisfied in one pass instead of two sequential edits; landing the descriptor with its byte-equality proof early converts the highest-blast-radius feature into an additive one and removes tail risk; the doc-example tests are scoped to the Search sections, so the later freshness and bench doc edits cannot break them.+ - Cons: a serial phase delays all lanes by the substrate duration; early risk concentrates in the config validation machinery, where a misspelled key only warns and silently defaults; lanes build against types that exist only on the cycle branch, so branch discipline is required; the substrate lane must be staffed with someone who understands both the dream config parse and the policy block machinery.+- **Complexity**: medium+- **Risk**: low++### Variant 2: Independent lanes with ownership contracts and an end-stage integrator++- **Approach**: No pre-landing. Five lanes start immediately from the same base under declared file ownership: the context-window lane owns the config quartet and the ratchet test; the cross-topic lane takes an explicit dependency on it and merges after, touching only the dream files, the path constants and its ledger write; judge-eval, freshness-plus-wikilink, and bench-plus-schema-schema-artifact form the remaining lanes on provably disjoint sets. Each lane registers its own census rows so every branch is green on its own. One integrator pass at the end resolves the residual collisions (state/surfaces.ts between the ledger and mark rows, command-manifest.ts between the eval and schema verbs, docs/cli-reference.md across three features, CHANGELOG), and the schema unification is sequenced last so the byte-identity check of SEARCH_INPUT_SCHEMA and the CLI flag derivation runs against the settled tree, with its doc-example tests executing after the freshness and bench doc edits have landed.+- **Trade-offs**:+ - Pros: maximum parallelism from minute zero; no lane waits on a substrate; the config machinery gets a single owner, so the two features never edit the same files simultaneously; sequencing the schema unification last means its byte-freeze and doc tests verify the final state of both the frozen MCP surface and the docs, eliminating the risk of later edits invalidating the proof.+ - Cons: the cross-topic lane is blocked or must stub against the config owner, creating a hidden serial chain inside a nominally parallel plan; integration churn concentrates at the end precisely in the sensitive files (config validation, state surfaces, the frozen schema, the manifest), where conflicts get resolved under deadline pressure; the highest-blast-radius feature lands last, so any byte-drift discovery or SCHEMA_IDS tripwire surprise arrives when the least schedule remains; reviewers see the config additions twice, in two feature diffs, instead of once.+- **Complexity**: medium+- **Risk**: medium++### Variant 3: Two-wave train with centralized registration commits++- **Approach**: No substrate pass. The cycle merges onto the cycle branch as two waves. Wave 1 lands immediately in parallel the three features with zero shared files: wikilink disambiguation, the freshness behind-count, and the bench guards. Wave 2 sequences the rest: context-window lands first and owns the config quartet, cross-topic rebases on it, judge-eval runs in parallel on its disjoint set, and the schema unification lands last in the wave, followed by a single final docs pass. Census and registry registration is centralized: each lane develops its rows as an attached patch, and one registration commit at each wave boundary applies the state-surface rows, config-template entries, manifest lines and doc updates in a single reviewable diff, keeping the PR head green at each boundary.+- **Trade-offs**:+ - Pros: the three disjoint features deliver early with no coordination cost, shrinking the tail; two wave boundaries give two clean integration and review checkpoints instead of one end-stage crunch; the centralized registration commit presents every census, manifest and docs change as one set, which is efficient to review as a whole.+ - Cons: commits between a feature landing and the wave-boundary registration commit leave the cycle branch census-red, which hurts bisectability inside the single PR; registration review is decoupled from feature review, so whoever reviews the registration commit may lack the context justifying each row; the wave discipline serializes the config work anyway, yielding most of Variant 2's constraint plus additional choreography; per-lane branches must either carry known-red census tests or maintain local registration patches, both of which invite drift between what a lane verified and what lands.+- **Complexity**: large+- **Risk**: medium++### Recommended: Variant 1++**Rationale**: The architecture censuses fail the build on unregistered new surfaces, so registration must be live wherever a lane adds state; Variant 1 is the only variant that removes the riskiest registrations (the cross-topic ledger surface row and the config-template ratchet shared by two features) from the lanes entirely, keeping every commit across four or five parallel lanes green and bisectable. The one genuine code collision, the config quartet shared by the cross-topic and context-window features, is resolved exactly once in a small coherent diff rather than through ownership-and-rebase choreography that concentrates churn in exactly the files where a mistake silently defaults. Landing the descriptor with its byte-equality proof early converts the schema unification, the highest-blast-radius feature, into an additive change and leaves only ordinary lane work for the tail. The cost is a short serial substrate phase and an early coordination front, which is cheap at this substrate size and pays for itself in merge stability and review clarity.diff --git a/docs/brainstorm/cycle-20261020/cli-output/prompt.md b/docs/brainstorm/cycle-20261020/cli-output/prompt.mdnew file mode 100644index 00000000..91315ece--- /dev/null+++ b/docs/brainstorm/cycle-20261020/cli-output/prompt.md@@ -0,0 +1,79 @@+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++Cycle 20261020: a seven-feature release cycle for Open Second Brain, planned as four to five parallel implementation lanes on disjoint file sets. The features (kanban cards in parentheses):++1. Cross-topic rule promotion in the dream pass (t_642bc2b8). The dream pass's only new-preference writer iterates per-topic buckets one key at a time; the lexical merge layer is same-topic by construction. Add a deterministic cross-bucket detector and promote recurring confirmed preferences into one evidence-linked unconfirmed rule, with a promotion budget and a new Brain/ ledger.+2. Shared model-aware context-window resolver (t_a567cc12). Every context-pack and compact budget is a caller-declared number or a two-bucket model-hint guess (substring matching on "mini"/"pro"/etc.). Build one shared resolver deriving the window from the model id (exact table, structural 1M-suffix rule), an operator config key and an environment variable, and switch the context-pack, preset-suggest, pre-compress and anticipatory-cache defaults to it.+3. Preregistered judge eval gates which models may auto-resolve (t_4e1681b3). The decision-model threshold profiles' `tuned` state is a hand edit to source. Build frozen content-hashed eval specs with seeded takes and a dev/counted split, cache graded verdicts, and write a machine-side tuning mark that the auto-resolve gate consults so a measured profile may run enforce.+4. Measured index-behind count (t_e4438152). The search answer says the index is stale but not by how much. Add a live stat-only walk reusing the incremental fastpath that counts the documents the next incremental run would add, update or delete, surfaced in the index-stale degradation detail and the status freshen block.+5. Bench-run integrity guards (t_d7ce8baf). The Memory Observability Suite harness can leave orphan run dirs on refusal, silently reset an existing run, publish a report from a tampered or truncated trace, and write artifacts non-atomically. Add named preflight refusals before run state is created and trace validation before a report publishes, with strict checkpoints and atomic writes.+6. Machine-readable JSON Schema for the query/search language (t_50c81d5c). The search input schema exists as drifting copies (MCP schema object, CLI flag parser, TypeScript SearchOptions type, plus a vendored Python projection). Unify behind one descriptor module, derive the served schema byte-identically, commit a versioned artifact under schemas/brain/, and add export/check verbs with doc-example tests.+7. Ambiguous-wikilink disambiguation must honor vault scope (t_fd842db0). Bridge acceptance counts basename twins over a census that ignores the operator's vault ignore/include rules, so a twin under node_modules forces a full-path wikilink spelling. Filter the census through the shared scope rules, matching the lint walkers' precedent.++Structure question for the consultant: how should this cycle be organized into a serial substrate (if any) and parallel lanes so that file ownership is disjoint, the architecture censuses stay green on every commit, and the frozen public surfaces are not broken?++# Project context++Open Second Brain, TypeScript on the Bun runtime; local-first memory layer with an MCP server, a CLI (o2b), and a deterministic "dream" maintenance pass.++Recent commits:+9e579820 feat: note-change truth maintenance for links, index freshness and entity anchoring (#268)+f7c1c88c feat: entity merge repair, write destinations, cross-agent catch-up and OKF v0.2 (v1.88.0) (#267)+f6d9f95f feat: guarded host writes, walkable list results, a converse decision route and a snoozable trigger queue (v1.87.0) (#266)+9a19fcc8 chore(deps): bump hashgraph-online/ai-plugin-scanner-action (#262)+69bec9d1 chore(deps-dev): bump the bun-minor-and-patch group with 3 updates (#263)+63410769 chore(apb): run the owner dev quality cycle in osb-pr-prepare (#265)+b183b6c3 fix: one holder per hook-state scope through a stale-lock takeover (v1.86.2) (#261)+fd8a0c8d fix: v1.86.0 review repairs and embedding preservation across schema upgrades (v1.86.1) (#259)+e0d11656 feat: session-mining economy - mining tombstones, a shadow trust-gate mode and a live-counts console (v1.86.0) (#258)+948a0403 feat: storage lifecycle for long-lived vaults (v1.85.0) (#257)+ef974e0d fix: comma-separated and legacy scopes no longer abort the dream pass, plus three test-isolation fixes (v1.84.1) (#254)+14a99584 feat: recall lane concurrency, overlapped_ms accounting, a caller-selectable packing policy and standing-instruction facets (v1.84.0) (#252)+e239d323 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)+44a8ccaf feat: recall quality - an iterative recall loop, coverage-first session recall and a measured surfacing key (v1.82.0) (#250)+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)++Related files:+- Dream pass: src/core/brain/dream.ts, dream-plan.ts, dream-plan-topics.ts, dream-apply.ts, dream-summary.ts, dream-types.ts, dream-report.ts, rollup-ladder.ts, preference-txn.ts+- Context budgets: src/core/brain/context-presets.ts, src/mcp/brain/pack-tools.ts, src/cli/brain/verbs/context-pack.ts, context-presets.ts, src/core/brain/anticipatory-cache.ts+- Decision model: src/core/decision-model/questions.ts, config.ts, record.ts, diagnostics.ts, reports/, src/cli/decision-model.ts+- Search: src/core/search/indexer.ts, search.ts, freshen.ts, pipeline/outcome.ts, retrieval-trail.ts, src/cli/search/verbs/status.ts+- Bench: src/core/bench/phases.ts, run-store.ts, failure-modes.ts, judge.ts, src/cli/brain/verbs/bench.ts+- Query language: src/mcp/search-tools.ts, src/cli/search/verbs/query.ts, src/core/search/types.ts, schemas/brain/, plugins/hermes/_schemas.py+- Links and scope: src/core/brain/link-graph/bridge-discovery.ts, src/core/vault-scope/, src/core/brain/page-dedup.ts+- Shared registries: src/core/state/surfaces.ts, src/core/brain/policy/validate.ts, src/core/brain/config-template.ts, src/core/config.ts, src/cli/command-manifest.ts++Conventions:+- Architecture census tests (write-site, state-surface, append-shard, import-cycles, visibility-surface) fail the build on unregistered new surfaces; registration must be live wherever a lane adds state.+- New config keys require a config-template entry or a listed omission, enforced by a ratchet test.+- The served MCP tools/list is a frozen public surface (v1.0.0 freeze); schema changes must be byte-identical or the vendored Hermes Python projection must be regenerated by hand in the same change.+- Conventional commits; formatter (oxfmt) and linter (oxlint) must pass before every commit; version bump and CHANGELOG entry land inside the PR via the pr-prepare phase.+- A failed measurement is reported as absent (null), never as zero.++Constraints:+- The kernel never calls an LLM: dream planning, detection and promotion must be deterministic; embeddings may nominate but never gate the kernel path.+- Server-derived facts only: every new number a surface reports must be measured or derived, not assumed; a failed measurement is absent, never zero.+- Egress and architecture censuses must stay green: no new unregistered write sites, state surfaces, or append shards; no new external dependencies.+- The cycle is planned as 4-5 parallel lanes on disjoint file sets; identify every shared file (config validation, state surfaces, command manifest, docs) and decide who owns it or which serial substrate pass resolves it first.+- Existing pinned test suites and published report fields (fixture_hash, served schema bytes) must remain stable unless a feature explicitly changes them.++# 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/cycle-20261020/design.md b/docs/brainstorm/cycle-20261020/design.mdnew file mode 100644index 00000000..e851d9d2--- /dev/null+++ b/docs/brainstorm/cycle-20261020/design.md@@ -0,0 +1,216 @@+# Cycle 20261020 - measured autonomy: the dream loop, the context window and every surface that reports a fact++**Status:** draft+**Author:** orchestrator (via feature-release-playbook)+**Audience:** implementation++## Problem statement++This cycle's spine is measured autonomy. Today the system's autonomous and semi-autonomous surfaces run on assumptions: the dream pass cannot generalize a pattern across topic buckets even when the evidence is textually identical, context packs size themselves to a caller-declared guess instead of the host model's real window, a decision-model profile's `tuned` state is a hand edit to source rather than a measurement, the search answer says only how old the index is but not how far behind it is, the bench harness can publish scores from a corrupted or truncated run, the query language exists as four drifting copies with no machine-readable contract, and wikilink disambiguation counts basename twins the rest of the product refuses to index. Every one of the seven features replaces one of those assumptions with a measured, derived or scope-honest fact. Together they make the loop safer to let run: promotion is budgeted and evidence-linked, budgets derive from the real window, auto-resolve is gated by preregistered evaluation, freshness and bench output report what was actually measured, and the query-language and wikilink contracts state what is true instead of what a filename happens to look like.++## Scope++Seven features, each with its kanban card:++- `t_642bc2b8` - Cross-topic rule promotion in the dream pass: a deterministic lexical detector elects confirmed preferences recurring across at least N folded topic buckets and promotes one representative rule as an unconfirmed, evidence-linked preference, one promotion per owner per day through a new ledger.+- `t_a567cc12` - Shared model-aware context-window resolver: a pure resolver derives the model context window from an exact-id table, a structural 1M-suffix rule, an operator `_brain.yaml` key and an environment variable; context packs, preset suggestions, pre-compress guidance and the anticipatory cache default derive from it.+- `t_4e1681b3` - Preregistered judge eval gating auto-resolve: frozen, content-hashed eval specs with seeded takes and a dev/counted split; graded verdicts cached as continuity records; a machine-side tuning mark that `thresholdsTunedFor` consults so a measured profile may run `enforce`.+- `t_e4438152` - Measured index-behind count: a live stat-only walk reusing the incremental fastpath reports how many documents the next incremental run would add, update or delete, surfaced through the `index-stale` degradation detail and the status freshen block.+- `t_d7ce8baf` - Bench-run integrity guards: named preflight refusals before any run state is created, trace validation before a report publishes, strict checkpoint parsing and atomic writes for published artifacts.+- `t_50c81d5c` - Machine-readable JSON Schema for the query/search language: one descriptor module as the single source of truth, `SEARCH_INPUT_SCHEMA` derived byte-identically from it, a committed versioned artifact under `schemas/brain/`, and `o2b search schema export|check` verbs with doc-example tests.+- `t_fd842db0` - Ambiguous-wikilink disambiguation honors vault scope: `countBasenameMatches` filters its census through `resolveVaultScope`/`matchScope` so ignored twins no longer force full-path spellings.++Plus the shared substrate (Task 0 in `plan.md`): the config quartet for both new config blocks, the environment parse helper, the cross-topic ledger path constants and its state-surface census row, and the search-options descriptor with a byte-identical `SEARCH_INPUT_SCHEMA` derivation behind an equality test.++## Out of scope++- Retrieval-plan advisor and bench max-token defaults derived from the resolver (`src/core/brain/retrieval-plan.ts:40,191`, `src/core/bench/phases.ts:533`) and the pre-compact-extract char default (`src/core/brain/pre-compact-extract.ts:109`) - the context-window recon marks these optional second wave; bench numbers are pinned and stay explicit.+- Reconciling the MCP limit 50 vs CLI limit 100, the uncapped CLI query, the naming drift (`path` vs `path_prefix`), and the `semantic` tri-state asymmetry - the descriptor records them; fixing them is a deliberate surface change of its own.+- Embedding-based nomination feeding the cross-topic detector, and teaching the dedup predicates to skip pairs where one side cites the other - named as a follow-up unit, not silently widened here.+- Folding `admitToIndex` into the wikilink scope filter, changing `listVaultPages`, or making adjacent hygiene walkers scope-aware - the card's residue is bridge-discovery's private census only.+- Per-source freshness grading and a resident indexer process - ruled out by the card.+- `brain benchmark run` (the older live-vault harness) - guards stay inside `src/core/bench` plus the `brain bench memory` verb.+- A CHANGELOG entry or version bump written by the feature lanes - the consolidated entry lands in the integrator task, and the version bump stays with the pr-prepare phase.++## Premise verification++All seven premises were verified against the live source by read-only recon. Verdict per card, with the decisive evidence:++- `t_642bc2b8` - CONFIRMED, with one sharpening: `findMergeCandidates` buckets entries by `${p.topic}\x00${p.scope ?? ""}` (`src/core/brain/merge-candidates.ts:97`) and `planTopics` iterates the `byTopic` map one folded key at a time (`src/core/brain/dream-plan-topics.ts:62-159`, loop at `:121`), so no cross-topic promotion path exists; the dedup detector nominates merges only (`src/core/brain/hygiene/detectors/dedup.ts:174`).+- `t_a567cc12` - CONFIRMED: `suggestContextPreset` matches model ids by case-insensitive substring against two coarse hint buckets (`src/core/brain/context-presets.ts:108-118`, buckets at `:60-77`), and every context-pack budget is caller-declared (`required: ["max_tokens"]` at `src/mcp/brain/pack-tools.ts:1214`); no surface derives a budget from the real window.+- `t_4e1681b3` - CONFIRMED: the threshold profiles table is hardcoded with `tuned` as a source literal (`src/core/decision-model/questions.ts:111-139`), the zero-regret promotion rule exists only as a report recommendation (`src/core/decision-model/reports/extract-prefilter.ts:180-185`), and no preregistration machinery exists anywhere (zero repo-wide hits for "preregist").+- `t_e4438152` - CONFIRMED, with one refinement: the `index-stale` degradation carries only `ageSeconds` (`src/core/search/pipeline/outcome.ts:324-354`), the status freshen block reports only the last completed run (`src/core/search/freshen.ts:723-782`), and the incremental fastpath comparison the behind-walk reuses is mtime+size (`src/core/search/indexer.ts:510`).+- `t_d7ce8baf` - CONFIRMED, with two scoping corrections: the run-identity hash is already shipped (`src/core/bench/run-store.ts:56-70`), while the real gaps are ordering/atomicity (config resolution and capability gate run after run creation, `src/core/bench/phases.ts:271-297`; `createBenchRun` silently resets an existing run dir, `run-store.ts:100-113`; non-atomic report writes, `phases.ts:345-350`) and the absence of trace validation before publishing.+- `t_50c81d5c` - CONFIRMED, with one addition: `SEARCH_INPUT_SCHEMA` is a hand-maintained 35-property object (`src/mcp/search-tools.ts:137-353`) with a hand-parallel enforcement handler (`:996-1138`), the CLI parser and the `SearchOptions` type drift from it, and the recon found a fourth, previously uncounted copy - the vendored Python projection at `plugins/hermes/_schemas.py:244`.+- `t_fd842db0` - CONFIRMED: `acceptBridge` spells the wikilink from a basename census that never consults vault scope (`src/core/brain/link-graph/bridge-discovery.ts:329`, census at `:376-383`), because the walk applies only `DEFAULT_SKIP_DIRS` (`src/core/vault.ts:137`) and never `resolveVaultScope`/`matchScope`; the lint half of the card is already at parity.++## Chosen approach++Consultant Variant 1, substrate-first with live censuses. A short serial substrate pass (Task 0, one lane, landing first as one to three commits) puts every shared declarative surface in place before any feature lane starts: the config quartet in one coherent diff (the `cross_topic` block on `BrainDreamConfig` and the new `context:` window block in `src/core/brain/types.ts`, the policy parse/validate registration, the `config-template.ts` entries and the single config-template-ratchet test update), the environment parse helper in `src/core/config.ts`, the path constants plus the state-surface census row for `Brain/cross-topic-rules.json`, and `src/core/search/search-options-descriptor.ts` deriving `SEARCH_INPUT_SCHEMA` byte-identically behind an equality test. Five feature lanes then run in parallel on disjoint file sets, consuming the substrate; the model-window resolver is built by the context-window lane itself, and the descriptor's remaining work (CLI flag derivation, the committed schema artifact, the export/check verbs, the scoped doc-example tests) proceeds as a normal lane. Census registration stays per-lane as features go; because the substrate pre-registered the riskiest new surface, the only lane that might add a census row is judge-eval, and the design below decides it does not (the tuning mark is machine-side state outside the vault). A final integrator task consolidates the docs, dedups the command manifest and runs the full local QA gates.++## Design decisions++### t_642bc2b8 - cross-topic rule promotion (recon: recommended approach and decisions)++Recommended approach: a pure planner `dream-plan-cross-topic.ts` modeled on `rollup-ladder.ts`, called in `dream.ts` after `planRefresh` (it needs post-refresh status) and before the `hasStateChange` gate so a fired promotion counts as a state change while a below-threshold pass stays byte-identical; the write lands inside the snapshot-gated apply stage through `writePreferences`, and the ledger persists in dream-report next to the rollup ledger. Every preference write goes through `writePreferenceTxn` (the single chokepoint); the promoted rule reuses the `deriveFact` evidence-linkage shape.++Named decisions, with the recon's recommendations:++1. Recurring-across-topics definition - deterministic and lexical: confirmed preferences in at least N (default 2) distinct folded `topicKey` buckets whose principles reach a jaccard threshold, via a cross-bucket variant of the `findSimilarPairs` walk reusing `tokenise`/`jaccard`; deterministic code-unit ordering everywhere so the same corpus elects the same cluster on every machine. The kernel stays embedding-free.+2. Principle text - no synthesis: the promoted rule takes one source principle verbatim (lexicographically smallest source, same total-order trick as `preferredTopicDisplay`). The cross-topic fact lives in the evidence, not in invented prose.+3. Artifact and lifecycle - a new unconfirmed preference (`status: unconfirmed`, `provenance: "inferred"`, `evidenced_by` = sorted `[[pref-...]]` wikilinks of every source, `unconfirmed_until` = now + `dream.unconfirmed_window_days`) written through `writePreferenceTxn`, then living under the normal refresh/confirm/retire machinery. Append-only by construction; sources are never retired or edited.+4. Topic - a deterministic join of the sorted source topic displays, with `related` carrying the source pref ids for lineage; the recall-visibility limitation (topic-keyed recall never surfaces a synthetic topic) is named in the release note rather than hacked in this unit.+5. Slug - content-derived `cross-<sha256-12>` over the sorted source pref ids, so the same source set maps to the same file and a rerun is a no-op below the changed gate; reserved against `collectReservedPreferenceSlugs`; optionally reused as `idempotency_key` for the ledger's payload-mismatch protection.+6. Budget - a new ledger `Brain/cross-topic-rules.json` shaped `{ version, last_promoted: Record<ownerToken, date> }`, read at plan time, written atomically (shared `atomicWriteFileSync`, never an append-mode writer) only when fired, next to the rollup ledger write; one promotion per owner token per calendar day, enforced at plan time so a budgeted-out pass is a no-op; the date comes from the pass's injected `now`, never wall clock.+7. Config - an opt-in `cross_topic?: { enabled?, min_topics?, jaccard? }` block on `BrainDreamConfig`; absent means off and the default install stays byte-identical (the `heal_enrich_enabled`/`salience_threshold` pattern).+8. Owner semantics - source preferences must share one normalized owner token (ownerless counts as the shared empty token); cross-owner sets are never merged into one owner-visible rule.+9. Known interaction - the promoted rule will be similar to its own sources and a near-certain future nomination of the dedup detector; mitigation is the verbatim principle plus content slug; teaching dedup to skip `evidenced_by`-cited pairs is a named follow-up, not a silent widening.++### t_a567cc12 - model-aware context-window resolver++Recommended approach: a new pure module `src/core/brain/model-window.ts` mirroring `src/core/search/embeddings/presets.ts` piece by piece - an exact-id table with provenance notes, named constants (`DEFAULT_MODEL_CONTEXT_WINDOW_TOKENS = 200_000`, `MIN = 100_000`, `MAX = 1_000_000`), two matching tiers, and one `resolveModelContextWindowTokens` entry point returning `{ windowTokens, source, clamped }`.++Named decisions, with the recon's recommendations:++1. Matching tiers - exact table lookup (`null` means UNKNOWN, never a default synonym; the id normalizes first so host-side spellings - provider and region prefixes, trailing date snapshots, `-vN:N` revision suffixes - still reach the exact row without ever widening a family name into a hit) plus one structural rule: a trailing, delimited `1m` suffix (`-1m` / `_1m`, or the trailing `[1m]` bracket form hosts report) resolves to 1_000_000. No family substring matching ever - that is the defect being removed; the suffix is a published declaration, a family name is not.+2. Precedence - operator config > operator env > declared table > 1M suffix > default; an explicit per-call argument wins over both operator channels. Every first-hand declaration - operator config, operator env, an exact table row - passes through unclamped: a declared 8k/32k window must budget inside the real window, not be re-inflated to the band floor. The [100_000, 1_000_000] band with `clamped: true` governs the guessed answers only - the 1M-suffix expansion and the unknown-model default, where the true window is unknown; both published figures sit inside the band today.+3. Operator override channels - a new `context:` block in `Brain/_brain.yaml` (`context.window_tokens`), parsed by a new `src/core/brain/policy/blocks/context.ts` block parser (not an extension of `anticipatory`, because the window governs packs, presets and compact guidance alike), and the environment variable `OPEN_SECOND_BRAIN_MODEL_CONTEXT_WINDOW` parsed beside the recall-adequacy trio in `src/core/config.ts` (substrate); the `_brain.yaml` block wins over the env var - the resolver's deliberate precedence (decision 2: config over env), not the standing env-over-config rule. Non-integer garbage in `_brain.yaml` is a block-parse validation raise.+4. `suggestContextPreset` integration - the resolver runs when no explicit window is given, and the suggest order is DELIBERATE (changed from the draft's hint-first order after external review, not preserved): explicit window first, then a table-declared or suffix-resolved window, then a `model_hints` match, then the conservative fallback. Rationale: the suggestion must name the same mapping every derived budget sizes from - the resolved window - so a table-known id that also matches a hint answers from the table on both surfaces, and an explicit `context_window_tokens` outranks a heuristic read off the id because it is the caller's own number for the deployment at hand; a hint answers only when nothing published resolves and never claims a `resolvedWindow`. The `reason` string carries what decided. An id nothing published places answers the conservative fallback here and is refused on the pack budget surfaces - never a silent default budget.+5. `brain_context_pack` contract - `max_tokens` becomes optional with `--model`/`model` added on CLI and MCP; when absent, the budget derives from the preset the resolver selects (the preset's `context_pack.max_tokens` is the curated mapping); an explicit `max_tokens` stays first-class. Decision to pin: when `max_tokens` is absent and nothing resolves (no model, no operator setting, or a model nothing published places - no table row, no suffix, no hint), the tool refuses exactly as today - never a silent default budget. `packContext` itself keeps its caller-budgeted signature.+6. Pre-compress guidance - optional `model` and resolver-derived default caps close the unbounded-addendum case.+7. Anticipatory cache - the 2_000 default yields to a window-fraction budget only when an operator setting, env var or model id actually resolves; 2_000 stays the nothing-resolved fallback so default-vault behavior is byte-identical and pinned suites do not shift.+8. Census obligations - registering the block in `validateBrainConfigDetailed` is what makes `brainConfigKnownKeys()` see the key; the config-template ratchet test is the gate; the block parse test pins acceptance and rejection because a misspelled top-level key only warns and silently defaults.++### t_4e1681b3 - preregistered judge eval++Recommended approach: build the missing measured link in three pieces - a frozen spec, a grader, and a machine-side tuning mark - reusing the bench suite's committed-fixture, seeded-sampling and run-store machinery and the `runRerankEvalGate` template.++Named decisions, with the recon's recommendations:++1. "Preregistered" means - a content-hashed spec frozen before any grading that identifies: fixture and seeded take (ids, seed, cap, strata receipt), the split rule and the derived dev/counted membership, the promotion metric with its threshold and minimum counted n, the exact threshold values of the use being validated, and the grading protocol (deterministic scorer canonical, judge advisory). Every cached grade stamps the spec hash; a spec edit invalidates prior marks.+2. Dev/counted split - hash-order split: `h = sha256Hex(seed + ":" + id)`, sort ids by `(h, id)`, first `ceil(0.3 n)` are dev, the rest counted; the derived membership lists are frozen into the spec receipt at preregistration time and the runner verifies current fixture membership against the receipt. Only dev may inform threshold selection; counted alone produces the promotion number.+3. Promotion metric - counted-split error rate against frozen gold, per (profile, use), with three conditions mirroring the in-repo gate styles: error at or below a preregistered per-use ceiling (conservative constants beside the profile table), no regression versus the deterministic baseline on the same counted items (the `rerankEvalVerdict` rule), and a minimum counted n (30 floor) below which the verdict is "not enough evidence". Metric name and ceiling live in the spec, not the grader.+4. Grade cache - verdicts are continuity records, new kind `decision_model_eval_grade` beside `decision_model_call` (ids and numbers only, `origin: "eval"` so they stay out of shadow agreement, spend counted toward the daily cost gate). Vault records are review evidence only; a hand-written record cannot mark a profile tuned.+5. Tuning mark - the machine-consumed summary is a small file under the platform state root (`src/core/platform-dirs.ts` gains its first production caller), keyed by (profile, use) and carrying the spec hash; `thresholdsTunedFor`/`holdToProfile` accept an injected optional mark reader (default none, existing callers untouched), consult it only when the source table says untuned, and accept the mark only if spec hash, fixture hash and threshold values match; a deleted mark fails closed to shadow. The mark read is a single small file with a TTL cache (hot path).+6. Decision on census registration - the mark file is machine-side state outside the vault and is deliberately NOT registered as a vault state surface in `src/core/state/surfaces.ts`; judge-eval does not touch that file (it belongs to the substrate for the cross-topic ledger row).+7. Surfaces - `o2b decision-model eval run|list` verbs plus an eval section in `report --use`; `check` gains one line naming the profile's measured state; the doctor readiness probe reflects measured/untuned state. The independent uncalibrated-provider refusal is never weakened by a measured mark.++### t_e4438152 - measured index-behind count++Recommended approach: a new exported `indexBehindCount(config): Promise<IndexBehind | null>` in the read-side diagnostics section of `src/core/search/indexer.ts`, beside `indexStatus`: one stat-only `walkVault` pass (inheriting all scope, admission-lane, extension and symlink rules with zero new scope logic) diffed against `store.listDocuments()` from a read-mode store. The walk is live, never persisted - a count frozen at scan start would read zero exactly when the operator wants to trust it.++Named decisions, with the recon's recommendations:++1. Definition - exact fastpath comparison: `unindexed` (walked path, no row), `changed` (row where mtime or size differs - the fastpath miss), `deleted` (indexed path not seen on the walk); `behind = unindexed + changed + deleted`, the same quantity the freshen child records as `lastChanged`, measured now. Documented semantics: an upper bound on content changes (touch-only counts as changed), second-granularity (same blindness as the fastpath, not fixed locally), and the deleted component needs the full walk before the diff.+2. Failure polarity - any failure (missing index, unreadable dir) returns `null`: absent, never zero; a failed measurement is not a measurement.+3. Search gating - compute only when the degradation will fire (`indexAge > INDEX_STALE_SECONDS`); fresh answers pay nothing, a stale answer pays one stat walk; `withIndexStale` gains the count and emits `detail: { ageSeconds, behindCount }` (both integers, type-compatible with `RetrievalDegradationDetail`; no envelope change, no MCP schema change - the detail object is open by design). No new degradation code, so the code enum is untouched.+4. Status surfacing - a new `index_behind` human line and `index_behind`/optional `index_behind_by_root` JSON keys on `renderFreshenStatus`/`serializeFreshenStatus`; per-root breakdown is status-only because the degradation detail rule forbids paths and cannot hold a breakdown.+5. Purity boundary - the measured value is passed into `freshenStatus` from `status.ts` so `freshenStatus` stays a pure state-file reader and the doctor's `freshenFailureCheck` cannot silently pick up the walk cost.+6. No census obligations - read-only walk, no new write sites, no new persisted state file, no new CLI verb, no new doctor exit.++### t_d7ce8baf - bench-run integrity guards++Recommended approach: a new CLI-agnostic module `src/core/bench/guards.ts` with three exports - a frozen `BENCH_REFUSAL` table with a closed `BenchRefusalKind` union (one member per preflight state P1-P7 and trace state T1-T7, on the `DEGRADATION_CODE` pattern), a `BenchRefusalError` carrying kind and detail (the `BenchEmbeddingError` pattern), and `preflightBenchRun`/`validateBenchTrace`, both throw-on-failure.++Named decisions, with the recon's recommendations:++1. Ordering - preflight runs before `createBenchRun`/`loadBenchRun`, and config resolution plus the capability gate move above run creation so a refusal can never leave an orphan run dir; trace validation runs between the evaluate re-read and the judge/report/write block, on every invocation, so fresh and resumed runs are both covered.+2. Trace strictness keys on absence, not content - a category-required field ABSENT from a persisted record is a refusal; present-but-empty is a legitimate miss; an all-questions-failed run stays publishable (score content never triggers refusal); judge errors stay advisory.+3. Faulted proactive decisions - the guard consumes `scoreProactiveRecall().faults` and refuses with the question named and the "start a fresh run" repair; `failure-modes.ts` is unchanged - guards abort, scorers score.+4. Counts check - the T7 recomputation extracts `buildReport`'s category-counting loop into a shared helper (including the standing_instruction headline-exclusion rule) rather than duplicating it, avoiding false refusals on facet runs.+5. Checkpoint strictness - `parseCheckpoint` refuses unknown phase names with a named error instead of silently filtering (consistent with the pre-knob-pinning refusal stance), and preflight refuses out-of-order/duplicate phases and missing phase artifacts (ingest done but `vault/` missing is the dangerous one); the error says the checkpoint was written by a different build where applicable.+6. Atomicity - `report.json` and per-question results move to temp+rename writes (the `writeVectorCache` pattern), making truncated traces genuinely rare; `run-store.ts` `persist` goes atomic too.+7. Identity freeze - guards add no knobs and change no measured behavior: `fixtureHash` stays content-only and `benchRunIdentityHash` is unchanged, because `report.fixture_hash` is a published cross-run comparison field; existing run ids, checkpoints and reports remain valid, no migration; a passing report stays byte-identical and guards add zero output on success.+8. Rendering - `cmdBrainBench` catches `BenchRefusalError`, emits `refused (<kind>): <detail>` naming the repair, exits non-zero; unknown errors keep propagating.++### t_50c81d5c - machine-readable query-language schema++Recommended approach: a descriptor module as the single source of truth - not a schema generated from the TypeScript type (no reflection; `SearchOptions` carries non-wire fields by design). `src/core/search/search-options-descriptor.ts` holds one typed table with a row per caller-facing field: canonical snake_case name, JSON Schema fragment (enums imported from the existing core vocabularies), CLI flag spelling and kind, surface visibility (mcp | cli | internal), and default.++Named decisions, with the recon's recommendations:++1. Derived, not copied - the substrate derives `SEARCH_INPUT_SCHEMA` in `src/mcp/search-tools.ts` from the descriptor's mcp-visible rows as a one-line filter keeping the same exported constant, proven byte-identical by an equality test before anything else ships; the lane derives the CLI `parseFlags` table from the cli-visible rows (snake_case to kebab-case mechanically), with verb-local flags (`json`, `verbose`, `auto-refresh`) staying local.+2. Parity - a compile-time `satisfies` assertion that every non-internal row key exists on `SearchOptions`, plus a unit test in the reverse direction (no mcp/cli row missing from the schema/flag derivations) - the descriptor must not be able to drift from `SearchOptions`, the very failure mode being fixed.+3. Artifact - `schemas/brain/search-query.schema.json` with `$schema: https://json-schema.org/draft/2020-12/schema` and `$id: brain.search_query.v1`, joining the existing published set (the `published-schema-contracts` file-set pin is the tripwire; the SCHEMA_IDS entry lands in the same PR). A sibling `brain.search_query_document.v1` block (as `$defs` or a second file) describes the line-oriented query_document grammar; it describes the hand-rolled parser and is validated by doc examples, not used for enforcement.+4. CLI verbs - `o2b search schema export` (file or `--stdout`) and `o2b search schema check` (regenerate and diff, exit 2 on drift), registered in `KNOWN_VERBS` in `src/cli/search.ts`. Deliberately not `o2b brain schema ...`, which already means the vault schema pack. Regeneration is a human action; CI enforces freshness via tests.+5. Doc-example tests - new `tests/docs/search-query-doc-examples.test.ts` on the retrieval-trail-doc pattern: the documented structured-query example must parse and validate against the artifact; every documented `--flag` in the scoped `o2b search "<query>"` block must be derivable from the descriptor's cli rows; every backticked `brain_search` argument in `docs/mcp.md` must be a property of the artifact. Extraction is scoped to the Search sections only; `docs/plans/**` and `docs/brainstorm/**` are excluded forever.+6. Validator extension - `tests/helpers/json-schema-subset.ts` gains `minLength`/`maxLength` (and `additionalProperties`-as-schema if the `properties` row keeps it) without weakening the core promise: an unsupported keyword is an error, never a silent pass; no full JSON Schema library dependency.+7. Compatibility neutrality - the artifact presents canonical MCP names with the descriptor mapping CLI spellings onto them; renaming CLI flags is out of scope. The vendored Hermes projection stays byte-neutral (the substrate guarantees it); if any description or bound were ever reworded, `plugins/hermes/_schemas.py` must be regenerated by hand in the same change because the anti-drift test diffs a live `tools/list`.++### t_fd842db0 - wikilink disambiguation honors vault scope++Recommended approach: filter inside `countBasenameMatches` (narrow placement) - resolve `resolveVaultScope(vault).rules` once, then per candidate page compute the vault-relative POSIX path (`toPosix(relative(vault, page.path))`) and skip the page when `matchScope(rel, rules).inScope` is false, keeping the existing entity status-scope check. Shape mirrors `page-dedup.ts`'s `basenameCollides`, the exact precedent.++Named decisions, with the recon's recommendations:++1. Placement - inside the private census, not the enumeration layer: filtering `listVaultPages` would silently shrink a dozen unrelated products (co-occurrence, repair-lane, freshness, heal-run, hygiene detectors, doctor counts, MCP query); the narrow placement can only decrement out-of-scope matches and changes nothing for in-scope files. One rule set does not require one call site - the predicate called is the same `matchScope`/`resolveVaultScope` pair the lint walkers call.+2. Boundary - `admitToIndex` is deliberately not folded in: the vault-scope module separates policy scope from lane admission on purpose, and a `Brain/state` twin exists even though it is never indexed. No changes to `src/core/vault.ts` or the vault-scope module.+3. Visibility - `countBasenameMatches` stays private, no new exports, so the visibility-surface census and surfaces registry prose stay untouched.+4. Documented edges - the docblock names both pre-existing edges: the target-itself-out-of-scope case (accept semantics unchanged) and the intended-target-was-the-ignored-twin case (the operator's remedy is fixing `vault.ignore_paths`/`include_paths`, the same remedy every other scope-aware surface shares). The write-time idempotency check already accepts either spelling, so no write storms on upgrade.+5. Not gitignore-dependent - the filter reads `Brain/_brain.yaml` plus frozen defaults through `resolveVaultScope`; no git invocation, identical behavior in a non-git vault.++### Cross-cutting substrate decisions++1. The two new config blocks land together in one reviewable diff: `cross_topic` on `BrainDreamConfig` (`src/core/brain/types.ts` near `:1450`) and the `context:` window block (near `:2030`), with policy parse/validate registration, `config-template.ts` entries and the single config-template-ratchet test update resolving both features' obligations in one pass.+2. The environment parse helper for `OPEN_SECOND_BRAIN_MODEL_CONTEXT_WINDOW` lives in `src/core/config.ts` beside the recall-adequacy trio, so the resolver in the context-window lane stays pure (parsed values in, no env reads inside).+3. The cross-topic ledger gets its identity early: `crossTopicLedgerPath` in `src/core/brain/paths.ts`, `BRAIN_CROSS_TOPIC_LEDGER_FILE` in `path-constants.ts`, and a `STATE_SURFACE_ID.crossTopicLedger` row in `src/core/state/surfaces.ts` with its `tests/core/state/surfaces.test.ts` row - so the cross-topic lane adds no census rows at all.+4. The descriptor lands with `SEARCH_INPUT_SCHEMA` derived byte-identically behind an equality test, converting the highest-blast-radius feature into an additive one before any lane starts.++## File changes++### Substrate (Task 0)++New: `src/core/brain/policy/blocks/context.ts`, `src/core/search/search-options-descriptor.ts`, `tests/core/brain/policy/context-block.test.ts`, `tests/core/search/search-query-schema-artifact.test.ts`.+Modified: `src/core/brain/types.ts`, `src/core/brain/policy.ts`, `src/core/brain/policy/validate.ts`, `src/core/brain/config-template.ts`, `tests/core/brain/config-template-ratchet.test.ts`, `src/core/config.ts`, `src/core/brain/paths.ts`, `src/core/brain/path-constants.ts`, `src/core/state/surfaces.ts`, `tests/core/state/surfaces.test.ts`, `src/mcp/search-tools.ts`.++### t_642bc2b8 cross-topic++New: `src/core/brain/dream-plan-cross-topic.ts`, `tests/core/brain/dream-cross-topic.test.ts`.+Modified: `src/core/brain/dream-plan.ts`, `src/core/brain/dream.ts`, `src/core/brain/dream-apply.ts`, `src/core/brain/dream-summary.ts`, `src/core/brain/dream-types.ts`, `src/core/brain/dream-report.ts`, plus the shape-pinning suites if they assert the changed summary additively (`tests/core/brain/dream-checkpoints.test.ts`, `tests/core/brain/dream-phase-refusal.test.ts`, `tests/core/brain/trust/operator-summary.test.ts` conditionally).++### t_a567cc12 context-window++New: `src/core/brain/model-window.ts`, `tests/core/brain/model-window.test.ts`.+Modified: `src/core/brain/context-presets.ts`, `src/mcp/brain/pack-tools.ts`, `src/cli/brain/verbs/context-pack.ts`, `src/cli/brain/verbs/context-presets.ts`, `src/cli/brain/help-text.ts`, `src/core/brain/anticipatory-cache.ts`, `tests/core/brain/context-presets.test.ts`, `tests/mcp/context-presets-tool.test.ts`, `tests/cli/brain-context-presets.test.ts`, `tests/mcp/context-pack-tool.test.ts`, `tests/cli/brain-context-pack.test.ts`, plus anticipatory-cache suites only if the default derivation lands there.++### t_4e1681b3 judge-eval++New: `src/core/decision-model/eval-spec.ts` (or kept inside `questions.ts`), `src/core/decision-model/eval/take.ts`, `src/core/decision-model/eval/grade.ts`, `src/core/decision-model/eval/mark.ts`, `tests/fixtures/decision-model/`, new decision-model eval tests.+Modified: `src/core/decision-model/questions.ts`, `src/core/decision-model/record.ts`, `src/core/decision-model/config.ts`, `src/core/decision-model/diagnostics.ts`, `src/cli/decision-model.ts`, `src/core/platform-dirs.ts`, `src/cli/command-manifest.ts` (decision-model entry; owning lane), `src/core/doctor-readiness.ts`, `src/core/install/ownership.ts`, `docs/decision-models/providers.md` and siblings.++### t_e4438152 freshness++New: `tests/core/search/behind-count.test.ts`.+Modified: `src/core/search/indexer.ts`, `src/core/search/pipeline/outcome.ts`, `src/core/search/search.ts`, `src/core/search/freshen.ts`, `src/core/search/index.ts`, `src/cli/search/verbs/status.ts`, `tests/core/search/freshen-search.test.ts` (or a sibling gate test), `tests/core/search/relational-path.test.ts` (detail literal), `tests/cli/search-status-freshen.test.ts`.++### t_d7ce8baf bench guards++New: `src/core/bench/guards.ts`, `tests/core/bench/guards.test.ts`.+Modified: `src/core/bench/phases.ts`, `src/core/bench/run-store.ts`, `src/cli/brain/verbs/bench.ts`, `tests/core/bench/phases.test.ts`, `tests/core/bench/run-store.test.ts`.++### t_50c81d5c schema artifact++New: `src/cli/search/verbs/schema-export.ts`, `schemas/brain/search-query.schema.json`, `tests/docs/search-query-doc-examples.test.ts`.+Modified: `src/cli/search/verbs/query.ts`, `src/cli/search.ts`, `tests/helpers/json-schema-subset.ts`, `tests/core/brain/published-schema-contracts.test.ts`, `package.json` (optional `search-schema` scripts).++### t_fd842db0 wikilink scope++Modified: `src/core/brain/link-graph/bridge-discovery.ts`, `tests/core/brain/bridge-discovery.test.ts`.++### Integrator++Modified: `docs/cli-reference.md`, `docs/mcp.md`, `src/cli/command-manifest.ts` (the search schema verb row, after the judge-eval lane lands), `CHANGELOG.md` (consolidated entries for the features whose recons demand them: `t_e4438152`, `t_fd842db0`, and `t_642bc2b8` per its CLAUDE.md versioning-discipline note).++## Risks and open questions++1. Served `tools/list` is a frozen public surface. The descriptor's derivation must be byte-identical on day one - the equality test is the gate - and the vendored Hermes Python projection stays byte-neutral with it; any schema byte change would silently require a manual Python edit and would only be caught after the churn by the live-server anti-drift test.+2. Config keys that silently default. A misspelled top-level key only warns (`validate.ts:203-213`), so a typo'd `context:` or `cross_topic` block resolves to defaults with no error; the block parse tests must pin acceptance and rejection, and the resolved `source` should be visible in preset-suggest output so an operator can see their key took effect.+3. Cross-topic generalization vs dedup nomination. A cross-bucket lexical cluster is simultaneously the strongest generalization evidence and a near-certain future dedup/digest nomination of the promoted rule (thresholds 0.8/0.6); the verbatim-principle and content-slug mitigations reduce it, and the dedup-skip follow-up is named but not built. The sign-derivation fallback (tier 3 "assume opposite" on a synthetic topic) and stale-no-evidence retirement of a never-applied rule need an explicit decision during implementation.+4. Host model visibility is conditional. No caller knows the host model today; `ServerContext` carries no model id. The resolver upgrades every hint into a real number, but a host that never forwards its id still gets the 200_000 default; tool descriptions and help text must say so.+5. Byte-identical blast radius on pinned defaults. Anticipatory cache (2_000), retrieval plan (2_000) and bench (1_000) budgets are pinned by tests and persisted stamps; window-derived defaults may only fire when something actually resolves, or those suites and cached stamps shift. Context-window and bench lanes are separate lanes precisely so a pin break is attributable.+6. Bench false refusals. T4 must key on field absence only; T5's refusal repeats under `--resume` (resume re-evaluates the same persisted decisions) so the detail must say a fresh run is required; T7 must reuse `buildReport`'s aggregation. The strongest false-refusal check is byte stability: a passing report identical to the pre-guard shape and every existing bench test green unchanged.+7. Flaky mtime tests. Second-granular mtime makes behind-count tests clock-edge sensitive; tests must set explicit mtimes (`utimesSync`) or sleep past a second boundary, as the existing fastpath tests already do.+8. Preregistration theater and grade-cache poisoning. A spec committed after grades were inspected looks preregistered but is not: spec and fixtures land in one reviewable commit before the runner is usable, and the authoritative mark is written solely by the eval command machine-side, with grade records carrying correlated `decision_model_call` ids so a reviewer can match grades to real spend.+9. Walk cost on large vaults. The stale-only gate bounds the behind-count walk to the abnormal state, but repeated stale searches (freshen off, backoff active) each pay a full stat walk inside the long-lived MCP server; the escape hatch is a per-process memo keyed on `dbPath + lastIndexedAt` with a short TTL - never persistence to the state file.+10. Open question - retirement semantics for `inferred` cross-topic rules: whether stale-no-evidence should eventually retire a never-applied promoted rule or a `pinned`-style exemption applies. Decide during implementation of `t_642bc2b8`; the default (no code change) is the existing `planAutoRetires` behavior.+11. Open question - whether the command manifest enumerates the new `o2b search schema` verbs. If it does, the row is added by the integrator task after the judge-eval lane (the manifest's owning lane) has landed, so the two never edit the file concurrently.diff --git a/docs/brainstorm/cycle-20261020/plan.md b/docs/brainstorm/cycle-20261020/plan.mdnew file mode 100644index 00000000..6cb0d2fc--- /dev/null+++ b/docs/brainstorm/cycle-20261020/plan.md@@ -0,0 +1,171 @@+# Cycle 20261020 - implementation plan (substrate + five parallel lanes + integrator)++Implementation follows consultant Variant 1: Task 0 (substrate) lands first, serial, on one lane; then five lanes run in parallel on provably disjoint file sets; a final integrator task consolidates docs, dedups the manifest and runs the full QA gates. Every feature below carries its kanban card id.++## Lane structure++| Lane | Card(s) | One-line scope |+|------|---------|----------------|+| Substrate (Task 0) | parts of `t_642bc2b8`, `t_a567cc12`, `t_50c81d5c` | Config quartet, env helper, ledger path constants and state-surface row, descriptor with byte-identical `SEARCH_INPUT_SCHEMA` |+| A - cross-topic | `t_642bc2b8` | Cross-topic rule promotion in the dream pass |+| B - context-window | `t_a567cc12` | Model-window resolver and its consumers |+| C - judge-eval | `t_4e1681b3` | Preregistered eval, grade cache and tuning mark |+| D - freshness + wikilink | `t_e4438152`, `t_fd842db0` | Measured index-behind count and scope-honest wikilink disambiguation |+| E - bench + schema artifact | `t_d7ce8baf`, `t_50c81d5c` | Bench-run integrity guards; descriptor consumption, committed artifact, export/check verbs |+| I - integrator | all | Consolidated docs, manifest dedup, CHANGELOG, full QA gates |++Lanes start only after Task 0 lands. Inside a lane, tasks are serial.++## Cross-lane contract++- **Commits**: every lane commits with explicit paths only, `git commit --only <paths>` (stage nothing else). Never `git add -A` and never a bare `git commit -am`.+- **Waiting on the substrate**: a lane that needs a substrate file (any Task 0 file) polls `git log --oneline -1 -- <file>` every 30 seconds with a 12-minute cap. If the substrate commit has not appeared when the cap is reached, the lane stops and reports instead of building workarounds.+- **Formatting and linting**: lanes run `bun run fmt` and `bun run lint` scope-restricted to their own files only (oxfmt/oxlint accept explicit paths). If the formatter wants to touch a file outside the lane's set, that is pre-existing drift - surface it, do not fold it in.+- **Exclusive ownership**: a lane never edits a file in another lane's set. Where recons overlap, the resolution below is binding.+- **Tests**: a lane runs the full suite before its final commit but is only responsible for greenness of tests its own files affect; cross-suite breakage is surfaced to the orchestrator, not patched over.++## Resolved file-ownership conflicts++1. `src/cli/command-manifest.ts` - Lane C (judge-eval) is the owning lane during the lane phase (its recon names the file; the decision-model entry gains the eval verbs). Lane E's `o2b search schema` verb, if the manifest enumerates search verbs, gets its row in Task I after Lane C has landed.+2. `docs/cli-reference.md` - touched by three features (freshness rows at `:2247` and `:2084-2088`, bench refusal contract near `:578-583`, schema export/check section in the Search region near `:1977-2004`). No lane touches it; Task I owns it.+3. `docs/mcp.md` - touched by freshness (`retrieval_trail` detail at `:1991-2000`) and the schema artifact (artifact line near `:461-474`). Task I owns it.+4. `CHANGELOG.md` - demanded by the freshness and wikilink recons (both list it in their files to touch) and by the cross-topic recon's CLAUDE.md versioning-discipline note. Task I writes one consolidated Unreleased section covering those three features; the other recons name no CHANGELOG obligation, and the version bump stays with the pr-prepare phase.+5. `src/core/state/surfaces.ts` - Task 0 only (the `crossTopicLedger` row). Lane C's tuning mark is machine-side state outside the vault and is deliberately not registered as a vault state surface, so Lane C does not touch this file.+6. `src/mcp/search-tools.ts` - Task 0 only (the byte-identical `SEARCH_INPUT_SCHEMA` derivation). Lane E consumes the descriptor but never edits the served schema.+7. `src/core/bench/phases.ts` - appears in the context-window recon only as an optional second-wave adoption, which is out of scope this cycle; Lane E owns the file exclusively.+8. `src/core/config.ts`, `src/core/brain/types.ts`, `src/core/brain/policy.ts`, `src/core/brain/policy/validate.ts`, `src/core/brain/config-template.ts`, `src/core/brain/paths.ts`, `src/core/brain/path-constants.ts` - Task 0 only; lanes consume what it exports.++## Lane-exclusive file sets++- **Task 0**: `src/core/brain/types.ts`, `src/core/brain/policy/blocks/context.ts`, `src/core/brain/policy.ts`, `src/core/brain/policy/validate.ts`, `src/core/brain/config-template.ts`, `tests/core/brain/config-template-ratchet.test.ts`, `tests/core/brain/policy/context-block.test.ts`, `src/core/config.ts`, `src/core/brain/paths.ts`, `src/core/brain/path-constants.ts`, `src/core/state/surfaces.ts`, `tests/core/state/surfaces.test.ts`, `src/core/search/search-options-descriptor.ts`, `src/mcp/search-tools.ts`, `tests/core/search/search-query-schema-artifact.test.ts`.+- **Lane A**: `src/core/brain/dream-plan-cross-topic.ts`, `src/core/brain/dream-plan.ts`, `src/core/brain/dream.ts`, `src/core/brain/dream-apply.ts`, `src/core/brain/dream-summary.ts`, `src/core/brain/dream-types.ts`, `src/core/brain/dream-report.ts`, `tests/core/brain/dream-cross-topic.test.ts`, and, if they pin the changed-summary shape additively, `tests/core/brain/dream-checkpoints.test.ts`, `tests/core/brain/dream-phase-refusal.test.ts`, `tests/core/brain/trust/operator-summary.test.ts`.+- **Lane B**: `src/core/brain/model-window.ts`, `src/core/brain/context-presets.ts`, `src/mcp/brain/pack-tools.ts`, `src/cli/brain/verbs/context-pack.ts`, `src/cli/brain/verbs/context-presets.ts`, `src/cli/brain/help-text.ts`, `src/core/brain/anticipatory-cache.ts`, `tests/core/brain/model-window.test.ts`, `tests/core/brain/context-presets.test.ts`, `tests/mcp/context-presets-tool.test.ts`, `tests/cli/brain-context-presets.test.ts`, `tests/mcp/context-pack-tool.test.ts`, `tests/cli/brain-context-pack.test.ts`, plus anticipatory-cache suites only if the default derivation lands there.+- **Lane C**: `src/core/decision-model/questions.ts`, `src/core/decision-model/eval-spec.ts` (if split out), `src/core/decision-model/eval/`, `src/core/decision-model/record.ts`, `src/core/decision-model/config.ts`, `src/core/decision-model/diagnostics.ts`, `src/cli/decision-model.ts`, `src/core/platform-dirs.ts`, `src/cli/command-manifest.ts`, `src/core/doctor-readiness.ts`, `src/core/install/ownership.ts`, `docs/decision-models/`, `tests/fixtures/decision-model/`, new tests under `tests/core/decision-model/`.+- **Lane D**: `src/core/search/indexer.ts`, `src/core/search/pipeline/outcome.ts`, `src/core/search/search.ts`, `src/core/search/freshen.ts`, `src/core/search/index.ts`, `src/cli/search/verbs/status.ts`, `src/core/brain/link-graph/bridge-discovery.ts`, `tests/core/search/behind-count.test.ts`, `tests/core/search/freshen-search.test.ts`, `tests/core/search/relational-path.test.ts`, `tests/cli/search-status-freshen.test.ts`, `tests/core/brain/bridge-discovery.test.ts`.+- **Lane E**: `src/core/bench/guards.ts`, `src/core/bench/phases.ts`, `src/core/bench/run-store.ts`, `src/cli/brain/verbs/bench.ts`, `src/cli/search/verbs/query.ts`, `src/cli/search/verbs/schema-export.ts`, `src/cli/search.ts`, `schemas/brain/search-query.schema.json`, `tests/core/bench/guards.test.ts`, `tests/core/bench/phases.test.ts`, `tests/core/bench/run-store.test.ts`, `tests/helpers/json-schema-subset.ts`, `tests/core/brain/published-schema-contracts.test.ts`, `tests/docs/search-query-doc-examples.test.ts`, `package.json` (optional scripts only).+- **Task I**: `docs/cli-reference.md`, `docs/mcp.md`, `CHANGELOG.md`, `src/cli/command-manifest.ts` (schema verb row only, after Lane C lands).++The lane sets are pairwise disjoint; every intersection above is resolved to a single owner or deferred to Task I.++## Tasks++### Task 0a: config quartet and env helper (substrate, commit 1)+- **Files**: `src/core/brain/types.ts` (`cross_topic` block on `BrainDreamConfig` near `:1450`; new `context` window block near `:2030`), `src/core/brain/policy/blocks/context.ts` (new block parser), `src/core/brain/policy.ts` (`cross_topic` parse plus block re-exports), `src/core/brain/policy/validate.ts` (register both blocks; `brainConfigKnownKeys()` follows), `src/core/brain/config-template.ts` (commented-default entries for both), `tests/core/brain/config-template-ratchet.test.ts`, `tests/core/brain/policy/context-block.test.ts` (new), `src/core/config.ts` (`OPEN_SECOND_BRAIN_MODEL_CONTEXT_WINDOW` parse helper beside the recall-adequacy trio, config-over-env per the resolver precedence).+- **Acceptance**: `tests/core/brain/policy/context-block.test.ts` pins block acceptance and rejection (garbage raises, out-of-range numeric accepted and passed through unclamped) on the `recall-inject-block` pattern; `tests/core/brain/config-template-ratchet.test.ts` passes with both new keys present in the generated template; absent blocks leave default behavior byte-identical.+- **Depends on**: none. Lands first.++### Task 0b: cross-topic ledger identity and state surface (substrate, commit 2)+- **Files**: `src/core/brain/paths.ts` (`crossTopicLedgerPath`), `src/core/brain/path-constants.ts` (`BRAIN_CROSS_TOPIC_LEDGER_FILE`), `src/core/state/surfaces.ts` (`STATE_SURFACE_ID.crossTopicLedger` + row, following the rollup ledger row), `tests/core/state/surfaces.test.ts` (the new row).+- **Acceptance**: `tests/core/state/surfaces.test.ts` passes with the `Brain/cross-topic-rules.json` surface registered; the state-surface architecture census stays green with no unbound new row.+- **Depends on**: none (parallel with 0a is acceptable; both precede 0c only in review order).++### Task 0c: search-options descriptor with byte-identical derivation (substrate, commit 3)+- **Files**: `src/core/search/search-options-descriptor.ts` (new; typed field table - canonical snake_case name, schema fragment with enums imported from `FTS_MATCH_MODES`/`DISCLOSURE_MODES`/`RECALL_PROFILE_NAMES`/`SEARCH_KINDS`, CLI flag spelling and kind, surface visibility, default; compile-time `satisfies` parity against `SearchOptions`), `src/mcp/search-tools.ts` (`SEARCH_INPUT_SCHEMA` becomes a one-line derivation filtering mcp-visible rows, same exported constant), `tests/core/search/search-query-schema-artifact.test.ts` (new; the derived schema deep-equals the previously literal object).+- **Acceptance**: the equality test proves the derived `SEARCH_INPUT_SCHEMA` is byte-identical to the pre-change literal, so `tools/list` and the vendored Hermes projection are untouched; the parity assertion and a reverse-direction test show no mcp/cli row missing from the derivation. Existing `tests/mcp` suites that read `tool.inputSchema` stay green unchanged.+- **Depends on**: none. All three substrate commits land before any lane starts.++### Task A1: cross-topic planner and ledger (Lane A, card `t_642bc2b8`)+- **Files**: `src/core/brain/dream-plan-cross-topic.ts` (new; pure planner - cross-bucket jaccard detection over confirmed prefs using `tokenise`/`jaccard`, deterministic ordering, content-derived `cross-<sha256-12>` slug, budget read against `Brain/cross-topic-rules.json` - plus ledger helpers on `atomicWriteFileSync`), `src/core/brain/dream-plan.ts` (`CrossTopicRulePlan` entry, `PlanState.crossTopicRules`, `emptyPlan()` init), `tests/core/brain/dream-cross-topic.test.ts` (new).+- **Acceptance**: `tests/core/brain/dream-cross-topic.test.ts` proves: cross-bucket detection fires at the configured `min_topics`/`jaccard`; same-bucket clusters never fire; config gating (absent block = off, byte-identical); content-slug dedup (same source set maps to one file, already-present or retired slug skips); one promotion per owner token per calendar day with the date from the injected `now`; a budgeted-out pass plans nothing. Modeled on `tests/core/brain/rollup-ladder.test.ts`.+- **Depends on**: Task 0a (config block), Task 0b (ledger path and surface).++### Task A2: dream pass wiring, apply, summary and report (Lane A)+- **Files**: `src/core/brain/dream.ts` (planner call after `planRefresh`, before the `hasStateChange` gate; `hasStateChange` includes the plan; thread into apply/report/summary inputs), `src/core/brain/dream-apply.ts` (write loop in `writePreferences` via `writePreferenceTxn`, `provenance: "inferred"`, `overwrite: false`), `src/core/brain/dream-summary.ts` (both summary shapes plus the synthesize phase metric), `src/core/brain/dream-types.ts` (additive `DreamRunSummary` field), `src/core/brain/dream-report.ts` (dream event body field; ledger write beside `writeRollupLedger`, only when fired), `tests/core/brain/dream-checkpoints.test.ts` / `tests/core/brain/dream-phase-refusal.test.ts` / `tests/core/brain/trust/operator-summary.test.ts` (only if they pin the changed shapes), plus an end-to-end dream run in `tests/core/brain/dream-cross-topic.test.ts` on the `dream-destructive-gate` pattern.+- **Acceptance**: the end-to-end test shows a fired promotion produces a written unconfirmed preference with `evidenced_by` wikilinks and a `related` lineage, counts as a state change, budgets per owner per day, and leaves a below-threshold pass byte-identical (no-op summary, no log write); sources are never modified or retired; the state-surface and write-site censuses stay green because the ledger routes through the shared atomic writer.+- **Depends on**: Task A1.++### Task B1: model-window resolver (Lane B, card `t_a567cc12`)+- **Files**: `src/core/brain/model-window.ts` (new; exact-id table with provenance notes, named constants `DEFAULT_MODEL_CONTEXT_WINDOW_TOKENS = 200_000` / `MIN = 100_000` / `MAX = 1_000_000`, `declaredModelContextWindowTokens`, `structuralModelContextWindowTokens` (trailing delimited `1m` suffix only), `resolveModelContextWindowTokens` returning `{ windowTokens, source, clamped }`; pure - no fs, no env reads, parsed values in), `tests/core/brain/model-window.test.ts` (new).+- **Acceptance**: `tests/core/brain/model-window.test.ts` pins table exactness, suffix positives and near-misses (`-1m` inside a larger token does not match), clamping in both directions with `clamped: true`, precedence config > env > table > suffix > default, and the unknown-model 200_000 default; no family substring ever resolves.+- **Depends on**: Task 0a (for the operator `context.window_tokens` key and the env helper's parsed value shape; the resolver itself consumes parsed numbers).++### Task B2: preset suggestion resolution (Lane B)+- **Files**: `src/core/brain/context-presets.ts` (`suggestContextPreset` resolves the window through the model-window resolver when no explicit window is given; `reason` carries the source; hint match and explicit window keep today's exact answers), `src/mcp/brain/pack-tools.ts` (suggest operation, `:896-908`), `src/cli/brain/verbs/context-presets.ts` (suggest path resolves from `--model` alone), `src/cli/brain/help-text.ts` (usage strings at `:1085`), `tests/core/brain/context-presets.test.ts` (existing cases stay green byte-identically; add model-only cases such as `gemini-2.5-pro-1m`), `tests/mcp/context-presets-tool.test.ts`, `tests/cli/brain-context-presets.test.ts` (`--model`-only case).+- **Acceptance**: all existing `context-presets` pins pass unchanged; a model-only call resolves a window (suffix or table or default) and the reason discloses the source; a preset hint match never masquerades as a resolved window in the same call.+- **Depends on**: Task B1.++### Task B3: context pack and pre-compress defaults (Lane B)+- **Files**: `src/mcp/brain/pack-tools.ts` (`brain_context_pack`: `max_tokens` optional, `model` added, schema `required` relaxed at `:1214`; `brain_pre_compress_pack`: optional `model` plus resolver-derived default caps; schema blocks updated), `src/cli/brain/verbs/context-pack.ts` (`--max-tokens` optional, `--model` added), `tests/mcp/context-pack-tool.test.ts`, `tests/cli/brain-context-pack.test.ts`.+- **Acceptance**: explicit `max_tokens` behaves exactly as before; omission with a resolvable model derives the preset budget for the resolved window; omission with nothing resolvable refuses exactly as today (the pinned decision - never a silent default budget); the pre-compress unbounded-addendum case closes with resolver-derived caps. The vendored Hermes schemas stay untouched because `brain_search` is not part of this change.+- **Depends on**: Task B1 (and Touches `pack-tools.ts` jointly with B2 inside Lane B, so serial within the lane).++### Task B4: anticipatory-cache window default (Lane B, conditional)+- **Files**: `src/core/brain/anticipatory-cache.ts` (window-fraction default only when an operator setting, env value or model id resolves; `DEFAULT_ANTICIPATORY_MAX_TOKENS = 2_000` stays the nothing-resolved fallback), relevant anticipatory-cache suites.+- **Acceptance**: with nothing resolvable every existing anticipatory pin passes unchanged (2_000); with a resolved window the derived budget appears and is disclosed; no persisted stamp changes in the default-vault case.+- **Depends on**: Task B1. If the derivation cannot be kept strictly additive for the pinned suites, this task is dropped and the fallback constant stands - report rather than force it.++### Task C1: preregistered spec and seeded take (Lane C, card `t_4e1681b3`)+- **Files**: `src/core/decision-model/questions.ts` (per-use spec constants: fixture reference, seed, split rule, frozen membership receipt, metric, ceiling, min n, pinned threshold values; canonical spec-hash helper; optionally `src/core/decision-model/eval-spec.ts` if split out), `src/core/decision-model/eval/take.ts` (new; hash-order split `sha256Hex(seed + ":" + id)`, dev = first `ceil(0.3 n)`, membership frozen at preregistration, runner verification against the receipt), `tests/fixtures/decision-model/` (committed take fixtures per use, gold labels in the closed expectation vocabulary), new spec-integrity and split tests.+- **Acceptance**: spec hash is stable; a spec missing any required element is a construction error; the split is deterministic, reorder-stable, dev/counted disjoint, and the receipt matches derivation; spec and fixtures land in one reviewable commit before the runner exists.+- **Depends on**: none (Lane C is self-contained until C3).++### Task C2: grader and grade records (Lane C)+- **Files**: `src/core/decision-model/eval/grade.ts` (new; runner in the `runRerankEvalGate` mold - materialize fixture vault, `runDecision` per item with `recordOrigin: "eval"`, deterministic scorer canonical, judge advisory, spend counted toward the daily cost gate), `src/core/decision-model/record.ts` (`DECISION_MODEL_EVAL_GRADE_KIND` + `listDecisionModelEvalGrades`), new grading tests.+- **Acceptance**: grading against `tests/helpers/fake-decision-provider.ts` caches `decision_model_eval_grade` records carrying the spec hash, profile, use, seed, item ids, boolean verdicts, metric and counted n; records carry `origin: "eval"` and stay out of rerank shadow agreement (`diagnostics.ts:453` invariant); malformed records are skipped with a named note.+- **Depends on**: Task C1.++### Task C3: tuning mark and measured gate (Lane C)+- **Files**: `src/core/decision-model/eval/mark.ts` (new; write/read/validate the machine-side mark, TTL cache), `src/core/platform-dirs.ts` (state-root helper - the module's first production caller), `src/core/decision-model/questions.ts` + `src/core/decision-model/config.ts` (`thresholdsTunedFor`/`holdToProfile` accept an injected optional mark reader, default none; `resolveDecisionModelConfig` threads it), `src/core/install/ownership.ts` (machine-side state enumeration), new gate tests.+- **Acceptance**: with a valid mark a previously shadow-only use runs `enforce`; a stale or foreign spec hash, changed fixture hash, or changed threshold values keep it in shadow; with no mark file everything behaves exactly as today; the mark is written only when counted error meets the ceiling, no-regression holds and n is met (three-arm verdict per `extract-prefilter.ts:180-185`); `tests/core/decision-model/profiles-all-uses.test.ts` and `presets-profiles.test.ts` pass unchanged; the uncalibrated-provider refusal is untouched.+- **Depends on**: Task C2.++### Task C4: eval surfaces and manifest (Lane C)+- **Files**: `src/core/decision-model/diagnostics.ts` (`check` names the measured state and lists cached grades; report gains the eval section), `src/cli/decision-model.ts` (`eval run` / `eval list` verbs, USAGE string, dispatcher), `src/cli/command-manifest.ts` (decision-model entry - Lane C owns this file), `src/core/doctor-readiness.ts` (readiness probe reflects measured/untuned state), `docs/decision-models/providers.md` and siblings (the measured path narrative), listing tests.+- **Acceptance**: `eval list` round-trips records, renders prose and `--json`, rejects malformed records by skipping with a named note; `check` prints untuned / measured under spec hash X / baseline; the manifest lists the new verbs; the doctor probe reflects the measured state.+- **Depends on**: Tasks C1-C3.++### Task D1: indexBehindCount (Lane D, card `t_e4438152`)+- **Files**: `src/core/search/indexer.ts` (new `indexBehindCount(config): Promise<IndexBehind | null>` in the read-side diagnostics section; stat-only `walkVault` diffed against `Store.listDocuments()` from a read-mode open; exact fastpath comparison; `null` on any failure), `src/core/search/index.ts` (re-export beside `indexStatus`), `tests/core/search/behind-count.test.ts` (new).+- **Acceptance**: `tests/core/search/behind-count.test.ts` classifies on a temp vault: added file, edited file (explicit `utimesSync` mtime bump), touch-only file (counts as changed - upper-bound semantics documented), deleted file, ignored path not counted, admission-lane path not counted, missing index returns `null`.+- **Depends on**: none.++### Task D2: degradation flow-through (Lane D)+- **Files**: `src/core/search/pipeline/outcome.ts` (`withIndexStale` accepts the behind count; detail becomes `{ ageSeconds, behindCount }`), `src/core/search/search.ts` (compute under the `indexAge > INDEX_STALE_SECONDS` gate, once per `search()` above the cache branch; hand to `served`), `tests/core/search/freshen-search.test.ts` (or a sibling gate test), `tests/core/search/relational-path.test.ts` (update the `index-stale` detail literal where the test actually crosses the walk gate).+- **Acceptance**: a stale index reports `detail.behindCount` matching the seeded delta; a fresh index emits no code and performs no walk; a `null` measurement still emits `ageSeconds` alone; the MCP contract needs no schema change (open detail object) and no new degradation code appears.+- **Depends on**: Task D1.++### Task D3: status freshen block (Lane D)+- **Files**: `src/core/search/freshen.ts` (`FreshenStatus` + `renderFreshenStatus` + `serializeFreshenStatus` extended; the measured value is a passed-in argument so `freshenStatus` stays a pure state-file reader), `src/cli/search/verbs/status.ts` (compute via `indexBehindCount` when `status.exists`; thread into the freshen block), `tests/cli/search-status-freshen.test.ts` (human line and `--json` keys, column alignment).+- **Acceptance**: status prints `index_behind:` with the live count (or `(not measured)` on `null`) and serializes `index_behind` (plus optional `index_behind_by_root`); the doctor's `freshenFailureCheck` is untouched and picks up no walk cost; label alignment assertions stay green.+- **Depends on**: Task D1.++### Task D4: wikilink census scope filter (Lane D, card `t_fd842db0`)+- **Files**: `src/core/brain/link-graph/bridge-discovery.ts` (`countBasenameMatches` resolves `resolveVaultScope(vault).rules` once above the loop and skips pages whose vault-relative POSIX path (`toPosix(relative(vault, page.path))`) fails `matchScope`; docblock names the vault-scope rule beside the entity status rule and the target-itself-out-of-scope edge; no new exports), `tests/core/brain/bridge-discovery.test.ts` (new cases beside the existing ambiguity pin at `:189-201`).+- **Acceptance**: new tests: twin under an operator-ignored dir yields the basename form; twin under a default-ignored dir absent from `DEFAULT_SKIP_DIRS` (`node_modules/`, `Brain/.snapshots/`, `.open-second-brain/`) yields the basename form - the case that fails today; twin outside an `include_paths` allowlist root yields the basename form; the existing in-scope-twin case passes unchanged byte-identically; `bun run link-ratchet:check` passes; visibility-surface census stays green (no new exports).+- **Depends on**: none (independent of D1-D3; serial within Lane D).++### Task E1: bench guards module (Lane E, card `t_d7ce8baf`)+- **Files**: `src/core/bench/guards.ts` (new; frozen `BENCH_REFUSAL` table + closed `BenchRefusalKind` union covering P1-P7 and T1-T7, `BenchRefusalError` with kind and detail, `preflightBenchRun`, `validateBenchTrace`), `tests/core/bench/guards.test.ts` (new).+- **Acceptance**: `tests/core/bench/guards.test.ts` covers one case per refusal kind on hand-built fixtures: unwritable runs dir, fresh-run collision (prior checkpoint survives and `--resume` is suggested), corrupt checkpoint JSON names the file, unknown and out-of-order `completed_phases`, ingest-done-with-vault-deleted, retrieve-done-with-results-deleted, fixture cross-reference defects naming the question id, and per-family trace cases (missing result, truncated JSON, id mismatch, absent category field refused while present-but-empty passes, extra result file, counts mismatch via the shared counting helper).+- **Depends on**: none.++### Task E2: bench pipeline wiring (Lane E)+- **Files**: `src/core/bench/phases.ts` (move config resolution and the capability gate above run creation; call preflight before `createBenchRun`/`loadBenchRun`; call `validateBenchTrace` between the evaluate re-read and the judge/report/write block; atomic temp+rename writes for results and `report.json`; extract the shared category-counting helper from `buildReport`), `src/core/bench/run-store.ts` (`parseCheckpoint` refuses unknown phase names; expose `readBenchCheckpoint`; atomic `persist`), `src/cli/brain/verbs/bench.ts` (catch `BenchRefusalError`, render `refused (<kind>): <detail>` naming the repair, exit non-zero), `tests/core/bench/phases.test.ts`, `tests/core/bench/run-store.test.ts`.+- **Acceptance**: env-garbage provider and capability-gate refusals leave no run dir behind; a tampered run dir is refused by name before scoring; a passing small fixture produces a report byte-identical to the pre-guard shape; `benchRunIdentityHash` and `fixtureHash` frozen-hash values are unchanged; every existing bench test passes; guards add zero stdout on success.+- **Depends on**: Task E1.++### Task E3: CLI flag derivation from the descriptor (Lane E, card `t_50c81d5c`)+- **Files**: `src/cli/search/verbs/query.ts` (`parseFlags` derived from the descriptor's cli-visible rows, snake_case to kebab-case mechanically; verb-local flags `json`/`verbose`/`auto-refresh` stay local; per-surface bounds preserved - CLI keeps `SEARCH_LIMIT_MAX`, uncapped query, and the documented `semantic` tri-state asymmetry), new parity tests for the flag table.+- **Acceptance**: the derived flag table accepts exactly the flags the literal table accepted today (existing `o2b search` CLI tests pass unchanged); a reverse-direction test shows every cli row is represented and every non-internal row key exists on `SearchOptions` (with the substrate's compile-time assertion covering the forward direction).+- **Depends on**: Task 0c (waits on the descriptor by the cross-lane contract).++### Task E4: committed artifact and export/check verbs (Lane E)+- **Files**: `schemas/brain/search-query.schema.json` (new; `$schema` draft 2020-12, `$id: brain.search_query.v1`; sibling `brain.search_query_document.v1` block as `$defs` or a second file describing the structured query-document grammar), `src/cli/search/verbs/schema-export.ts` (new; `export` writes the file or `--stdout`), `src/cli/search.ts` (`schema` in `KNOWN_VERBS`, case, import), `tests/core/brain/published-schema-contracts.test.ts` (`SCHEMA_IDS` gains the file; generator check deep-compares descriptor output with the file on disk), `tests/helpers/json-schema-subset.ts` (add `minLength`/`maxLength` and `additionalProperties`-as-schema; unsupported keyword still throws).+- **Acceptance**: the published-schema file-set pin passes only with the `SCHEMA_IDS` entry (the tripwire fires in the same change); the descriptor-vs-file generator check passes; `o2b search schema check` exits 2 on injected drift and 0 on a clean tree; the subset validator rejects an unsupported keyword with an error, never a silent pass.+- **Depends on**: Task E3.++### Task E5: doc-example tests (Lane E)+- **Files**: `tests/docs/search-query-doc-examples.test.ts` (new; on the `retrieval-trail-doc` pattern), `package.json` (optional `search-schema` / `search-schema:check` scripts).+- **Acceptance**: the documented structured-query example under "Structured recall query documents" parses and validates against the committed artifact; every intent token in the documented grammar sentence appears in the artifact's enum; every `--flag` in the scoped `o2b search "<query>"` block of `docs/cli-reference.md` is derivable from the descriptor's cli rows; every backticked `brain_search` argument in `docs/mcp.md` is a property of the artifact; extraction stays scoped to the Search sections and never reads `docs/plans/**` or `docs/brainstorm/**`.+- **Depends on**: Task E4.++### Task I: integrator - consolidated docs, manifest dedup, full QA (serial, after all lanes)+- **Files**: `docs/cli-reference.md` (freshness: `index-stale` row gains `detail.behindCount` at `:2247`, status freshen block and JSON field list at `:2084-2088`; bench: the `brain bench memory` refusal contract near `:578-583`; schema: `o2b search schema export|check` in the Search section near `:1977-2004`), `docs/mcp.md` (`retrieval_trail` paragraph names `behindCount` at `:1991-2000`; artifact line with its `$id` near the `brain_search` paragraph `:461-474`), `CHANGELOG.md` (one consolidated Unreleased section covering `t_e4438152`, `t_fd842db0` and `t_642bc2b8` - the features whose recons demand an entry; no version bump here, pr-prepare owns that), `src/cli/command-manifest.ts` (the `o2b search schema` row, only if the manifest enumerates search verbs, after Lane C has landed).+- **Acceptance**: the doc-example tests from Task E5 stay green after the doc edits (their extraction is scoped to Search sections, so the freshness and bench edits cannot break them); the docs-drift-sensitive suites (`tests/docs/retrieval-trail-doc.test.ts`) stay green; then the full local QA gates in CI order pass: `bun run typecheck`, `bun run lint`, `bun run fmt:check` on the branch, and the full `bun run test` suite.+- **Depends on**: all lanes (A1-A2, B1-B4, C1-C4, D1-D4, E1-E5).++## Suggested commit boundaries++- Substrate: three commits (0a config quartet + env helper, 0b ledger identity + surface, 0c descriptor + derivation), each `feat(substrate): ...` or the lane's conventional scope, committed with explicit paths only.+- Lanes: one commit per task (`feat(dream): ...`, `feat(context): ...`, `feat(decision-model): ...`, `feat(search): ...` / `feat(links): ...`, `feat(bench): ...` / `feat(search): ...`).+- Integrator: one `docs(cycle): ...` commit plus any manifest fixup; the brainstorm commit itself predates all of these.diff --git a/docs/brainstorm/cycle-20261020/variants.md b/docs/brainstorm/cycle-20261020/variants.mdnew file mode 100644index 00000000..c21d539f--- /dev/null+++ b/docs/brainstorm/cycle-20261020/variants.md@@ -0,0 +1,38 @@+# Cycle 20261020 - structure variants (consultant output, verbatim) and final rationale++The three variants below are the consultant's output, reproduced verbatim from `cli-output/claude.md`.++### Variant 1: Substrate-first with live censuses++- **Approach**: A short serial substrate pass lands every shared declarative surface before the feature lanes start: the config quartet in one coherent diff (src/core/brain/types.ts carrying both the `cross_topic` block on BrainDreamConfig at :1450 and the new `context:` block near :2030, the policy parse/validate registration, the config-template entries, and the single config-template-ratchet test update), the env parse helper in src/core/config.ts, the path constants plus the state-surface row for Brain/cross-topic-rules.json, and the search-options-descriptor module with SEARCH_INPUT_SCHEMA derived byte-identically behind an equality test. The five feature lanes then run in parallel on disjoint file sets, consuming the substrate; the model-window resolver is built by the context-window lane itself, and the descriptor's remaining work (CLI flag derivation, the committed schemas/brain artifact, the schema export/check verb, the scoped doc-example tests) proceeds as a normal lane. Census registration stays per-lane as features go; because the substrate pre-registered the riskiest new surface, the only lane expected to add a census row is judge-eval, if it counts the machine-side mark file as a state surface.+- **Trade-offs**:+ - Pros: the single real code collision (the config quartet shared by cross-topic and context-window) is resolved exactly once in one reviewable diff; every commit on the cycle branch stays census-green and bisectable; the config-template ratchet is satisfied in one pass instead of two sequential edits; landing the descriptor with its byte-equality proof early converts the highest-blast-radius feature into an additive one and removes tail risk; the doc-example tests are scoped to the Search sections, so the later freshness and bench doc edits cannot break them.+ - Cons: a serial phase delays all lanes by the substrate duration; early risk concentrates in the config validation machinery, where a misspelled key only warns and silently defaults; lanes build against types that exist only on the cycle branch, so branch discipline is required; the substrate lane must be staffed with someone who understands both the dream config parse and the policy block machinery.+- **Complexity**: medium+- **Risk**: low++### Variant 2: Independent lanes with ownership contracts and an end-stage integrator++- **Approach**: No pre-landing. Five lanes start immediately from the same base under declared file ownership: the context-window lane owns the config quartet and the ratchet test; the cross-topic lane takes an explicit dependency on it and merges after, touching only the dream files, the path constants and its ledger write; judge-eval, freshness-plus-wikilink, and bench-plus-schema-schema-artifact form the remaining lanes on provably disjoint sets. Each lane registers its own census rows so every branch is green on its own. One integrator pass at the end resolves the residual collisions (state/surfaces.ts between the ledger and mark rows, command-manifest.ts between the eval and schema verbs, docs/cli-reference.md across three features, CHANGELOG), and the schema unification is sequenced last so the byte-identity check of SEARCH_INPUT_SCHEMA and the CLI flag derivation runs against the settled tree, with its doc-example tests executing after the freshness and bench doc edits have landed.+- **Trade-offs**:+ - Pros: maximum parallelism from minute zero; no lane waits on a substrate; the config machinery gets a single owner, so the two features never edit the same files simultaneously; sequencing the schema unification last means its byte-freeze and doc tests verify the final state of both the frozen MCP surface and the docs, eliminating the risk of later edits invalidating the proof.+ - Cons: the cross-topic lane is blocked or must stub against the config owner, creating a hidden serial chain inside a nominally parallel plan; integration churn concentrates at the end precisely in the sensitive files (config validation, state surfaces, the frozen schema, the manifest), where conflicts get resolved under deadline pressure; the highest-blast-radius feature lands last, so any byte-drift discovery or SCHEMA_IDS tripwire surprise arrives when the least schedule remains; reviewers see the config additions twice, in two feature diffs, instead of once.+- **Complexity**: medium+- **Risk**: medium++### Variant 3: Two-wave train with centralized registration commits++- **Approach**: No substrate pass. The cycle merges onto the cycle branch as two waves. Wave 1 lands immediately in parallel the three features with zero shared files: wikilink disambiguation, the freshness behind-count, and the bench guards. Wave 2 sequences the rest: context-window lands first and owns the config quartet, cross-topic rebases on it, judge-eval runs in parallel on its disjoint set, and the schema unification lands last in the wave, followed by a single final docs pass. Census and registry registration is centralized: each lane develops its rows as an attached patch, and one registration commit at each wave boundary applies the state-surface rows, config-template entries, manifest lines and doc updates in a single reviewable diff, keeping the PR head green at each boundary.+- **Trade-offs**:+ - Pros: the three disjoint features deliver early with no coordination cost, shrinking the tail; two wave boundaries give two clean integration and review checkpoints instead of one end-stage crunch; the centralized registration commit presents every census, manifest and docs change as one set, which is efficient to review as a whole.+ - Cons: commits between a feature landing and the wave-boundary registration commit leave the cycle branch census-red, which hurts bisectability inside the single PR; registration review is decoupled from feature review, so whoever reviews the registration commit may lack the context justifying each row; the wave discipline serializes the config work anyway, yielding most of Variant 2's constraint plus additional choreography; per-lane branches must either carry known-red census tests or maintain local registration patches, both of which invite drift between what a lane verified and what lands.+- **Complexity**: large+- **Risk**: medium++### Recommended: Variant 1++**Rationale**: The architecture censuses fail the build on unregistered new surfaces, so registration must be live wherever a lane adds state; Variant 1 is the only variant that removes the riskiest registrations (the cross-topic ledger surface row and the config-template ratchet shared by two features) from the lanes entirely, keeping every commit across four or five parallel lanes green and bisectable. The one genuine code collision, the config quartet shared by the cross-topic and context-window features, is resolved exactly once in a small coherent diff rather than through ownership-and-rebase choreography that concentrates churn in exactly the files where a mistake silently defaults. Landing the descriptor with its byte-equality proof early converts the schema unification, the highest-blast-radius feature, into an additive change and leaves only ordinary lane work for the tail. The cost is a short serial substrate phase and an early coordination front, which is cheap at this substrate size and pays for itself in merge stability and review clarity.++## Orchestrator decision++The orchestrator accepts the consultant's recommendation of Variant 1. It resolves the cycle's only true code collision, the config quartet shared by the cross-topic and context-window features, exactly once in one reviewable diff, and pre-registers the riskiest census rows so every commit across the five parallel lanes stays green and bisectable. Landing the search-options descriptor with its byte-equality proof first converts the highest-blast-radius feature into a purely additive change, which no other variant achieves without end-stage churn in exactly the files where a mistake silently defaults.diff --git a/docs/cli-reference.md b/docs/cli-reference.mdindex c6678683..9c52b7f5 100644--- a/docs/cli-reference.md+++ b/docs/cli-reference.md@@ -582,6 +582,8 @@ The benchmark never touches the configured vault - the fixture materializes intoSince 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.+The run is guarded at both ends by a closed refusal vocabulary, so a degraded run can neither create state nor publish scores. Before a run exists, a preflight refuses - by name, on stderr, as `refused (<kind>): <detail>` with a non-zero exit and no run directory left behind - an unusable runs directory (`runs_dir_unusable`), a fresh run whose identity collides with an existing run dir (`run_dir_exists`; the prior checkpoint survives and the detail names `--resume`), a resume target whose checkpoint is not a usable object (`checkpoint_unparseable`), lists a phase this build does not know (`checkpoint_phase_unknown`) or lists phases out of order or duplicated (`checkpoint_phase_order`), a resume handed a fixture the run did not start with - another `--fixture`, an edited copy, or a different `--sample-seed`/`--sample-cap` on a sampled suite (`checkpoint_fixture_mismatch`, refused before the artifact check so the new fixture's absent artifacts cannot masquerade as a tampered run), a phase marked done whose artifacts are gone or truncated (`run_artifact_missing`: the materialized vault is required exactly while retrieval still has to run against it, the per-question result files once retrieve is done, `report.json` once report is), and a fixture that cross-references a note or session it never defines (`fixture_cross_reference`). Config resolution and the capability gate moved above run creation, so those refusals leave no run dir behind either. Before any score is counted and again before the report writes, the persisted trace is validated: a question with no result file (`trace_result_missing`), a truncated or non-JSON one (`trace_result_unparseable`), an id that differs from the question it is stored under (`trace_id_mismatch`), a category-required field absent from a record (`trace_field_absent` - present-but-empty is a legitimate miss and passes), a faulted proactive decision (`trace_faulted_decisions` - the report must not publish harness breakage as memory behavior), files in `results/` beyond the fixture's question ids (`trace_extra_results`), and a report whose counts disagree with its own trace (`report_counts_mismatch`, recomputed through the same aggregation the report builder uses). Every detail names the repair (`--resume`, a fresh run, a writable `--runs-dir`, a fixture fix). What is deliberately NOT a refusal: score content - an all-questions-failed run is the harness's purpose - and the external judge staying in `error` remains advisory. Guards add zero stdout on success, and existing run ids, checkpoints and reports are byte-identical (`fixtureHash` stays content-only); the results and the report are now written atomically.+### Externalized session payloads (payload registry)```text@@ -2081,11 +2083,18 @@ o2b search status Index status; since v0.36.0 also reports the activ<n> in the last 30 days); --json carries it as the event_time object(documents, with_event_time, earliest, latest, recent_window_days,in_recent_window)- Since v1.76.0 it prints freshen (every <n>s or off), index_age, last_freshen- (completed <ts> (<n> changed) / failed <ts> (<n> in a row): <error> /- (none)) and freshen_backoff (until <ts>) while a backoff is active; --json- carries them as the freshen object (interval_s, index_age_s, last_outcome,- last_run_at, last_changed, last_error, failures, backoff_until)+ Since v1.76.0 it prints freshen (every <n>s or off), index_age, index_behind,+ last_freshen (completed <ts> (<n> changed) / failed <ts> (<n> in a row):+ <error> / (none)) and freshen_backoff (until <ts>) while a backoff is+ active; --json carries them as the freshen object (interval_s, index_age_s,+ index_behind, last_outcome, last_run_at, last_changed, last_error,+ failures, backoff_until)+ index_behind is the measured number of documents the next incremental run+ would add, update or delete, counted now by a stat-only walk diffed against+ the index - an upper bound, since a touch-only file counts as changed.+ It is measured only when+ an index exists; a failed measurement prints (not measured) and serializes+ null - never a fabricated zeroo2b search check Pre-flight diagnostics: vault, index directory, SQLite/FTS5, thevector extension, the embedding key, the provider, the vector ABI stamp--integrity additionally runs a full PRAGMA quick_check over the index@@ -2191,6 +2200,26 @@ o2b search rerank-eval Rerank eval gate over a labelled dataset: runs theaggregates, each language folded with the same reduce over itsper-query rows, so a bilingual dataset shows per-script lifts theblended number would average away.+o2b search schema export Write the versioned search-query JSON Schema artifact+ (schemas/brain/search-query.schema.json, $id+ brain.search_query.v1, draft 2020-12) from the search-options+ descriptor - the same table that derives the served brain_search+ inputSchema and the o2b search CLI flags, so the committed artifact+ cannot disagree with either. --stdout prints it instead of writing.+ The file is derived, never hand-edited: regeneration is this verb,+ and its $defs.search_query_document block is the grammar of the+ line-oriented query-document program (intent/lex/vec/hyde lanes)+o2b search schema check Re-derive the artifact and compare it with the committed file, so a+ descriptor change that outgrew the file is named here and in CI+ before anything trusts the stale one. The comparison is JSON+ equality, not byte equality - the committed file carries the repo+ formatter's layout, so only content can drift. Exit 0 clean ("search+ schema: <path> matches the descriptor"; --json prints+ {"ok":true,"$id":"brain.search_query.v1"}); exit 2 on drift, with+ stderr naming which (the property set or the content) and the remedy+ (run o2b search schema export and commit the result); exit 2 also+ when the file is missing or unreadable. An unknown subcommand is a+ usage error, also exit 2````search_rerank_kind` is `openai-compat` (default), `local` or@@ -2244,7 +2273,7 @@ so there is no separate lane field that could drift from it:| Code | The narrowing it reports || ------------------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |-| `index-stale` | the index was last updated more than ten minutes ago (`detail.ageSeconds`), so notes changed since then may be missing; the code reports the index age only and does not say a refresh is running: freshen on read starts a background run when it can, and starts none when it is off, a failed run is backing off, another run or writer holds the index, the index is read-only for this reader, or the run cannot be spawned |+| `index-stale` | the index was last updated more than ten minutes ago (`detail.ageSeconds`), so notes changed since then may be missing; `detail.behindCount` is the measured number of documents the next incremental run would add, update or delete, counted live under the same gate that fires the code by a stat-only walk diffed against the index - an upper bound (a touch-only file counts as changed), a measured zero rides too, and absent means not measured, never zero. The code still does not say a refresh is running: freshen on read starts a background run when it can, and starts none when it is off, a failed run is backing off, another run or writer holds the index, the index is read-only for this reader, or the run cannot be spawned || `keyword-fts-match-empty` | the query tokenised to an empty FTS match, so the keyword lane never ran || `keyword-trigram-lane-fault` | the trigram candidate lane could not be read; `detail.fault` carries that lane's own classification || `semantic-embeddings-absent` | the index holds no compatible embedding |diff --git a/docs/decision-models/providers.md b/docs/decision-models/providers.mdindex 6b671ead..ea91ccb7 100644--- a/docs/decision-models/providers.md+++ b/docs/decision-models/providers.md@@ -11,18 +11,18 @@ for you, and no route is ever a fallback for another one.## Presets-| Preset | Adapter | Base URL | Model id | Context (state tokens: default / ceiling) | Licence | Data handling |-|---|---|---|---|---|---|---|-| `typesafe` | `systemone` | `https://api.typesafe.ai` | `jev-1.13.0` | 32000 / 32000 | hosted | TypeSafe, directly |-| `openrouter` | `systemone` | `https://openrouter.ai/api` | `typesafe/jev-1.13` | 32000 / 32000 | hosted | OpenRouter, then TypeSafe |-| `vercel` | `systemone` | `https://ai-gateway.vercel.sh/typesafe` | `typesafe-ai/jev` | 32000 / 32000 | hosted | Vercel AI Gateway, then TypeSafe |-| `vercel-evaluate` | `vercel-evaluate` | `https://ai-gateway.vercel.sh` | `typesafe-ai/jev` | 32000 / 32000 | hosted | Vercel AI Gateway, then TypeSafe |-| `opencode-zen` | `systemone` | `https://opencode.ai/zen` | `jev-1.13` | 32000 / 32000 | hosted | OpenCode Zen, then TypeSafe |-| `laya` | `systemone` | `http://127.0.0.1:8000` | `english` | 2000 / 8192 | Apache-2.0 | your own server; on loopback nothing leaves the machine |-| `openjev` | `systemone` | `http://127.0.0.1:3000` | `openjev` | 4000 / 16384 | CC-BY-NC-4.0 | your own server; on loopback nothing leaves the machine |-| `compatible` | `systemone` | must be set | must be set | 32000 / 32000 | depends on the model | whoever runs the server |-| `llm-emulation` | `llm-emulation` | must be set | must be set | 32000 / 32000 | depends on the model | whoever runs the chat endpoint |-| `converse` | `converse` | must be set | must be set | 32000 / 32000 | depends on the model | whoever runs the gateway |+| Preset | Adapter | Base URL | Model id | Context (state tokens: default / ceiling) | Licence | Data handling |+| ----------------- | ----------------- | --------------------------------------- | ------------------- | ----------------------------------------- | -------------------- | ------------------------------------------------------- |+| `typesafe` | `systemone` | `https://api.typesafe.ai` | `jev-1.13.0` | 32000 / 32000 | hosted | TypeSafe, directly |+| `openrouter` | `systemone` | `https://openrouter.ai/api` | `typesafe/jev-1.13` | 32000 / 32000 | hosted | OpenRouter, then TypeSafe |+| `vercel` | `systemone` | `https://ai-gateway.vercel.sh/typesafe` | `typesafe-ai/jev` | 32000 / 32000 | hosted | Vercel AI Gateway, then TypeSafe |+| `vercel-evaluate` | `vercel-evaluate` | `https://ai-gateway.vercel.sh` | `typesafe-ai/jev` | 32000 / 32000 | hosted | Vercel AI Gateway, then TypeSafe |+| `opencode-zen` | `systemone` | `https://opencode.ai/zen` | `jev-1.13` | 32000 / 32000 | hosted | OpenCode Zen, then TypeSafe |+| `laya` | `systemone` | `http://127.0.0.1:8000` | `english` | 2000 / 8192 | Apache-2.0 | your own server; on loopback nothing leaves the machine |+| `openjev` | `systemone` | `http://127.0.0.1:3000` | `openjev` | 4000 / 16384 | CC-BY-NC-4.0 | your own server; on loopback nothing leaves the machine |+| `compatible` | `systemone` | must be set | must be set | 32000 / 32000 | depends on the model | whoever runs the server |+| `llm-emulation` | `llm-emulation` | must be set | must be set | 32000 / 32000 | depends on the model | whoever runs the chat endpoint |+| `converse` | `converse` | must be set | must be set | 32000 / 32000 | depends on the model | whoever runs the gateway |"State tokens" is Open Second Brain's own conservative estimate (about twocharacters per token), used to keep a request within the route's context:@@ -31,14 +31,14 @@ to the second.Other per-route limits:-| Preset | Key | Most `choice` options | Threshold profile | Input price (USD / M tokens) |-|---|---|---|---|---|-| `typesafe`, `openrouter`, `vercel`, `vercel-evaluate`, `opencode-zen` | required | 255 | `jev-1.13` | 0.042 |-| `laya` | optional on loopback | 100 | `laya` | 0 |-| `openjev` | optional on loopback | 52 | `openjev` | 0 |-| `compatible` | required | 255 | none, unless `decision_model_threshold_profile` names one | unknown |-| `llm-emulation` | required | 255 | `llm-emulation` | unknown unless both price keys are set |-| `converse` | required | 255 | `converse` | unknown unless both price keys are set |+| Preset | Key | Most `choice` options | Threshold profile | Input price (USD / M tokens) |+| --------------------------------------------------------------------- | -------------------- | --------------------- | --------------------------------------------------------- | -------------------------------------- |+| `typesafe`, `openrouter`, `vercel`, `vercel-evaluate`, `opencode-zen` | required | 255 | `jev-1.13` | 0.042 |+| `laya` | optional on loopback | 100 | `laya` | 0 |+| `openjev` | optional on loopback | 52 | `openjev` | 0 |+| `compatible` | required | 255 | none, unless `decision_model_threshold_profile` names one | unknown |+| `llm-emulation` | required | 255 | `llm-emulation` | unknown unless both price keys are set |+| `converse` | required | 255 | `converse` | unknown unless both price keys are set |A `choice` question above the route's option limit is never sent: a use thatcan split it does, and otherwise that request degrades with `budget`, like an@@ -75,7 +75,7 @@ uncalibrated without saying so, so Open Second Brain never configures them.```yamldecision_model_enabled: "true"decision_model_provider: vercel-evaluate-decision_model_env_key: AI_GATEWAY_API_KEY # the variable's name, not the key+decision_model_env_key: AI_GATEWAY_API_KEY # the variable's name, not the keydecision_model_uses: "rerank:shadow"```@@ -169,7 +169,7 @@ compare routes in `shadow` when only a chat endpoint is available.```yamldecision_model_enabled: "true"-decision_model_provider: llm-emulation # uncalibrated, shadow only+decision_model_provider: llm-emulation # uncalibrated, shadow onlydecision_model_base_url: https://api.example.com/v1decision_model_id: some-small-chat-modeldecision_model_env_key: EXAMPLE_API_KEY@@ -220,7 +220,7 @@ decision_model_enabled: "true"decision_model_provider: conversedecision_model_base_url: https://gateway.example.comdecision_model_id: gateway-jev-1-decision_model_env_key: GATEWAY_DECISION_KEY # the variable's name, not the key+decision_model_env_key: GATEWAY_DECISION_KEY # the variable's name, not the keydecision_model_uses: "rerank:shadow"```@@ -238,6 +238,45 @@ preset names a threshold profile:A use set to `enforce` on a profile without tuned thresholds for it runs as`shadow`: the request is sent and recorded, and the deterministic result isreturned. Nothing on a hot path warns about it; `o2b decision-model check`-prints one warning naming the uses concerned. Tuning a profile means-measuring it in shadow and with the eval gate, the same way as for the-hosted route.+prints one warning naming the uses concerned.++## Measuring a profile: the preregistered eval++The shadow hold is not a dead end. Each use with a committed, labeled take+ships a preregistered eval spec: the fixture and its content hash, a seed+with a frozen dev/counted split, the promotion metric with its ceiling and+minimum n, and the exact threshold values the use reads - all frozen and+content-hashed before anything is graded, so a spec edited after the fact+invalidates what came before instead of quietly re-scoping the claim.++`o2b decision-model eval run --use <use>` grades that take over your own+configured adapter. The requests are real spend counted toward the daily+cost gate (the deterministic scorer is canonical; an external judge would+be advisory only). The verdict is a three-arm rule, the same shape the+extract-prefilter report keeps: `promote` only when the counted error meets+the ceiling, does not regress against the deterministic baseline, and the+counted n is met; a short n is `not_enough_evidence`, never a pass.++Every run caches a `decision_model_eval_grade` record in the vault's+continuity log - `o2b decision-model eval list` prints them (or+`o2b decision-model report`), and malformed records are skipped by name,+never silently. These records are review evidence. The gate input is a+separate machine-side tuning mark under the state root+(`${XDG_STATE_HOME:-~/.local/state}/open-second-brain/decision-model/`),+written only by `eval run`, and only on a `promote` verdict for a named+profile. With a valid mark, that profile-use pair runs `enforce` where it+would have run `shadow`.++The mark is honored only while the installed spec still matches the one it+was measured under: the spec hash, the fixture hash and the pinned+threshold values are all re-checked on every read, along with the endpoint+that earned it (the provider, model and base-url hash recorded in the+mark). Edit the spec, move the fixture, change a threshold, or point the+config at another endpoint, and the pair falls back to shadow - the+fail-closed direction. Deleting the mark does the same; nothing breaks.+`o2b decision-model check` names the measured state (untuned, baseline,+measured under a spec hash, or measured under a spec hash on another+endpoint - provider, model or base-url mismatch) and lists the cached+grades, and the doctor readiness line carries the same summary. Tuning a+profile by hand-editing the source table stays possible and still wins+over a mark; the mark only ever carries pairs the table leaves untuned.diff --git a/docs/mcp.md b/docs/mcp.mdindex 78440562..49676142 100644--- a/docs/mcp.md+++ b/docs/mcp.md@@ -471,7 +471,12 @@ reasons, per-result `why_retrieved`, IDF-weighted coverage with rare-termclassification, per-token `union_records` for uncovered terms, and a`completeness` verdict whose `uncovered_but_present_in_corpus` list is thefalse-absence guard. It can also emit opt-in recall telemetry with-`telemetry: true`.+`telemetry: true`. The whole query language is published as a versioned+JSON Schema artifact beside the repo+(`schemas/brain/search-query.schema.json`, `$id brain.search_query.v1`),+derived from the same table that serves this inputSchema:+`o2b search schema export` regenerates it and `o2b search schema check`+exits 2 when the committed file has drifted from the derivation.Since v1.44.0 `explain: true` adds two top-level receipts alongside theper-result `score_breakdown`: `retrieval_decision_trace` (evaluated /surfaced / excluded counts plus every excluded candidate as a compact@@ -1994,7 +1999,14 @@ format characters), when it contains NUL, or when it exceeds the cap.vocabulary of stable identifiers, and an `empty` corpus statement on azero-result answer no degradation accounts for. Every `degraded[].detail`carries identifiers and integers only, never a provider message, a- filesystem path, or the query text. The response schema declares the code+ filesystem path, or the query text. The `index-stale` entry's detail+ carries `behindCount` when the index-behind census was measured for this+ answer - cached for at most 60 seconds and invalidated by this process's+ own note writes, so a write from another process can leave the count up+ to a minute old - the documents the next incremental run would add,+ update or delete, counted under the same staleness gate that fires the+ code; a measured zero rides too, and absent means not measured, never a+ zero. The response schema declares the codeenum, so a build emitting a code outside the vocabulary fails its owncontract rather than handing a client a value it cannot interpret. Thekey is absent - never null - on a healthy answer, so an existingdiff --git a/openclaw.plugin.json b/openclaw.plugin.jsonindex 3f0db615..6cd59560 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.89.0",+ "version": "1.90.0","activation": { "onStartup": true },"skills": ["./skills"],"contracts": {diff --git a/openclaw/index.js b/openclaw/index.jsindex 31ca6a4c..e716563c 100644--- a/openclaw/index.js+++ b/openclaw/index.js@@ -2241,6 +2241,7 @@ __export(exports_config, {MAINTENANCE_CUSTOM_TASKS_ENV: () => MAINTENANCE_CUSTOM_TASKS_ENV,MAINTENANCE_EMBEDDINGS_CONFIG_KEY: () => MAINTENANCE_EMBEDDINGS_CONFIG_KEY,MAINTENANCE_EMBEDDINGS_ENV: () => MAINTENANCE_EMBEDDINGS_ENV,+ MODEL_CONTEXT_WINDOW_ENV_KEY: () => MODEL_CONTEXT_WINDOW_ENV_KEY,PARTNER_CODEGRAPH_DISABLED_CONFIG_KEY: () => PARTNER_CODEGRAPH_DISABLED_CONFIG_KEY,PARTNER_CODEGRAPH_DISABLED_ENV: () => PARTNER_CODEGRAPH_DISABLED_ENV,REGROUND_PART_CHARS_DEFAULT: () => REGROUND_PART_CHARS_DEFAULT,@@ -2282,6 +2283,7 @@ __export(exports_config, {resolveMaintenanceEmbeddings: () => resolveMaintenanceEmbeddings,resolveMcpRouteMetricsEnabled: () => resolveMcpRouteMetricsEnabled,resolveMcpToolProfile: () => resolveMcpToolProfile,+ resolveModelContextWindowEnvTokens: () => resolveModelContextWindowEnvTokens,resolveNavTierCadenceMinutes: () => resolveNavTierCadenceMinutes,resolveNavTierEnabled: () => resolveNavTierEnabled,resolveNearDuplicateRetireSiblingsEnabled: () => resolveNearDuplicateRetireSiblingsEnabled,@@ -2704,6 +2706,16 @@ function resolveAdequacyMinResults(env, fileValue) {}return value;}+function resolveModelContextWindowEnvTokens() {+ const raw = process.env[MODEL_CONTEXT_WINDOW_ENV_KEY]?.trim() ?? "";+ if (raw === "")+ return;+ const value = Number(raw);+ if (!Number.isInteger(value) || value <= 0) {+ throw new Error(`${MODEL_CONTEXT_WINDOW_ENV_KEY} must be a positive integer; got '${raw}'`);+ }+ return value;+}function resolveGenerationTraceEnabled(configPath) {return resolveConfigFlag("OPEN_SECOND_BRAIN_GENERATION_TRACE_ENABLED", "generation_trace_enabled", configPath);}@@ -2954,7 +2966,7 @@ function expandTilde(p, platform = process.platform, home = homedir2()) {return join5(home, p.slice(2));return p;}-var import_proper_lockfile2, namedSecretResolver, CONFIG_VALUE_REJECTED_CHARS, UNSUPPORTED_CONFIG_PLATFORMS, UnsupportedPlatformError, ConfigReadError, UNCONFIGURED_AGENT_NAME = "agent", SHARED_NAMESPACE_KEY = "shared_namespace", DEVICE_ID_RE, INSTALLATION_SECRET_CONFIG_KEY = "installation_secret", INSTALLATION_SECRET_ENV_KEY = "O2B_INSTALLATION_SECRET", INSTALLATION_SECRET_RE, VAULT_STORE_REF_PREFIX = "vault://", VAULT_STORE_REF_HEX_LEN = 32, DECISION_RECALL_MAX_PER_SESSION_CONFIG_KEY = "decision_recall.max_per_session", DECISION_RECALL_MAX_PER_SESSION_ENV_KEY = "OPEN_SECOND_BRAIN_DECISION_RECALL_MAX_PER_SESSION", DECISION_RECALL_MIN_SPACING_TURNS_CONFIG_KEY = "decision_recall.min_spacing_turns", DECISION_RECALL_MIN_SPACING_TURNS_ENV_KEY = "OPEN_SECOND_BRAIN_DECISION_RECALL_MIN_SPACING_TURNS", ANSWER_QUOTE_CHECK_MODES, QUOTE_CHECK_BLOCK = "quote_check", ANSWER_QUOTE_CHECK_PHASES, QUOTE_CHECK_DEFAULT = "shadow", quoteCheckWarnedUnknownKeys, RECALL_INJECT_CAP_SPECS, REGROUND_PART_CHARS_DEFAULT = 9000, MAINTENANCE_EMBEDDINGS_ENV = "OPEN_SECOND_BRAIN_MAINTENANCE_EMBEDDINGS", MAINTENANCE_EMBEDDINGS_CONFIG_KEY = "maintenance_embeddings", MAINTENANCE_CUSTOM_TASKS_ENV = "OPEN_SECOND_BRAIN_MAINTENANCE_CUSTOM_TASKS", MAINTENANCE_CUSTOM_TASKS_CONFIG_KEY = "maintenance_custom_tasks", PARTNER_CODEGRAPH_DISABLED_ENV = "OPEN_SECOND_BRAIN_PARTNER_CODEGRAPH_DISABLED", PARTNER_CODEGRAPH_DISABLED_CONFIG_KEY = "partner_codegraph_disabled", SESSION_CAPTURE_ROLES;+var import_proper_lockfile2, namedSecretResolver, CONFIG_VALUE_REJECTED_CHARS, UNSUPPORTED_CONFIG_PLATFORMS, UnsupportedPlatformError, ConfigReadError, UNCONFIGURED_AGENT_NAME = "agent", SHARED_NAMESPACE_KEY = "shared_namespace", DEVICE_ID_RE, INSTALLATION_SECRET_CONFIG_KEY = "installation_secret", INSTALLATION_SECRET_ENV_KEY = "O2B_INSTALLATION_SECRET", INSTALLATION_SECRET_RE, VAULT_STORE_REF_PREFIX = "vault://", VAULT_STORE_REF_HEX_LEN = 32, DECISION_RECALL_MAX_PER_SESSION_CONFIG_KEY = "decision_recall.max_per_session", DECISION_RECALL_MAX_PER_SESSION_ENV_KEY = "OPEN_SECOND_BRAIN_DECISION_RECALL_MAX_PER_SESSION", DECISION_RECALL_MIN_SPACING_TURNS_CONFIG_KEY = "decision_recall.min_spacing_turns", DECISION_RECALL_MIN_SPACING_TURNS_ENV_KEY = "OPEN_SECOND_BRAIN_DECISION_RECALL_MIN_SPACING_TURNS", MODEL_CONTEXT_WINDOW_ENV_KEY = "OPEN_SECOND_BRAIN_MODEL_CONTEXT_WINDOW", ANSWER_QUOTE_CHECK_MODES, QUOTE_CHECK_BLOCK = "quote_check", ANSWER_QUOTE_CHECK_PHASES, QUOTE_CHECK_DEFAULT = "shadow", quoteCheckWarnedUnknownKeys, RECALL_INJECT_CAP_SPECS, REGROUND_PART_CHARS_DEFAULT = 9000, MAINTENANCE_EMBEDDINGS_ENV = "OPEN_SECOND_BRAIN_MAINTENANCE_EMBEDDINGS", MAINTENANCE_EMBEDDINGS_CONFIG_KEY = "maintenance_embeddings", MAINTENANCE_CUSTOM_TASKS_ENV = "OPEN_SECOND_BRAIN_MAINTENANCE_CUSTOM_TASKS", MAINTENANCE_CUSTOM_TASKS_CONFIG_KEY = "maintenance_custom_tasks", PARTNER_CODEGRAPH_DISABLED_ENV = "OPEN_SECOND_BRAIN_PARTNER_CODEGRAPH_DISABLED", PARTNER_CODEGRAPH_DISABLED_CONFIG_KEY = "partner_codegraph_disabled", SESSION_CAPTURE_ROLES;var init_config = __esm(() => {init_fs_atomic();init_secret_ref();diff --git a/package.json b/package.jsonindex fcaf8cca..092f4984 100644--- a/package.json+++ b/package.json@@ -1,6 +1,6 @@{"name": "open-second-brain",- "version": "1.89.0",+ "version": "1.90.0","private": false,"description": "Second brain for AI agents using Obsidian-compatible Markdown vaults. Works with Hermes, Claude Code, Codex, and OpenClaw.","keywords": [@@ -28,10 +28,12 @@"skills/","scripts/","plugins/",+ "schemas/","openclaw.plugin.json","README.md","LICENSE",- "pyproject.toml"+ "pyproject.toml",+ "tests/fixtures/decision-model"],"type": "module","scripts": {@@ -48,6 +50,8 @@"sync-version:check": "bun run scripts/sync-version.ts --check","sync-plugin-mirrors": "bun run scripts/sync-plugin-mirrors.ts","sync-plugin-mirrors:check": "bun run scripts/sync-plugin-mirrors.ts --check",+ "search-schema": "bun run scripts/search-schema.ts",+ "search-schema:check": "bun run scripts/search-schema.ts --check","link-ratchet": "bun run scripts/link-ratchet.ts","link-ratchet:check": "bun run scripts/link-ratchet.ts --check","check:paths": "bun run scripts/check-hardcoded-paths.ts",diff --git a/plugin.yaml b/plugin.yamlindex d8f79a58..2d2b8b3e 100644--- a/plugin.yaml+++ b/plugin.yaml@@ -1,5 +1,5 @@name: open-second-brain-version: "1.89.0"+version: "1.90.0"description: "Open Second Brain - native Hermes memory provider backed by an Obsidian-compatible Markdown vault."author: "Open Second Brain contributors"memory_provider: truediff --git a/plugins/codex/.codex-plugin/plugin.json b/plugins/codex/.codex-plugin/plugin.jsonindex 7682a66c..b1a91ace 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.89.0",+ "version": "1.90.0","description": "Plugin-first second brain package for Codex, Hermes, Claude Code, OpenClaw, and other agent runtimes.","author": {"name": "Open Second Brain contributors",diff --git a/plugins/hermes/_schemas.py b/plugins/hermes/_schemas.pyindex 490efdc0..79979b2a 100644--- a/plugins/hermes/_schemas.py+++ b/plugins/hermes/_schemas.py@@ -24,867 +24,1465 @@ from __future__ import annotationsimport copyfrom typing import Any-STATIC_TOOL_SCHEMAS: tuple[dict[str, Any], ...] = ({'name': 'brain_feedback',- 'description': 'Record one Brain taste signal in `Brain/inbox/sig-*.md`. With `force_confirmed: '- 'true`, create the preference directly (skips the dream trial window).',- 'inputSchema': {'type': 'object',- 'properties': {'topic': {'type': 'string',- 'description': 'Stable kebab-slug for the rule, e.g. '- '`no-internal-abbrev`.'},- 'signal': {'type': 'string',- 'enum': ['positive', 'negative'],- 'description': '`positive` when the principle is the '- "rule to follow, `negative` when it's "- 'what to avoid.'},- 'principle': {'type': 'string',- 'description': 'One-line, agent-readable '- 'formulation of the rule (imperative '- 'voice).'},- 'scope': {'type': 'string',- 'description': 'Optional soft category for later '- 'application-scope matching, e.g. '- '`writing`, `coding`.'},- 'source': {'type': 'array',- 'items': {'type': 'string'},- 'description': 'Optional wikilinks to the artifacts or '- 'notes that triggered the signal.'},- 'agent': {'type': 'string',- 'description': 'Optional agent identity override; '- 'defaults to the server-resolved name.'},- 'raw': {'type': 'string',- 'description': 'Optional free-form raw quote (rendered '- 'under `## Raw` in the signal file).'},- 'force_confirmed': {'type': 'boolean',- 'description': 'When true, also creates an '- 'immediately-active confirmed '- '`pref-*` alongside the inbox '- 'signal, skipping the '- 'dream-pass promotion step.'},- 'event_time': {'type': 'string',- 'description': 'Optional ISO-8601 event-time for a '- 'backfilled signal (when it '- 'actually happened). Stamps '- '`created_at`/`valid_from`/`recorded_at`; '- 'absent uses wall-clock.'},- 'idempotency_key': {'type': 'string',- 'description': 'Optional client key that '- 'dedupes retried calls: same '- 'key + same payload is a '- 'no-op; same key + different '- 'payload is rejected.'},- 'expires': {'type': 'string',- 'description': 'Optional YYYY-MM-DD or ISO-8601 '- 'lifetime. Past it the signal (and any '- 'force-confirmed preference) drops out '- 'of default reads; the file is never '- 'deleted.'}},- 'required': ['topic', 'signal', 'principle'],- 'additionalProperties': False}},- {'name': 'brain_apply_evidence',- 'description': 'Record whether an active preference was applied, violated, or marked outdated '- 'against a freshly-produced durable artifact. Appends one event to '- '`Brain/log/<today>.md`. A single `outdated` event triggers retire on the next '- 'dream pass.',- 'inputSchema': {'type': 'object',- 'properties': {'pref_id': {'type': 'string',- 'description': 'Preference id (`pref-<slug>` or bare '- '`<slug>`).'},- 'artifact': {'type': 'string',- 'description': 'Wikilink identifying the artifact; '- 'optional inclusive line-range '- 'suffix, e.g. '- '`[[src/cli/main.ts:120-145]]`.'},- 'result': {'type': 'string',- 'enum': ['applied', 'violated', 'outdated'],- 'description': '`applied` if the rule held, `violated` '- 'if broken, `outdated` if the artifact '- 'shows the rule itself is obsolete.'},- 'agent': {'type': 'string',- 'description': 'Optional agent identity override; '- 'defaults to the server-resolved name.'},- 'outcome': {'type': 'string',- 'enum': ['success', 'failure', 'unknown'],- 'description': 'Optional downstream outcome of the '- 'artifact (t_d478df53): did the work '- 'the rule was applied to actually '- 'succeed? `unknown` is treated like an '- 'absent outcome.'},- 'note': {'type': 'string',- 'description': 'Optional one-line context.'}},- 'required': ['pref_id', 'artifact', 'result'],- 'additionalProperties': False}},- {'name': 'brain_note',- 'description': 'Append one narrative-milestone line (release shipped, PR merged, fact '- "discovered) to today's Brain log under the `note` event kind. Use when neither "- 'brain_feedback nor brain_apply_evidence fits.',- 'inputSchema': {'type': 'object',- 'properties': {'text': {'type': 'string',- 'description': 'One-line narrative description. Newlines '- 'collapse to single spaces; the shared '- 'redactor strips secret-shaped tokens.'},- 'agent': {'type': 'string',- 'description': 'Optional agent identity override; '- 'defaults to the server-resolved name.'}},- 'required': ['text'],- 'additionalProperties': False}},- {'name': 'brain_pinned_context',- 'description': 'Read, write, append, or clear the transient current-task scratchpad at '- '`Brain/pinned.md`. Use for facts that should survive context rotation but should '- 'not become permanent preferences. Pass `operations` to apply an ordered batch '- 'atomically (all-or-nothing).',- 'inputSchema': {'type': 'object',- 'properties': {'operation': {'type': 'string',- 'enum': ['read', 'write', 'append', 'clear'],- 'description': 'Single operation to perform. '- 'Defaults to read. Ignored when '- '`operations` is given.'},- 'content': {'type': 'string',- 'description': 'Pinned context body for write/append '- 'operations.'},- 'operations': {'type': 'array',- 'description': 'Ordered batch applied atomically; '- 'any invalid op aborts the whole '- 'batch with no write.',- 'items': {'type': 'object',- 'properties': {'op': {'type': 'string',- 'enum': ['write',- 'append',- 'clear',- 'replace'],- 'description': 'What '- 'this '- 'step '- 'does '- 'to '- 'the '- 'pinned '- 'body.'},- 'content': {'type': 'string',- 'description': 'Body '- 'for '- 'write/append '- 'ops.'},- 'find': {'type': 'string',- 'description': 'Exact '- 'segment '- 'to '- 'locate '- 'for '- 'a '- 'replace '- 'op.'},- 'replace': {'type': 'string',- 'description': 'Replacement '- 'text '- 'for '- 'a '- 'replace '- 'op.'}},- 'required': ['op'],- 'additionalProperties': False}}},- 'additionalProperties': False}},- {'name': 'brain_query',- 'description': 'Read-only lookup: one preference + its evidence trail, all artifacts under a '- 'topic, or every log event after a timestamp. Exactly one of `preference`, '- '`topic`, `since` must be supplied.',- 'inputSchema': {'type': 'object',- 'properties': {'preference': {'type': 'string',- 'description': 'Preference id (`pref-...` or '- '`ret-...`) to look up with its '- 'evidence trail.'},- 'topic': {'type': 'string',- 'description': 'Topic slug to aggregate signals + '- 'active/retired preference + log '- 'events.'},- 'show_expired': {'type': 'boolean',- 'description': 'Topic mode only: include '- 'memories past their '- '`expiration_date`. Default false '- '(expired memories are silently '- 'dropped from the result).'},- 'at': {'type': 'string',- 'description': 'Topic mode only: evaluate '- '`expiration_date` as of this instant, so a '- 'memory that lapsed after it comes back. '- 'ISO-8601 instant or YYYY-MM-DD. Default '- 'now.'},- 'since': {'type': 'string',- 'description': 'ISO-8601 timestamp; returns every Brain '- 'log event with timestamp >= since.'},- 'format': {'type': 'string',- 'enum': ['markdown', 'json'],- 'description': 'Reserved for forward-compat; the '- 'structured response is the same '- 'regardless.'},- 'telemetry': {'type': 'boolean',- 'description': 'Opt-in recall telemetry: emit one '- "continuity record (mode 'query', "- 'kind-only payload) for this call.'},- 'telemetry_host': {'type': 'string',- 'maxLength': 200,- 'description': 'Optional host/client label '- 'recorded on the telemetry '- 'record.'},- 'session_id': {'type': 'string',- 'maxLength': 512,- 'description': 'Optional session correlation id '- 'recorded on the telemetry record.'},- 'turn_id': {'type': 'string',- 'maxLength': 512,- 'description': 'Optional turn correlation id recorded '- 'on the telemetry record.'},- 'agent_scope': {'type': 'string',- 'description': 'Optional owner scope: with '- 'owner_scoped_facts on, an '- 'owner-tagged fact returns only to '- 'its own scope; ownerless facts '- 'always match. Absent = no '- 'filtering.'}},- 'additionalProperties': False}},- {'name': 'brain_search',- 'description': 'Full-text search across the vault. Optional semantic layer when configured. '- 'Read-only. When a query misses, consult brain_recall_gate before widening recall: it '- 'classifies whether widening is warranted.',- 'inputSchema': {'type': 'object',- 'properties': {'query': {'type': 'string',- 'minLength': 1,- 'maxLength': 2000,- 'description': 'What to recall from the vault. Matched '- 'against the index by keyword, semantics, or '- 'both.'},- 'query_document': {'type': 'string',- 'minLength': 1,- 'maxLength': 4000,- 'description': 'Line-oriented query program with '- 'intent:, lex:, vec: and hyde: '- 'lanes, steering each retrieval '- 'layer separately. Absent means '- "'query' drives every lane."},- 'focus_query': {'type': 'string',- 'minLength': 1,- 'maxLength': 1000,- 'description': 'Steer this one call towards a '- 'working-set topic without persisting a '- 'session focus.'},- 'focus_path_prefix': {'type': 'string',- 'minLength': 1,- 'maxLength': 256,- 'description': 'Steer this one call towards a '- 'vault subtree, paired with '- 'focus_query as a transient '- 'focus.'},- 'focus_session': {'type': 'string',- 'minLength': 1,- 'maxLength': 128,- 'description': 'Session id whose bound focus applies '- '(falls back to the global focus).'},- 'evidence_pack': {'type': 'boolean',- 'description': 'Return the evidence pack: '- 'matched/missing terms, coverage, '- 'abstention text and the '- 'false-absence guard. Default false.'},- 'include_superseded': {'type': 'boolean',- 'description': 'History mode for relation '- 'polarity: keep matched '- 'superseded predecessors '- 'undemoted and skip successor '- 'pull-in. Default false.'},- 'since': {'type': 'string',- 'maxLength': 64,- 'description': 'Hard filter on event time (validity, body '- 'anchor, mtime last): at/after this point. '- 'ISO date/datetime, today, yesterday, last '- 'week, last month, <n>h/<n>d/<n>w.'},- 'until': {'type': 'string',- 'maxLength': 64,- 'description': 'Hard filter on event time (validity, body '- 'anchor, mtime last): at/before this point. '- "Same forms as 'since'."},- 'limit': {'type': 'integer',- 'minimum': 1,- 'maximum': 50,- 'description': 'How many ranked results to return. Default '- '10.'},- 'semantic': {'type': 'boolean',- 'description': 'Force the semantic lane on or off. Absent '- 'lets the configured hybrid strategy '- 'decide.'},- 'keyword_only': {'type': 'boolean',- 'description': 'Skip the semantic lane entirely, so '- 'no embedding is needed. Default '- 'false.'},- 'match_mode': {'type': 'string',- 'enum': ['all', 'any'],- 'description': "FTS match breadth: 'all' (default) "- "requires every term; 'any' matches a "- 'document carrying any one term. Absent '- 'leaves the implicit AND.'},- 'disclosure': {'type': 'string',- 'enum': ['full', 'cards'],- 'description': "Result depth: 'full' (default) returns "- "full chunk content; 'cards' returns "- 'token-cheap layer-1 cards — drill a hit '- 'with brain_search_expand.'},- 'profile': {'type': 'string',- 'enum': ['fast', 'balanced', 'thorough'],- 'description': 'Named recall profile '- '(fast|balanced|thorough): a fixed knob '- 'preset, preferred over persisted '- 'self-tuning. Absent leaves ranking '- 'unchanged.'},- 'explain': {'type': 'boolean',- 'description': 'Add a per-result score_breakdown plus the '- 'retrieval_decision_trace and '- 'memory_trust_assessment receipts. Default '- 'false.'},- 'trust': {'type': 'boolean',- 'description': 'Stamp each result with inline trust metadata '- '(age_days, superseded, conflict), computed '- 'at read time. Default false.'},- 'threshold': {'type': 'number',- 'minimum': 0,- 'maximum': 1,- 'description': 'Relevance floor in [0,1] on the final '- 'score; drops weaker hits so an '- 'irrelevant query returns no match. '- 'Default 0 (disabled).'},- 'rerank': {'type': 'boolean',- 'description': 'Re-order the threshold-qualified results by '- 'core textual relevance (keyword + '- 'semantic). Default false.'},- 'reinforce': {'type': 'array',- 'maxItems': 50,- 'items': {'type': 'string',- 'minLength': 1,- 'maxLength': 512},- 'description': 'Paths proven useful: recorded to the '- 'reinforce ledger and lifted (bounded) '- 'before the top_k cut. Default absent.'},- 'record_access': {'type': 'boolean',- 'description': 'Record the surfaced paths as one '- 'activation access event (feeds the '- 'usage-aware ranking layer). Default '- 'true; never recorded for global '- 'searches.'},- 'global': {'type': 'boolean',- 'description': 'Cross-vault union: search profile vaults '- 'and read-only recall sources too, merging '- 'results with origin labels. Default false '- '(active vault only).'},- 'path_prefix': {'type': 'string',- 'maxLength': 256,- 'description': 'Restrict results to this vault '- 'subtree. Absent searches the whole '- 'vault.'},- 'telemetry': {'type': 'boolean',- 'description': 'Emit one recall-telemetry continuity '- 'record for this call. Default false.'},- 'telemetry_host': {'type': 'string',- 'maxLength': 200,- 'description': 'Optional host/client label recorded '- 'on the telemetry record.'},- 'session_id': {'type': 'string',- 'maxLength': 512,- 'description': 'Optional session correlation id '- 'recorded on the telemetry record.'},- 'turn_id': {'type': 'string',- 'maxLength': 512,- 'description': 'Optional turn correlation id recorded on '- 'the telemetry record.'},- 'properties': {'type': 'object',- 'description': 'Optional frontmatter filter; values '- 'within a key OR, keys AND. type, '- 'pinned, visibility as indexed; other '- 'keys narrow on the attribute snapshot, '- 'judged live.',- 'additionalProperties': {'type': 'array',- 'items': {'type': 'string'}}},- 'kind': {'type': 'string',- 'enum': ['page', 'section'],- 'description': "Restrict candidates by chunk kind: 'page' "- "matches each document's frontmatter/head "- "chunk (chunk 0), 'section' everything after "- 'it. Absent searches all chunks.'},- 'degree': {'type': 'array',- 'description': 'Graph-degree predicates over '- "backlink/outlink counts, e.g. 'backlinks=0' "- "(orphans) or 'outlinks>=5' (hubs); ANDed. "- 'Absent = no filter.',- 'items': {'type': 'string'}},- 'visibility': {'type': 'array',- 'description': 'Optional content-visibility scope; '- 'untagged pages always match, tagged '- 'pages only when this scope includes one '- 'of their values.',- 'items': {'type': 'string'}},- 'agent_scope': {'type': 'string',- 'description': 'Optional agent-ownership scope; shared '- '(ownerless) pages always match, '- 'owner-tagged pages only their owner. '- 'Absent = no ownership filtering.'},- 'session_scope': {'type': 'string',- 'description': 'Optional session-scope filter; pages '- 'with no session always match, '- 'session-tagged pages only this '- 'session. Absent = no session '- 'filtering.'},- 'project_scope': {'type': 'string',- 'description': 'Optional project-scope filter; pages '- 'with no project always match, '- 'project-tagged pages only this '- 'project. Absent = no project '- 'filtering.'},- 'iterative': {'type': 'boolean',- 'description': 'Opt in to the bounded iterative recall '- 'loop (default off). Surviving gaps pause '- 'with a plan; resume via '- 'iterative_payload. Inert unless the knob '- 'is on.'},- 'iterative_token': {'type': 'string',- 'maxLength': 128,- 'description': 'The round token from a plan-phase '- 'response, submitted beside '- 'iterative_payload. Requires '- 'iterative: true; single use - a '- 'replayed token is refused by '- 'name.'},- 'iterative_payload': {'type': 'object',- 'description': 'Decider payload answering a '- 'plan-phase envelope: { evidence: '- '[chunkId, ...], subQueries: '- '[...] }, validated before any '- 'pull runs. Requires '- 'iterative_token.'}},- 'required': ['query'],- 'additionalProperties': False}},- {'name': 'brain_recall_gate',- 'description': 'Classify whether recall should run. Diagnostics only; does not search. Pass '- '`scores` AND `match_quality` together for an adequacy verdict; either alone is '- 'INVALID_PARAMS (see `dependentRequired`). A measurement decides the verdict: '- 'below-floor quality answers retrieve false. `admit` echoes it.',- 'inputSchema': {'type': 'object',- 'properties': {'prompt': {'type': 'string',- 'minLength': 1,- 'maxLength': 4000,- 'description': "The turn's prompt, scored to decide "- 'whether recall is worth running at '- 'all.'},- 'previous_prompt': {'type': 'string',- 'maxLength': 4000,- 'description': "The preceding turn's prompt, "- 'so a follow-up is judged in '- 'context rather than on its '- 'own.'},- 'explicit': {'type': 'boolean',- 'description': 'The user asked for memory in so many '- 'words; the gate then retrieves '- 'regardless of score. Default false.'},- 'telemetry_host': {'type': 'string',- 'maxLength': 200,- 'description': 'Optional host/client label '- 'recorded on the telemetry '- 'record.'},- 'session_id': {'type': 'string',- 'maxLength': 512,- 'description': 'Optional session correlation id '- 'recorded on the telemetry record.'},- 'turn_id': {'type': 'string',- 'maxLength': 512,- 'description': 'Optional turn correlation id recorded '- 'on the telemetry record.'},- 'scores': {'type': 'array',- 'maxItems': 200,- 'items': {'type': 'number'},- 'description': 'Optional top-k recall scores; requires '- '`match_quality`. Together they add an '- 'adequacy verdict: sufficient/proceed, '- 'weak/re_recall, insufficient/abstain.'},- 'match_quality': {'type': 'number',- 'minimum': 0,- 'maximum': 1,- 'description': 'Absolute match quality in '- "[0,1]: a search outcome's "- '`idf_weighted_coverage`. '- 'Required with `scores`; the '- 'adequacy level reads this, '- 'never a score.'},- 'decision_answerable': {'type': 'number',- 'minimum': 0,- 'maximum': 1,- 'description': 'Advisory [0,1] '- 'probability from a '- "search's "- '`decision_model.answerable`. '- 'Needs `scores` and '- '`match_quality`; never '- 'changes the level.'}},- 'required': ['prompt'],- 'dependentRequired': {'scores': ['match_quality'],- 'match_quality': ['scores'],- 'decision_answerable': ['scores', 'match_quality']},- 'additionalProperties': False}},- {'name': 'brain_context',- 'description': 'Pull the current Brain/active.md body, pinned current-task context, and '- 'active-preference counts. Use at session start when SessionStart hook is '- 'unavailable (Cursor, Aider, raw Claude API). Read-only.',- 'inputSchema': {'type': 'object', 'properties': {}, 'additionalProperties': False}},- {'name': 'brain_context_pack',- 'description': 'Return the highest-tier, most recent vault slice that fits under '- '`max_tokens`. Ordered core → supporting → peripheral, newest first; '- 'stops adding pages when the next page would exceed the budget. '- 'Read-only.',- 'inputSchema': {'type': 'object',- 'properties': {'max_tokens': {'type': 'integer',- 'minimum': 1,- 'description': 'Strict upper bound on '- "the returned slice's "- 'token count.'},- 'query': {'type': 'string',- 'maxLength': 2000,- 'description': 'Optional query. Read as a '- 'case/Unicode-insensitive '- 'substring filter on topic + '- 'principle unless '- '`query_mode` says '- 'otherwise.'},- 'query_mode': {'type': 'string',- 'enum': ['substring',- 'ranked',- 'semantic'],- 'description': 'How `query` is read: '- '`substring` (default) '- 'drops misses; `ranked` '- 'orders by token '- 'overlap; `semantic` '- 'orders by stored belief '- 'vectors, embedding the '- 'query once.'},- 'packing_policy': {'type': 'string',- 'enum': ['facts_first',- 'retired_first'],- 'description': 'Budget claim order: '- '`facts_first` or '- '`retired_first`. '- 'Neither is the '- 'omitted default; a '- 'vault where one '- 'lane has no '- 'candidate is '- 'refused. Requires '- '`query`.'},- 'focus_session': {'type': 'string',- 'minLength': 1,- 'maxLength': 128,- 'description': 'Session id whose '- 'bound search focus '- 'boosts matching '- 'memories (requires '- 'search_focus_context_pack).'},- 'max_chars_per_memory': {'type': 'integer',- 'minimum': 1,- 'description': 'Optional '- 'per-page '- 'character cap '- 'so one huge '- 'page cannot '- 'crowd out the '- 'rest; trimmed '- 'pages carry '- '`trimmed: '- 'true`.'},- 'max_total_chars': {'type': 'integer',- 'minimum': 1,- 'description': 'Optional second '- 'ceiling (code '- 'points) on the '- 'cumulative size of '- 'the returned '- 'slice. '- 'Lowest-priority '- 'overflow is '- 'dropped with an '- '`over-char-budget` '- 'skip reason.'},- 'lanes': {'type': 'boolean',- 'description': 'When true, also return '- 'polarity-aware directives, '- 'constraints, and consider '- 'lanes. Legacy flat `items` '- 'remains present.'},- 'cache_stable': {'type': 'boolean',- 'description': 'When true, reorder '- 'the selected items by '- 'stable id and '- 'annotate their '- 'original rank.'},- 'dedup_repeated': {'type': 'boolean',- 'description': 'When true, replace '- 'repeated context '- 'bodies with '- 'reference hints to '- 'an earlier emitted '- 'item.'},- 'attention_flow_ids': {'type': 'array',- 'items': {'type': 'string'},- 'description': 'Optional '- 'declarative '- 'attention flow '- 'ids to inject '- 'as a synthetic '- 'context block.'},- 'receipt': {'type': 'boolean',- 'description': 'When true, emit an opt-in '- 'context receipt for this '- 'context-pack run.'},- 'receipt_host': {'type': 'string',- 'description': 'Optional host/runtime '- 'name for emitted '- 'receipts; defaults to '- '`mcp`.'},- 'recall_scores': {'type': 'array',- 'maxItems': 200,- 'items': {'type': 'number'},- 'description': 'Optional top-k '- 'recall scores; '- 'requires '- '`match_quality`. '- 'Together they add an '- 'adequacy verdict: '- 'sufficient/proceed, '- 'weak/re_recall, '- 'insufficient/abstain.'},- 'match_quality': {'type': 'number',- 'minimum': 0,- 'maximum': 1,- 'description': 'Absolute match '- 'quality in [0,1]: a '- "search outcome's "- '`idf_weighted_coverage`. '- 'Required with '- '`recall_scores`; the '- 'adequacy level reads '- 'this, never a '- 'score.'},- 'decision_answerable': {'type': 'number',- 'minimum': 0,- 'maximum': 1,- 'description': 'Advisory [0,1] '- 'probability '- 'from a '- "search's "- '`decision_model.answerable`. '- 'Needs '- '`recall_scores` '- 'and '- '`match_quality`; '- 'never changes '- 'the level.'},- 'telemetry': {'type': 'boolean',- 'description': 'When true, emit an '- 'opt-in recall telemetry '- 'record for this '- 'context-pack run.'},- 'telemetry_host': {'type': 'string',- 'description': 'Optional '- 'host/runtime name '- 'for emitted '- 'telemetry; defaults '- 'to `mcp`.'},- 'session_id': {'type': 'string',- 'description': 'Optional session id '- 'recorded on emitted '- 'telemetry.'},- 'turn_id': {'type': 'string',- 'description': 'Optional turn id recorded '- 'on emitted telemetry.'},- 'agent_scope': {'type': 'string',- 'description': 'Optional '- 'agent-ownership scope; '- 'shared (ownerless) '- 'memories always match, '- 'owner-tagged memories '- 'only their owner. '- 'Absent = no ownership '- 'filtering.'}},- 'required': ['max_tokens'],- 'dependentRequired': {'recall_scores': ['match_quality'],- 'match_quality': ['recall_scores'],- 'decision_answerable': ['recall_scores',- 'match_quality'],- 'query_mode': ['query'],- 'packing_policy': ['query']},- 'additionalProperties': False}},- {'name': 'brain_context_pack_outcome',- 'description': 'Context-pack outcome loop. `post` records an outcome row for a carried sample id '- '— first-pass/repair/retry counters plus three SEPARATE token signals (exact, '- 'modeled, observed) — calibrates the token-impact ledger, and records the '- "kernel's on-disk evidence. `list`/`summary` read rows. Gated.",- 'inputSchema': {'type': 'object',- 'properties': {'operation': {'type': 'string',- 'enum': ['post', 'list', 'summary'],- 'description': 'post writes one opt-in outcome row; '- 'list/summary read the durable '- 'ledger.'},- 'sample_id': {'type': 'string',- 'description': 'post: the carried '- 'recall/context-pack quality-sample '- 'id (a context-receipt id or opaque '- 'request hash) — never a raw prompt. '- 'Also a list/summary filter.'},- 'first_pass_success': {'type': 'boolean',- 'description': 'post: whether the packed '- 'context led to a '- 'first-pass success.'},- 'repair_required': {'type': 'boolean',- 'description': 'post (optional): whether the '- 'agent had to repair the first '- 'completion.'},- 'retry_count': {'type': 'integer',- 'minimum': 0,- 'description': 'post (optional): how many retries '- 'the completion needed.'},- 'follow_up_tokens': {'type': 'integer',- 'minimum': 0,- 'description': 'post (optional): tokens '- 'spent on follow-up turns '- 'after the first pass.'},- 'exact_prompt_token_savings': {'type': 'number',+STATIC_TOOL_SCHEMAS: tuple[dict[str, Any], ...] = ( { 'name': 'brain_feedback',+ 'description': 'Record one Brain taste signal in `Brain/inbox/sig-*.md`. With '+ '`force_confirmed: true`, create the preference directly (skips the '+ 'dream trial window).',+ 'inputSchema': { 'type': 'object',+ 'properties': { 'topic': { 'type': 'string',+ 'description': 'Stable kebab-slug '+ 'for the rule, e.g. '+ '`no-internal-abbrev`.'},+ 'signal': { 'type': 'string',+ 'enum': ['positive', 'negative'],+ 'description': '`positive` when the '+ 'principle is the '+ 'rule to follow, '+ '`negative` when '+ "it's what to "+ 'avoid.'},+ 'principle': { 'type': 'string',+ 'description': 'One-line, '+ 'agent-readable '+ 'formulation of '+ 'the rule '+ '(imperative '+ 'voice).'},+ 'scope': { 'type': 'string',+ 'description': 'Optional soft '+ 'category for later '+ 'application-scope '+ 'matching, e.g. '+ '`writing`, '+ '`coding`.'},+ 'source': { 'type': 'array',+ 'items': {'type': 'string'},+ 'description': 'Optional wikilinks '+ 'to the artifacts or '+ 'notes that '+ 'triggered the '+ 'signal.'},+ 'agent': { 'type': 'string',+ 'description': 'Optional agent '+ 'identity override; '+ 'defaults to the '+ 'server-resolved '+ 'name.'},+ 'raw': { 'type': 'string',+ 'description': 'Optional free-form raw '+ 'quote (rendered under '+ '`## Raw` in the signal '+ 'file).'},+ 'force_confirmed': { 'type': 'boolean',+ 'description': 'When true, '+ 'also '+ 'creates an '+ 'immediately-active '+ 'confirmed '+ '`pref-*` '+ 'alongside '+ 'the inbox '+ 'signal, '+ 'skipping '+ 'the '+ 'dream-pass '+ 'promotion '+ 'step.'},+ 'event_time': { 'type': 'string',+ 'description': 'Optional '+ 'ISO-8601 '+ 'event-time for '+ 'a backfilled '+ 'signal (when it '+ 'actually '+ 'happened). '+ 'Stamps '+ '`created_at`/`valid_from`/`recorded_at`; '+ 'absent uses '+ 'wall-clock.'},+ 'idempotency_key': { 'type': 'string',+ 'description': 'Optional '+ 'client key '+ 'that '+ 'dedupes '+ 'retried '+ 'calls: '+ 'same key + '+ 'same '+ 'payload is '+ 'a no-op; '+ 'same key + '+ 'different '+ 'payload is '+ 'rejected.'},+ 'expires': { 'type': 'string',+ 'description': 'Optional '+ 'YYYY-MM-DD or '+ 'ISO-8601 lifetime. '+ 'Past it the signal '+ '(and any '+ 'force-confirmed '+ 'preference) drops '+ 'out of default '+ 'reads; the file is '+ 'never deleted.'}},+ 'required': ['topic', 'signal', 'principle'],+ 'additionalProperties': False}},+ { 'name': 'brain_apply_evidence',+ 'description': 'Record whether an active preference was applied, violated, or marked '+ 'outdated against a freshly-produced durable artifact. Appends one '+ 'event to `Brain/log/<today>.md`. A single `outdated` event triggers '+ 'retire on the next dream pass.',+ 'inputSchema': { 'type': 'object',+ 'properties': { 'pref_id': { 'type': 'string',+ 'description': 'Preference id '+ '(`pref-<slug>` or '+ 'bare `<slug>`).'},+ 'artifact': { 'type': 'string',+ 'description': 'Wikilink '+ 'identifying the '+ 'artifact; '+ 'optional '+ 'inclusive '+ 'line-range '+ 'suffix, e.g. '+ '`[[src/cli/main.ts:120-145]]`.'},+ 'result': { 'type': 'string',+ 'enum': [ 'applied',+ 'violated',+ 'outdated'],+ 'description': '`applied` if the '+ 'rule held, '+ '`violated` if '+ 'broken, `outdated` '+ 'if the artifact '+ 'shows the rule '+ 'itself is '+ 'obsolete.'},+ 'agent': { 'type': 'string',+ 'description': 'Optional agent '+ 'identity override; '+ 'defaults to the '+ 'server-resolved '+ 'name.'},+ 'outcome': { 'type': 'string',+ 'enum': [ 'success',+ 'failure',+ 'unknown'],+ 'description': 'Optional '+ 'downstream outcome '+ 'of the artifact '+ '(t_d478df53): did '+ 'the work the rule '+ 'was applied to '+ 'actually succeed? '+ '`unknown` is '+ 'treated like an '+ 'absent outcome.'},+ 'note': { 'type': 'string',+ 'description': 'Optional one-line '+ 'context.'}},+ 'required': ['pref_id', 'artifact', 'result'],+ 'additionalProperties': False}},+ { 'name': 'brain_note',+ 'description': 'Append one narrative-milestone line (release shipped, PR merged, fact '+ "discovered) to today's Brain log under the `note` event kind. Use when "+ 'neither brain_feedback nor brain_apply_evidence fits.',+ 'inputSchema': { 'type': 'object',+ 'properties': { 'text': { 'type': 'string',+ 'description': 'One-line narrative '+ 'description. Newlines '+ 'collapse to single '+ 'spaces; the shared '+ 'redactor strips '+ 'secret-shaped '+ 'tokens.'},+ 'agent': { 'type': 'string',+ 'description': 'Optional agent '+ 'identity override; '+ 'defaults to the '+ 'server-resolved '+ 'name.'}},+ 'required': ['text'],+ 'additionalProperties': False}},+ { 'name': 'brain_pinned_context',+ 'description': 'Read, write, append, or clear the transient current-task scratchpad at '+ '`Brain/pinned.md`. Use for facts that should survive context rotation '+ 'but should not become permanent preferences. Pass `operations` to '+ 'apply an ordered batch atomically (all-or-nothing).',+ 'inputSchema': { 'type': 'object',+ 'properties': { 'operation': { 'type': 'string',+ 'enum': [ 'read',+ 'write',+ 'append',+ 'clear'],+ 'description': 'Single operation '+ 'to perform. '+ 'Defaults to '+ 'read. Ignored '+ 'when '+ '`operations` is '+ 'given.'},+ 'content': { 'type': 'string',+ 'description': 'Pinned context '+ 'body for '+ 'write/append '+ 'operations.'},+ 'operations': { 'type': 'array',+ 'description': 'Ordered batch '+ 'applied '+ 'atomically; any '+ 'invalid op '+ 'aborts the '+ 'whole batch '+ 'with no write.',+ 'items': { 'type': 'object',+ 'properties': { 'op': { 'type': 'string',+ 'enum': [ 'write',+ 'append',+ 'clear',+ 'replace'],+ 'description': 'What '+ 'this '+ 'step '+ 'does '+ 'to '+ 'the '+ 'pinned '+ 'body.'},+ 'content': { 'type': 'string',+ 'description': 'Body '+ 'for '+ 'write/append '+ 'ops.'},+ 'find': { 'type': 'string',+ 'description': 'Exact '+ 'segment '+ 'to '+ 'locate '+ 'for '+ 'a '+ 'replace '+ 'op.'},+ 'replace': { 'type': 'string',+ 'description': 'Replacement '+ 'text '+ 'for '+ 'a '+ 'replace '+ 'op.'}},+ 'required': ['op'],+ 'additionalProperties': False}}},+ 'additionalProperties': False}},+ { 'name': 'brain_context',+ 'description': 'Pull the current Brain/active.md body, pinned current-task context, '+ 'and active-preference counts. Use at session start when SessionStart '+ 'hook is unavailable (Cursor, Aider, raw Claude API). Read-only.',+ 'inputSchema': {'type': 'object', 'properties': {}, 'additionalProperties': False}},+ { 'name': 'brain_context_pack',+ 'description': 'Return the highest-tier, most recent vault slice under `max_tokens` - '+ 'derived from the model context window when omitted, refused when '+ 'nothing resolves. Ordered core → supporting → peripheral, newest '+ 'first; stops when the next page would exceed the budget. Read-only.',+ 'inputSchema': { 'type': 'object',+ 'properties': { 'max_tokens': { 'type': 'integer',+ 'minimum': 1,+ 'description': 'Token cap for '+ 'the slice. '+ 'Omitted: '+ 'derives from '+ 'the resolved '+ 'window (channel '+ 'in '+ '`max_tokens_source`; '+ '`default` '+ 'defers to the '+ 'preset hint). '+ 'Nothing '+ 'resolvable is '+ 'refused.'},+ 'model': { 'type': 'string',+ 'description': 'Model id. '+ '`max_tokens` '+ 'omitted: the context '+ 'window resolves '+ '(config, env, table, '+ '`1m` suffix); an '+ 'unplaced id is '+ 'refused (pass '+ 'max_tokens or set '+ 'context.window_tokens).'},+ 'query': { 'type': 'string',+ 'maxLength': 2000,+ 'description': 'Optional query. Read '+ 'as a '+ 'case/Unicode-insensitive '+ 'substring filter on '+ 'topic + principle '+ 'unless `query_mode` '+ 'says otherwise.'},+ 'query_mode': { 'type': 'string',+ 'enum': [ 'substring',+ 'ranked',+ 'semantic'],+ 'description': 'How `query` is '+ 'read: '+ '`substring` '+ '(default) drops '+ 'misses; '+ '`ranked` orders '+ 'by token '+ 'overlap; '+ '`semantic` '+ 'orders by '+ 'stored belief '+ 'vectors, '+ 'embedding the '+ 'query once.'},+ 'packing_policy': { 'type': 'string',+ 'enum': [ 'facts_first',+ 'retired_first'],+ 'description': 'Budget '+ 'claim '+ 'order: '+ '`facts_first` '+ 'or '+ '`retired_first`. '+ 'Neither is '+ 'the omitted '+ 'default; a '+ 'vault where '+ 'one lane '+ 'has no '+ 'candidate '+ 'is refused. '+ 'Requires '+ '`query`.'},+ 'focus_session': { 'type': 'string',+ 'minLength': 1,+ 'maxLength': 128,+ 'description': 'Session id '+ 'whose bound '+ 'search focus '+ 'boosts '+ 'matching '+ 'memories '+ '(requires '+ 'search_focus_context_pack).'},+ 'max_chars_per_memory': { 'type': 'integer',+ 'minimum': 1,+ 'description': 'Optional '+ 'per-page '+ 'character '+ 'cap '+ 'so '+ 'one '+ 'huge '+ 'page '+ 'cannot '+ 'crowd '+ 'out '+ 'the '+ 'rest; '+ 'trimmed '+ 'pages '+ 'carry '+ '`trimmed: '+ 'true`.'},+ 'max_total_chars': { 'type': 'integer',+ 'minimum': 1,+ 'description': 'Optional '+ 'second '+ 'ceiling '+ '(code '+ 'points) on '+ 'the '+ 'cumulative '+ 'size of '+ 'the '+ 'returned '+ 'slice. '+ 'Lowest-priority '+ 'overflow '+ 'is dropped '+ 'with an '+ '`over-char-budget` '+ 'skip '+ 'reason.'},+ 'lanes': { 'type': 'boolean',+ 'description': 'When true, also '+ 'return '+ 'polarity-aware '+ 'directives, '+ 'constraints, and '+ 'consider lanes. '+ 'Legacy flat `items` '+ 'remains present.'},+ 'cache_stable': { 'type': 'boolean',+ 'description': 'When true, '+ 'reorder the '+ 'selected '+ 'items by '+ 'stable id and '+ 'annotate '+ 'their '+ 'original '+ 'rank.'},+ 'dedup_repeated': { 'type': 'boolean',+ 'description': 'When true, '+ 'replace '+ 'repeated '+ 'context '+ 'bodies with '+ 'reference '+ 'hints to an '+ 'earlier '+ 'emitted '+ 'item.'},+ 'attention_flow_ids': { 'type': 'array',+ 'items': { 'type': 'string'},+ 'description': 'Optional '+ 'declarative '+ 'attention '+ 'flow '+ 'ids to '+ 'inject '+ 'as a '+ 'synthetic '+ 'context '+ 'block.'},+ 'receipt': { 'type': 'boolean',+ 'description': 'When true, emit an '+ 'opt-in context '+ 'receipt for this '+ 'context-pack run.'},+ 'receipt_host': { 'type': 'string',+ 'description': 'Optional '+ 'host/runtime '+ 'name for '+ 'emitted '+ 'receipts; '+ 'defaults to '+ '`mcp`.'},+ 'recall_scores': { 'type': 'array',+ 'maxItems': 200,+ 'items': {'type': 'number'},+ 'description': 'Optional '+ 'top-k recall '+ 'scores; '+ 'requires '+ '`match_quality`. '+ 'Together '+ 'they add an '+ 'adequacy '+ 'verdict: '+ 'sufficient/proceed, '+ 'weak/re_recall, '+ 'insufficient/abstain.'},+ 'match_quality': { 'type': 'number',+ 'minimum': 0,+ 'maximum': 1,+ 'description': 'Absolute '+ 'match '+ 'quality in '+ '[0,1]: a '+ 'search '+ "outcome's "+ '`idf_weighted_coverage`. '+ 'Required '+ 'with '+ '`recall_scores`; '+ 'the adequacy '+ 'level reads '+ 'this, never '+ 'a score.'},+ 'decision_answerable': { 'type': 'number',+ 'minimum': 0,+ 'maximum': 1,+ 'description': 'Advisory '+ '[0,1] '+ 'probability '+ 'from a '+ "search's "+ '`decision_model.answerable`. '+ 'Needs '+ '`recall_scores` '+ 'and '+ '`match_quality`; '+ 'never '+ 'changes '+ 'the '+ 'level.'},+ 'telemetry': { 'type': 'boolean',+ 'description': 'When true, emit '+ 'an opt-in recall '+ 'telemetry record '+ 'for this '+ 'context-pack '+ 'run.'},+ 'telemetry_host': { 'type': 'string',+ 'description': 'Optional '+ 'host/runtime '+ 'name for '+ 'emitted '+ 'telemetry; '+ 'defaults to '+ '`mcp`.'},+ 'session_id': { 'type': 'string',+ 'description': 'Optional '+ 'session id '+ 'recorded on '+ 'emitted '+ 'telemetry.'},+ 'turn_id': { 'type': 'string',+ 'description': 'Optional turn id '+ 'recorded on '+ 'emitted '+ 'telemetry.'},+ 'agent_scope': { 'type': 'string',+ 'description': 'Optional '+ 'agent-ownership '+ 'scope; shared '+ '(ownerless) '+ 'memories '+ 'always match, '+ 'owner-tagged '+ 'memories only '+ 'their owner. '+ 'Absent = no '+ 'ownership '+ 'filtering.'}},+ 'dependentRequired': { 'recall_scores': ['match_quality'],+ 'match_quality': ['recall_scores'],+ 'decision_answerable': [ 'recall_scores',+ 'match_quality'],+ 'query_mode': ['query'],+ 'packing_policy': ['query']},+ 'additionalProperties': False}},+ { 'name': 'brain_pre_compact_extract',+ 'description': 'Extract typed Decision/Commitment/Outcome/Rule/Open question records '+ 'from bounded text into continuity storage.',+ 'inputSchema': { 'type': 'object',+ 'properties': { 'session_id': { 'type': 'string',+ 'description': 'Session '+ 'identifier used '+ 'for idempotency '+ 'and source '+ 'refs.'},+ 'turn_start': { 'type': 'string',+ 'description': 'First source '+ 'turn id in the '+ 'extracted '+ 'segment.'},+ 'turn_end': { 'type': 'string',+ 'description': 'Last source turn '+ 'id in the '+ 'extracted '+ 'segment.'},+ 'text': { 'type': 'string',+ 'description': 'Bounded text segment '+ 'to scan for labeled '+ 'extraction lines.'},+ 'host': { 'type': 'string',+ 'description': 'Optional host/client '+ 'label.'},+ 'max_chars': { 'type': 'integer',+ 'minimum': 1,+ 'description': 'Optional maximum '+ 'input characters '+ 'to scan before '+ 'extracting.'},+ 'interrupted': { 'type': 'boolean',+ 'description': 'When true, '+ 'mark the '+ 'extracted '+ 'records as '+ 'flushed by an '+ 'interrupted '+ 'close '+ '(SIGHUP/SIGTERM/force-quit/restart-drain). '+ 'Absent by '+ 'default.'},+ 'dry_run': { 'type': 'boolean',+ 'description': 'Preview the '+ 'candidate records '+ 'extraction would '+ 'append WITHOUT '+ 'writing to the '+ 'vault (no '+ 'continuity record, '+ 'no dream/retire '+ 'trigger). Absent '+ 'by default.'}},+ 'required': ['session_id', 'turn_start', 'turn_end', 'text'],+ 'additionalProperties': False}},+ { 'name': 'brain_query',+ 'description': 'Read-only lookup: one preference + its evidence trail, all artifacts '+ 'under a topic, or every log event after a timestamp. Exactly one of '+ '`preference`, `topic`, `since` must be supplied.',+ 'inputSchema': { 'type': 'object',+ 'properties': { 'preference': { 'type': 'string',+ 'description': 'Preference id '+ '(`pref-...` or '+ '`ret-...`) to '+ 'look up with '+ 'its evidence '+ 'trail.'},+ 'topic': { 'type': 'string',+ 'description': 'Topic slug to '+ 'aggregate signals + '+ 'active/retired '+ 'preference + log '+ 'events.'},+ 'show_expired': { 'type': 'boolean',+ 'description': 'Topic mode '+ 'only: include '+ 'memories past '+ 'their '+ '`expiration_date`. '+ 'Default false '+ '(expired '+ 'memories are '+ 'silently '+ 'dropped from '+ 'the result).'},+ 'at': { 'type': 'string',+ 'description': 'Topic mode only: '+ 'evaluate '+ '`expiration_date` as of '+ 'this instant, so a '+ 'memory that lapsed '+ 'after it comes back. '+ 'ISO-8601 instant or '+ 'YYYY-MM-DD. Default '+ 'now.'},+ 'since': { 'type': 'string',+ 'description': 'ISO-8601 timestamp; '+ 'returns every Brain '+ 'log event with '+ 'timestamp >= since.'},+ 'format': { 'type': 'string',+ 'enum': ['markdown', 'json'],+ 'description': 'Reserved for '+ 'forward-compat; the '+ 'structured response '+ 'is the same '+ 'regardless.'},+ 'telemetry': { 'type': 'boolean',+ 'description': 'Opt-in recall '+ 'telemetry: emit '+ 'one continuity '+ 'record (mode '+ "'query', "+ 'kind-only '+ 'payload) for '+ 'this call.'},+ 'telemetry_host': { 'type': 'string',+ 'maxLength': 200,+ 'description': 'Optional '+ 'host/client '+ 'label '+ 'recorded on '+ 'the '+ 'telemetry '+ 'record.'},+ 'session_id': { 'type': 'string',+ 'maxLength': 512,+ 'description': 'Optional '+ 'session '+ 'correlation id '+ 'recorded on the '+ 'telemetry '+ 'record.'},+ 'turn_id': { 'type': 'string',+ 'maxLength': 512,+ 'description': 'Optional turn '+ 'correlation id '+ 'recorded on the '+ 'telemetry record.'},+ 'agent_scope': { 'type': 'string',+ 'description': 'Optional owner '+ 'scope: with '+ 'owner_scoped_facts '+ 'on, an '+ 'owner-tagged '+ 'fact returns '+ 'only to its '+ 'own scope; '+ 'ownerless '+ 'facts always '+ 'match. Absent '+ '= no '+ 'filtering.'}},+ 'additionalProperties': False}},+ { 'name': 'brain_context_pack_outcome',+ 'description': 'Context-pack outcome loop. `post` records an outcome row for a carried '+ 'sample id — first-pass/repair/retry counters plus three SEPARATE token '+ 'signals (exact, modeled, observed) — calibrates the token-impact '+ "ledger, and records the kernel's on-disk evidence. `list`/`summary` "+ 'read rows. Gated.',+ 'inputSchema': { 'type': 'object',+ 'properties': { 'operation': { 'type': 'string',+ 'enum': [ 'post',+ 'list',+ 'summary'],+ 'description': 'post writes one '+ 'opt-in outcome '+ 'row; '+ 'list/summary '+ 'read the durable '+ 'ledger.'},+ 'sample_id': { 'type': 'string',+ 'description': 'post: the '+ 'carried '+ 'recall/context-pack '+ 'quality-sample '+ 'id (a '+ 'context-receipt '+ 'id or opaque '+ 'request hash) — '+ 'never a raw '+ 'prompt. Also a '+ 'list/summary '+ 'filter.'},+ 'first_pass_success': { 'type': 'boolean',+ 'description': 'post: '+ 'whether '+ 'the '+ 'packed '+ 'context '+ 'led to '+ 'a '+ 'first-pass '+ 'success.'},+ 'repair_required': { 'type': 'boolean',+ 'description': 'post '+ '(optional): '+ 'whether '+ 'the agent '+ 'had to '+ 'repair the '+ 'first '+ 'completion.'},+ 'retry_count': { 'type': 'integer','minimum': 0,- 'description': 'post (optional): '- 'EXACT '- 'tokenizer-aware '- 'prompt-token '- 'savings (a '- 'measurement). Kept '- 'separate from the '- 'modeled and '- 'observed signals.'},- 'modeled_inference_avoidance': {'type': 'number',- 'minimum': 0,- 'description': 'post (optional): '- 'MODELED '- 'confidence-banded '- 'inference-avoidance '- 'estimate (a '- 'model). Kept '- 'separate from the '- 'exact and '- 'observed '- 'signals.'},- 'observed_provider_tokens': {'type': 'number',+ 'description': 'post '+ '(optional): '+ 'how many '+ 'retries the '+ 'completion '+ 'needed.'},+ 'follow_up_tokens': { 'type': 'integer',+ 'minimum': 0,+ 'description': 'post '+ '(optional): '+ 'tokens '+ 'spent on '+ 'follow-up '+ 'turns '+ 'after the '+ 'first '+ 'pass.'},+ 'exact_prompt_token_savings': { 'type': 'number',+ 'minimum': 0,+ 'description': 'post '+ '(optional): '+ 'EXACT '+ 'tokenizer-aware '+ 'prompt-token '+ 'savings '+ '(a '+ 'measurement). '+ 'Kept '+ 'separate '+ 'from '+ 'the '+ 'modeled '+ 'and '+ 'observed '+ 'signals.'},+ 'modeled_inference_avoidance': { 'type': 'number',+ 'minimum': 0,+ 'description': 'post '+ '(optional): '+ 'MODELED '+ 'confidence-banded '+ 'inference-avoidance '+ 'estimate '+ '(a '+ 'model). '+ 'Kept '+ 'separate '+ 'from '+ 'the '+ 'exact '+ 'and '+ 'observed '+ 'signals.'},+ 'observed_provider_tokens': { 'type': 'number',+ 'minimum': 0,+ 'description': 'post '+ '(optional): '+ 'OBSERVED '+ 'provider-reported '+ 'token '+ 'usage. '+ 'Kept '+ 'separate '+ 'from '+ 'the '+ 'exact '+ 'and '+ 'modeled '+ 'signals; '+ 'also '+ 'calibrates '+ 'the '+ 'token-impact '+ 'ledger.'},+ 'evidence_claim': { 'type': 'object',+ 'description': 'post '+ '(optional): '+ 'what you '+ 'assert '+ 'about this '+ 'sample; '+ 'kernel '+ 'reads its '+ 'receipt off '+ 'disk, '+ 'records '+ 'match|mismatch|unclaimed|unresolved. '+ 'Malformed = '+ 'INVALID_PARAMS.',+ 'properties': { 'final_text_hash': { 'type': 'string',+ 'description': 'Claimed '+ 'SHA-256 '+ 'of '+ 'the '+ 'assembled '+ 'pack '+ 'text.'},+ 'item_count': { 'type': 'integer',+ 'minimum': 0,+ 'description': 'Claimed '+ 'number '+ 'of '+ 'artifacts '+ 'the '+ 'pack '+ 'injected.'},+ 'final_text_chars': { 'type': 'integer',+ 'minimum': 0,+ 'description': 'Claimed '+ 'codepoint '+ 'length '+ 'of '+ 'the '+ 'assembled '+ 'pack '+ 'text.'}},+ 'additionalProperties': False},+ 'host': { 'type': 'string',+ 'description': 'Optional host/runtime '+ 'label; also a '+ 'filter.'},+ 'session_id': { 'type': 'string',+ 'description': 'Optional '+ 'session id '+ 'recorded on the '+ 'row.'},+ 'turn_id': { 'type': 'string',+ 'description': 'Optional turn id '+ 'recorded on the '+ 'row.'},+ 'agent_id': { 'type': 'string',+ 'description': 'post (optional): '+ 'the ACTING agent, '+ 'recorded on all '+ 'three rows this '+ 'post lands. '+ 'Self-asserted, '+ 'never a verifier; '+ 'omitted records '+ 'no actor rather '+ 'than a guess.'},+ 'since': { 'type': 'string',+ 'description': 'Optional inclusive '+ 'lower timestamp '+ 'bound.'},+ 'until': { 'type': 'string',+ 'description': 'Optional inclusive '+ 'upper timestamp '+ 'bound.'},+ 'limit': { 'type': 'integer',+ 'minimum': 1,+ 'description': 'Optional maximum '+ 'record count for '+ 'list.'},+ 'max_samples': { 'type': 'integer',+ 'minimum': 1,+ 'description': 'Optional cap '+ 'on the '+ 'most-recent '+ 'rows '+ 'aggregated by '+ 'summary.'}},+ 'required': ['operation'],+ 'additionalProperties': False}},+ { 'name': 'brain_recall_gate',+ 'description': 'Classify whether recall should run. Diagnostics only; does not search. '+ 'Pass `scores` AND `match_quality` together for an adequacy verdict; '+ 'either alone is INVALID_PARAMS (see `dependentRequired`). A '+ 'measurement decides the verdict: below-floor quality answers retrieve '+ 'false. `admit` echoes it.',+ 'inputSchema': { 'type': 'object',+ 'properties': { 'prompt': { 'type': 'string',+ 'minLength': 1,+ 'maxLength': 4000,+ 'description': "The turn's prompt, "+ 'scored to decide '+ 'whether recall is '+ 'worth running at '+ 'all.'},+ 'previous_prompt': { 'type': 'string',+ 'maxLength': 4000,+ 'description': 'The '+ 'preceding '+ "turn's "+ 'prompt, so '+ 'a '+ 'follow-up '+ 'is judged '+ 'in context '+ 'rather '+ 'than on '+ 'its own.'},+ 'explicit': { 'type': 'boolean',+ 'description': 'The user asked '+ 'for memory in so '+ 'many words; the '+ 'gate then '+ 'retrieves '+ 'regardless of '+ 'score. Default '+ 'false.'},+ 'telemetry_host': { 'type': 'string',+ 'maxLength': 200,+ 'description': 'Optional '+ 'host/client '+ 'label '+ 'recorded on '+ 'the '+ 'telemetry '+ 'record.'},+ 'session_id': { 'type': 'string',+ 'maxLength': 512,+ 'description': 'Optional '+ 'session '+ 'correlation id '+ 'recorded on the '+ 'telemetry '+ 'record.'},+ 'turn_id': { 'type': 'string',+ 'maxLength': 512,+ 'description': 'Optional turn '+ 'correlation id '+ 'recorded on the '+ 'telemetry record.'},+ 'scores': { 'type': 'array',+ 'maxItems': 200,+ 'items': {'type': 'number'},+ 'description': 'Optional top-k '+ 'recall scores; '+ 'requires '+ '`match_quality`. '+ 'Together they add '+ 'an adequacy '+ 'verdict: '+ 'sufficient/proceed, '+ 'weak/re_recall, '+ 'insufficient/abstain.'},+ 'match_quality': { 'type': 'number',+ 'minimum': 0,+ 'maximum': 1,+ 'description': 'Absolute '+ 'match '+ 'quality in '+ '[0,1]: a '+ 'search '+ "outcome's "+ '`idf_weighted_coverage`. '+ 'Required '+ 'with '+ '`scores`; '+ 'the adequacy '+ 'level reads '+ 'this, never '+ 'a score.'},+ 'decision_answerable': { 'type': 'number',+ 'minimum': 0,+ 'maximum': 1,+ 'description': 'Advisory '+ '[0,1] '+ 'probability '+ 'from a '+ "search's "+ '`decision_model.answerable`. '+ 'Needs '+ '`scores` '+ 'and '+ '`match_quality`; '+ 'never '+ 'changes '+ 'the '+ 'level.'}},+ 'required': ['prompt'],+ 'dependentRequired': { 'scores': ['match_quality'],+ 'match_quality': ['scores'],+ 'decision_answerable': [ 'scores',+ 'match_quality']},+ 'additionalProperties': False}},+ { 'name': 'brain_search',+ 'description': 'Full-text search across the vault. Optional semantic layer when '+ 'configured. Read-only. When a query misses, consult brain_recall_gate '+ 'before widening recall: it classifies whether widening is warranted.',+ 'inputSchema': { 'type': 'object',+ 'properties': { 'query': { 'type': 'string',+ 'minLength': 1,+ 'maxLength': 2000,+ 'description': 'What to recall from '+ 'the vault. Matched '+ 'against the index by '+ 'keyword, semantics, '+ 'or both.'},+ 'query_document': { 'type': 'string',+ 'minLength': 1,+ 'maxLength': 4000,+ 'description': 'Line-oriented '+ 'query '+ 'program '+ 'with '+ 'intent:, '+ 'lex:, vec: '+ 'and hyde: '+ 'lanes, '+ 'steering '+ 'each '+ 'retrieval '+ 'layer '+ 'separately. '+ 'Absent '+ 'means '+ "'query' "+ 'drives '+ 'every '+ 'lane.'},+ 'focus_query': { 'type': 'string',+ 'minLength': 1,+ 'maxLength': 1000,+ 'description': 'Steer this one '+ 'call towards a '+ 'working-set '+ 'topic without '+ 'persisting a '+ 'session '+ 'focus.'},+ 'focus_path_prefix': { 'type': 'string',+ 'minLength': 1,+ 'maxLength': 256,+ 'description': 'Steer '+ 'this one '+ 'call '+ 'towards '+ 'a vault '+ 'subtree, '+ 'paired '+ 'with '+ 'focus_query '+ 'as a '+ 'transient '+ 'focus.'},+ 'focus_session': { 'type': 'string',+ 'minLength': 1,+ 'maxLength': 128,+ 'description': 'Session id '+ 'whose bound '+ 'focus '+ 'applies '+ '(falls back '+ 'to the '+ 'global '+ 'focus).'},+ 'evidence_pack': { 'type': 'boolean',+ 'description': 'Return the '+ 'evidence '+ 'pack: '+ 'matched/missing '+ 'terms, '+ 'coverage, '+ 'abstention '+ 'text and the '+ 'false-absence '+ 'guard. '+ 'Default '+ 'false.'},+ 'include_superseded': { 'type': 'boolean',+ 'description': 'History '+ 'mode '+ 'for '+ 'relation '+ 'polarity: '+ 'keep '+ 'matched '+ 'superseded '+ 'predecessors '+ 'undemoted '+ 'and '+ 'skip '+ 'successor '+ 'pull-in. '+ 'Default '+ 'false.'},+ 'since': { 'type': 'string',+ 'maxLength': 64,+ 'description': 'Hard filter on event '+ 'time (validity, body '+ 'anchor, mtime last): '+ 'at/after this point. '+ 'ISO date/datetime, '+ 'today, yesterday, '+ 'last week, last '+ 'month, '+ '<n>h/<n>d/<n>w.'},+ 'until': { 'type': 'string',+ 'maxLength': 64,+ 'description': 'Hard filter on event '+ 'time (validity, body '+ 'anchor, mtime last): '+ 'at/before this '+ 'point. Same forms as '+ "'since'."},+ 'limit': { 'type': 'integer',+ 'minimum': 1,+ 'maximum': 50,+ 'description': 'How many ranked '+ 'results to return. '+ 'Default 10.'},+ 'semantic': { 'type': 'boolean',+ 'description': 'Force the '+ 'semantic lane on '+ 'or off. Absent '+ 'lets the '+ 'configured hybrid '+ 'strategy decide.'},+ 'keyword_only': { 'type': 'boolean',+ 'description': 'Skip the '+ 'semantic lane '+ 'entirely, so '+ 'no embedding '+ 'is needed. '+ 'Default '+ 'false.'},+ 'match_mode': { 'type': 'string',+ 'enum': ['all', 'any'],+ 'description': 'FTS match '+ "breadth: 'all' "+ '(default) '+ 'requires every '+ "term; 'any' "+ 'matches a '+ 'document '+ 'carrying any '+ 'one term. '+ 'Absent leaves '+ 'the implicit '+ 'AND.'},+ 'disclosure': { 'type': 'string',+ 'enum': ['full', 'cards'],+ 'description': 'Result depth: '+ "'full' "+ '(default) '+ 'returns full '+ 'chunk content; '+ "'cards' returns "+ 'token-cheap '+ 'layer-1 cards — '+ 'drill a hit '+ 'with '+ 'brain_search_expand.'},+ 'profile': { 'type': 'string',+ 'enum': [ 'fast',+ 'balanced',+ 'thorough'],+ 'description': 'Named recall '+ 'profile '+ '(fast|balanced|thorough): '+ 'a fixed knob '+ 'preset, preferred '+ 'over persisted '+ 'self-tuning. '+ 'Absent leaves '+ 'ranking '+ 'unchanged.'},+ 'explain': { 'type': 'boolean',+ 'description': 'Add a per-result '+ 'score_breakdown '+ 'plus the '+ 'retrieval_decision_trace '+ 'and '+ 'memory_trust_assessment '+ 'receipts. Default '+ 'false.'},+ 'trust': { 'type': 'boolean',+ 'description': 'Stamp each result '+ 'with inline trust '+ 'metadata (age_days, '+ 'superseded, '+ 'conflict), computed '+ 'at read time. '+ 'Default false.'},+ 'threshold': { 'type': 'number','minimum': 0,- 'description': 'post (optional): '- 'OBSERVED '- 'provider-reported '- 'token usage. Kept '- 'separate from the '- 'exact and modeled '- 'signals; also '- 'calibrates the '- 'token-impact '- 'ledger.'},- 'evidence_claim': {'type': 'object',- 'description': 'post (optional): what you '- 'assert about this sample; '- 'kernel reads its receipt off '- 'disk, records '- 'match|mismatch|unclaimed|unresolved. '- 'Malformed = INVALID_PARAMS.',- 'properties': {'final_text_hash': {'type': 'string',- 'description': 'Claimed '- 'SHA-256 '- 'of '- 'the '- 'assembled '- 'pack '- 'text.'},- 'item_count': {'type': 'integer',- 'minimum': 0,- 'description': 'Claimed '- 'number '- 'of '- 'artifacts '- 'the '- 'pack '- 'injected.'},- 'final_text_chars': {'type': 'integer',- 'minimum': 0,- 'description': 'Claimed '- 'codepoint '- 'length '- 'of '- 'the '- 'assembled '- 'pack '- 'text.'}},- 'additionalProperties': False},- 'host': {'type': 'string',- 'description': 'Optional host/runtime label; also a '- 'filter.'},- 'session_id': {'type': 'string',- 'description': 'Optional session id recorded on '- 'the row.'},- 'turn_id': {'type': 'string',- 'description': 'Optional turn id recorded on the '- 'row.'},- 'agent_id': {'type': 'string',- 'description': 'post (optional): the ACTING agent, '- 'recorded on all three rows this post '- 'lands. Self-asserted, never a '- 'verifier; omitted records no actor '- 'rather than a guess.'},- 'since': {'type': 'string',- 'description': 'Optional inclusive lower timestamp '- 'bound.'},- 'until': {'type': 'string',- 'description': 'Optional inclusive upper timestamp '- 'bound.'},- 'limit': {'type': 'integer',- 'minimum': 1,- 'description': 'Optional maximum record count for '- 'list.'},- 'max_samples': {'type': 'integer',- 'minimum': 1,- 'description': 'Optional cap on the most-recent '- 'rows aggregated by summary.'}},- 'required': ['operation'],- 'additionalProperties': False}},- {'name': 'brain_pre_compact_extract',- 'description': 'Extract typed Decision/Commitment/Outcome/Rule/Open question records from '- 'bounded text into continuity storage.',- 'inputSchema': {'type': 'object',- 'properties': {'session_id': {'type': 'string',- 'description': 'Session identifier used for '- 'idempotency and source refs.'},- 'turn_start': {'type': 'string',- 'description': 'First source turn id in the '- 'extracted segment.'},- 'turn_end': {'type': 'string',- 'description': 'Last source turn id in the extracted '- 'segment.'},- 'text': {'type': 'string',- 'description': 'Bounded text segment to scan for labeled '- 'extraction lines.'},- 'host': {'type': 'string',- 'description': 'Optional host/client label.'},- 'max_chars': {'type': 'integer',- 'minimum': 1,- 'description': 'Optional maximum input characters '- 'to scan before extracting.'},- 'interrupted': {'type': 'boolean',- 'description': 'When true, mark the extracted '- 'records as flushed by an '- 'interrupted close '- '(SIGHUP/SIGTERM/force-quit/restart-drain). '- 'Absent by default.'},- 'dry_run': {'type': 'boolean',- 'description': 'Preview the candidate records '- 'extraction would append WITHOUT '- 'writing to the vault (no continuity '- 'record, no dream/retire trigger). '- 'Absent by default.'}},- 'required': ['session_id', 'turn_start', 'turn_end', 'text'],- 'additionalProperties': False}})+ 'maximum': 1,+ 'description': 'Relevance floor '+ 'in [0,1] on the '+ 'final score; '+ 'drops weaker '+ 'hits so an '+ 'irrelevant query '+ 'returns no '+ 'match. Default 0 '+ '(disabled).'},+ 'rerank': { 'type': 'boolean',+ 'description': 'Re-order the '+ 'threshold-qualified '+ 'results by core '+ 'textual relevance '+ '(keyword + '+ 'semantic). Default '+ 'false.'},+ 'reinforce': { 'type': 'array',+ 'maxItems': 50,+ 'items': { 'type': 'string',+ 'minLength': 1,+ 'maxLength': 512},+ 'description': 'Paths proven '+ 'useful: recorded '+ 'to the reinforce '+ 'ledger and '+ 'lifted (bounded) '+ 'before the top_k '+ 'cut. Default '+ 'absent.'},+ 'record_access': { 'type': 'boolean',+ 'description': 'Record the '+ 'surfaced '+ 'paths as one '+ 'activation '+ 'access event '+ '(feeds the '+ 'usage-aware '+ 'ranking '+ 'layer). '+ 'Default '+ 'true; never '+ 'recorded for '+ 'global '+ 'searches.'},+ 'global': { 'type': 'boolean',+ 'description': 'Cross-vault union: '+ 'search profile '+ 'vaults and '+ 'read-only recall '+ 'sources too, '+ 'merging results '+ 'with origin labels. '+ 'Default false '+ '(active vault '+ 'only).'},+ 'path_prefix': { 'type': 'string',+ 'maxLength': 256,+ 'description': 'Restrict '+ 'results to '+ 'this vault '+ 'subtree. '+ 'Absent '+ 'searches the '+ 'whole vault.'},+ 'telemetry': { 'type': 'boolean',+ 'description': 'Emit one '+ 'recall-telemetry '+ 'continuity '+ 'record for this '+ 'call. Default '+ 'false.'},+ 'telemetry_host': { 'type': 'string',+ 'maxLength': 200,+ 'description': 'Optional '+ 'host/client '+ 'label '+ 'recorded on '+ 'the '+ 'telemetry '+ 'record.'},+ 'session_id': { 'type': 'string',+ 'maxLength': 512,+ 'description': 'Optional '+ 'session '+ 'correlation id '+ 'recorded on the '+ 'telemetry '+ 'record.'},+ 'turn_id': { 'type': 'string',+ 'maxLength': 512,+ 'description': 'Optional turn '+ 'correlation id '+ 'recorded on the '+ 'telemetry record.'},+ 'properties': { 'type': 'object',+ 'description': 'Optional '+ 'frontmatter '+ 'filter; values '+ 'within a key '+ 'OR, keys AND. '+ 'type, pinned, '+ 'visibility as '+ 'indexed; other '+ 'keys narrow on '+ 'the attribute '+ 'snapshot, '+ 'judged live.',+ 'additionalProperties': { 'type': 'array',+ 'items': { 'type': 'string'}}},+ 'kind': { 'type': 'string',+ 'enum': ['page', 'section'],+ 'description': 'Restrict candidates '+ "by chunk kind: 'page' "+ 'matches each '+ "document's "+ 'frontmatter/head '+ 'chunk (chunk 0), '+ "'section' everything "+ 'after it. Absent '+ 'searches all chunks.'},+ 'degree': { 'type': 'array',+ 'description': 'Graph-degree '+ 'predicates over '+ 'backlink/outlink '+ 'counts, e.g. '+ "'backlinks=0' "+ '(orphans) or '+ "'outlinks>=5' "+ '(hubs); ANDed. '+ 'Absent = no filter.',+ 'items': {'type': 'string'}},+ 'visibility': { 'type': 'array',+ 'description': 'Optional '+ 'content-visibility '+ 'scope; untagged '+ 'pages always '+ 'match, tagged '+ 'pages only when '+ 'this scope '+ 'includes one of '+ 'their values.',+ 'items': {'type': 'string'}},+ 'agent_scope': { 'type': 'string',+ 'description': 'Optional '+ 'agent-ownership '+ 'scope; shared '+ '(ownerless) '+ 'pages always '+ 'match, '+ 'owner-tagged '+ 'pages only '+ 'their owner. '+ 'Absent = no '+ 'ownership '+ 'filtering.'},+ 'session_scope': { 'type': 'string',+ 'description': 'Optional '+ 'session-scope '+ 'filter; '+ 'pages with '+ 'no session '+ 'always '+ 'match, '+ 'session-tagged '+ 'pages only '+ 'this '+ 'session. '+ 'Absent = no '+ 'session '+ 'filtering.'},+ 'project_scope': { 'type': 'string',+ 'description': 'Optional '+ 'project-scope '+ 'filter; '+ 'pages with '+ 'no project '+ 'always '+ 'match, '+ 'project-tagged '+ 'pages only '+ 'this '+ 'project. '+ 'Absent = no '+ 'project '+ 'filtering.'},+ 'iterative': { 'type': 'boolean',+ 'description': 'Opt in to the '+ 'bounded '+ 'iterative recall '+ 'loop (default '+ 'off). Surviving '+ 'gaps pause with '+ 'a plan; resume '+ 'via '+ 'iterative_payload. '+ 'Inert unless the '+ 'knob is on.'},+ 'iterative_token': { 'type': 'string',+ 'maxLength': 128,+ 'description': 'The round '+ 'token from '+ 'a '+ 'plan-phase '+ 'response, '+ 'submitted '+ 'beside '+ 'iterative_payload. '+ 'Requires '+ 'iterative: '+ 'true; '+ 'single use '+ '- a '+ 'replayed '+ 'token is '+ 'refused by '+ 'name.'},+ 'iterative_payload': { 'type': 'object',+ 'description': 'Decider '+ 'payload '+ 'answering '+ 'a '+ 'plan-phase '+ 'envelope: '+ '{ '+ 'evidence: '+ '[chunkId, '+ '...], '+ 'subQueries: '+ '[...] }, '+ 'validated '+ 'before '+ 'any pull '+ 'runs. '+ 'Requires '+ 'iterative_token.'}},+ 'required': ['query'],+ 'additionalProperties': False}})def static_tool_schemas() -> list[dict[str, Any]]:diff --git a/plugins/hermes/plugin.yaml b/plugins/hermes/plugin.yamlindex d8f79a58..2d2b8b3e 100644--- a/plugins/hermes/plugin.yaml+++ b/plugins/hermes/plugin.yaml@@ -1,5 +1,5 @@name: open-second-brain-version: "1.89.0"+version: "1.90.0"description: "Open Second Brain - native Hermes memory provider backed by an Obsidian-compatible Markdown vault."author: "Open Second Brain contributors"memory_provider: truediff --git a/pyproject.toml b/pyproject.tomlindex 91014d96..a0a8cb3b 100644--- a/pyproject.toml+++ b/pyproject.toml@@ -12,7 +12,7 @@ build-backend = "setuptools.build_meta"# `hermes_agent.memory_providers` group, not a CLI script.[project]name = "open-second-brain"-version = "1.89.0"+version = "1.90.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/schemas/brain/search-query.schema.json b/schemas/brain/search-query.schema.jsonnew file mode 100644index 00000000..79b1e956--- /dev/null+++ b/schemas/brain/search-query.schema.json@@ -0,0 +1,231 @@+{+ "$schema": "https://json-schema.org/draft/2020-12/schema",+ "$id": "brain.search_query.v1",+ "title": "Brain Search Query v1",+ "description": "The brain_search query language: every argument the MCP tool accepts, published as a versioned JSON Schema (draft 2020-12). The same table derives the served tools/list inputSchema and the o2b search CLI flags; see $defs.search_query_document for the line-oriented query_document grammar.",+ "type": "object",+ "required": ["query"],+ "additionalProperties": false,+ "properties": {+ "query": {+ "type": "string",+ "minLength": 1,+ "maxLength": 2000,+ "description": "What to recall from the vault. Matched against the index by keyword, semantics, or both."+ },+ "query_document": {+ "type": "string",+ "minLength": 1,+ "maxLength": 4000,+ "description": "Line-oriented query program with intent:, lex:, vec: and hyde: lanes, steering each retrieval layer separately. Absent means 'query' drives every lane."+ },+ "focus_query": {+ "type": "string",+ "minLength": 1,+ "maxLength": 1000,+ "description": "Steer this one call towards a working-set topic without persisting a session focus."+ },+ "focus_path_prefix": {+ "type": "string",+ "minLength": 1,+ "maxLength": 256,+ "description": "Steer this one call towards a vault subtree, paired with focus_query as a transient focus."+ },+ "focus_session": {+ "type": "string",+ "minLength": 1,+ "maxLength": 128,+ "description": "Session id whose bound focus applies (falls back to the global focus)."+ },+ "evidence_pack": {+ "type": "boolean",+ "description": "Return the evidence pack: matched/missing terms, coverage, abstention text and the false-absence guard. Default false."+ },+ "include_superseded": {+ "type": "boolean",+ "description": "History mode for relation polarity: keep matched superseded predecessors undemoted and skip successor pull-in. Default false."+ },+ "since": {+ "type": "string",+ "maxLength": 64,+ "description": "Hard filter on event time (validity, body anchor, mtime last): at/after this point. ISO date/datetime, today, yesterday, last week, last month, <n>h/<n>d/<n>w."+ },+ "until": {+ "type": "string",+ "maxLength": 64,+ "description": "Hard filter on event time (validity, body anchor, mtime last): at/before this point. Same forms as 'since'."+ },+ "limit": {+ "type": "integer",+ "minimum": 1,+ "maximum": 50,+ "description": "How many ranked results to return. Default 10."+ },+ "semantic": {+ "type": "boolean",+ "description": "Force the semantic lane on or off. Absent lets the configured hybrid strategy decide."+ },+ "keyword_only": {+ "type": "boolean",+ "description": "Skip the semantic lane entirely, so no embedding is needed. Default false."+ },+ "match_mode": {+ "type": "string",+ "enum": ["all", "any"],+ "description": "FTS match breadth: 'all' (default) requires every term; 'any' matches a document carrying any one term. Absent leaves the implicit AND."+ },+ "disclosure": {+ "type": "string",+ "enum": ["full", "cards"],+ "description": "Result depth: 'full' (default) returns full chunk content; 'cards' returns token-cheap layer-1 cards — drill a hit with brain_search_expand."+ },+ "profile": {+ "type": "string",+ "enum": ["fast", "balanced", "thorough"],+ "description": "Named recall profile (fast|balanced|thorough): a fixed knob preset, preferred over persisted self-tuning. Absent leaves ranking unchanged."+ },+ "explain": {+ "type": "boolean",+ "description": "Add a per-result score_breakdown plus the retrieval_decision_trace and memory_trust_assessment receipts. Default false."+ },+ "trust": {+ "type": "boolean",+ "description": "Stamp each result with inline trust metadata (age_days, superseded, conflict), computed at read time. Default false."+ },+ "threshold": {+ "type": "number",+ "minimum": 0,+ "maximum": 1,+ "description": "Relevance floor in [0,1] on the final score; drops weaker hits so an irrelevant query returns no match. Default 0 (disabled)."+ },+ "rerank": {+ "type": "boolean",+ "description": "Re-order the threshold-qualified results by core textual relevance (keyword + semantic). Default false."+ },+ "reinforce": {+ "type": "array",+ "maxItems": 50,+ "items": {+ "type": "string",+ "minLength": 1,+ "maxLength": 512+ },+ "description": "Paths proven useful: recorded to the reinforce ledger and lifted (bounded) before the top_k cut. Default absent."+ },+ "record_access": {+ "type": "boolean",+ "description": "Record the surfaced paths as one activation access event (feeds the usage-aware ranking layer). Default true; never recorded for global searches."+ },+ "global": {+ "type": "boolean",+ "description": "Cross-vault union: search profile vaults and read-only recall sources too, merging results with origin labels. Default false (active vault only)."+ },+ "path_prefix": {+ "type": "string",+ "maxLength": 256,+ "description": "Restrict results to this vault subtree. Absent searches the whole vault."+ },+ "telemetry": {+ "type": "boolean",+ "description": "Emit one recall-telemetry continuity record for this call. Default false."+ },+ "telemetry_host": {+ "type": "string",+ "maxLength": 200,+ "description": "Optional host/client label recorded on the telemetry record."+ },+ "session_id": {+ "type": "string",+ "maxLength": 512,+ "description": "Optional session correlation id recorded on the telemetry record."+ },+ "turn_id": {+ "type": "string",+ "maxLength": 512,+ "description": "Optional turn correlation id recorded on the telemetry record."+ },+ "properties": {+ "type": "object",+ "description": "Optional frontmatter filter; values within a key OR, keys AND. type, pinned, visibility as indexed; other keys narrow on the attribute snapshot, judged live.",+ "additionalProperties": {+ "type": "array",+ "items": {+ "type": "string"+ }+ }+ },+ "kind": {+ "type": "string",+ "enum": ["page", "section"],+ "description": "Restrict candidates by chunk kind: 'page' matches each document's frontmatter/head chunk (chunk 0), 'section' everything after it. Absent searches all chunks."+ },+ "degree": {+ "type": "array",+ "description": "Graph-degree predicates over backlink/outlink counts, e.g. 'backlinks=0' (orphans) or 'outlinks>=5' (hubs); ANDed. Absent = no filter.",+ "items": {+ "type": "string"+ }+ },+ "visibility": {+ "type": "array",+ "description": "Optional content-visibility scope; untagged pages always match, tagged pages only when this scope includes one of their values.",+ "items": {+ "type": "string"+ }+ },+ "agent_scope": {+ "type": "string",+ "description": "Optional agent-ownership scope; shared (ownerless) pages always match, owner-tagged pages only their owner. Absent = no ownership filtering."+ },+ "session_scope": {+ "type": "string",+ "description": "Optional session-scope filter; pages with no session always match, session-tagged pages only this session. Absent = no session filtering."+ },+ "project_scope": {+ "type": "string",+ "description": "Optional project-scope filter; pages with no project always match, project-tagged pages only this project. Absent = no project filtering."+ },+ "iterative": {+ "type": "boolean",+ "description": "Opt in to the bounded iterative recall loop (default off). Surviving gaps pause with a plan; resume via iterative_payload. Inert unless the knob is on."+ },+ "iterative_token": {+ "type": "string",+ "maxLength": 128,+ "description": "The round token from a plan-phase response, submitted beside iterative_payload. Requires iterative: true; single use - a replayed token is refused by name."+ },+ "iterative_payload": {+ "type": "object",+ "description": "Decider payload answering a plan-phase envelope: { evidence: [chunkId, ...], subQueries: [...] }, validated before any pull runs. Requires iterative_token."+ }+ },+ "$defs": {+ "search_query_document": {+ "$id": "brain.search_query_document.v1",+ "title": "Brain Search Query Document v1",+ "description": "Line-oriented query program steering each retrieval layer separately. One '<lane>: <value>' line per lane; blank lines and #-comments are ignored. At least one lane is required; the intent lane may appear at most once.",+ "type": "object",+ "required": [],+ "additionalProperties": false,+ "properties": {+ "intent": {+ "type": "string",+ "enum": ["neutral", "exact", "entity", "broad"],+ "description": "Retrieval posture: neutral (default ranking), exact (verbatim phrase preference), entity (tightly scoped subject), broad (recall-favouring). At most one intent line."+ },+ "lex": {+ "type": "string",+ "description": "Keyword-lane tokens, space separated; quote a multi-word token. A leading '-' excludes the token. Repeatable: later lex lines add tokens."+ },+ "vec": {+ "type": "string",+ "description": "Embedding-lane query text. Repeatable: later vec lines add queries."+ },+ "hyde": {+ "type": "string",+ "description": "Hypothetical passage the answer would look like. Repeatable: later hyde lines add passages."+ }+ }+ }+ }+}diff --git a/scripts/search-schema.ts b/scripts/search-schema.tsnew file mode 100644index 00000000..700857d3--- /dev/null+++ b/scripts/search-schema.ts@@ -0,0 +1,26 @@+/**+ * `bun run search-schema` / `bun run search-schema:check` - the+ * regeneration driver for the committed search-query artifact+ * (t_50c81d5c, Task E4), matching the sync-version / sync-plugin-mirrors+ * script pattern: regeneration is a human action, freshness is enforced+ * by check (exit 2 on drift), never by a test writing to the repo.+ *+ * - no args (or `export`): rewrite schemas/brain/search-query.schema.json+ * from the descriptor;+ * - `--check` (or `check`): re-derive and diff, exit 0 clean / 2 drift.+ */++import { cmdSearchSchema } from "../src/cli/search/verbs/schema-export.ts";++const arg = process.argv[2];+const verb =+ arg === undefined || arg === "export"+ ? ["export"]+ : arg === "--check" || arg === "check"+ ? ["check"]+ : null;+if (verb === null) {+ process.stderr.write(`usage: bun run scripts/search-schema.ts [export|--check]\n`);+ process.exit(2);+}+process.exit(await cmdSearchSchema(verb));diff --git a/src/cli/brain/help-text.ts b/src/cli/brain/help-text.tsindex 83441465..a3d18920 100644--- a/src/cli/brain/help-text.ts+++ b/src/cli/brain/help-text.ts@@ -1059,11 +1059,16 @@ export const VERB_HELP: Record<string, string> = {"threshold (default 200000; override via --warn-threshold or the\n" +"BRAIN_TOKEN_WARN_THRESHOLD env var).\n","context-pack":- "usage: o2b brain context-pack --max-tokens <n> [--query <q>] [--lanes] [--cache-stable] [--dedup-repeated]\n" ++ "usage: o2b brain context-pack [--max-tokens <n>] [--model <name>] [--query <q>] [--lanes] [--cache-stable] [--dedup-repeated]\n" +" [--receipt] [--receipt-host <name>] [--telemetry] [--telemetry-host <name>]\n" +" [--session-id <id>] [--turn-id <id>] [--vault <path>] [--json]\n" +"Return the highest-tier, most recent vault slice that fits under\n" +- "<n> tokens. Items ordered core → supporting → peripheral, then\n" ++ "<n> tokens. --max-tokens is optional: when omitted, the budget derives\n" ++ "from the model context window (the vault's context: block, the\n" ++ "environment override, or --model; the matching preset's budget), and\n" ++ "--json names the deciding channel in max_tokens_source. With nothing\n" ++ "resolvable the verb refuses - it never picks a budget silently. Items\n" ++ "ordered core → supporting → peripheral, then\n" +"newest first. Stops adding pages when the next page would exceed\n" +"the budget. --query <q> filters by NFKC+casefold substring match\n" +"on topic + principle. --lanes also returns directives, constraints,\n" +@@ -1084,7 +1089,10 @@ export const VERB_HELP: Record<string, string> = {"usage: o2b brain context-presets show [preset-id] [--json]\n" +" o2b brain context-presets suggest [--model <name>] [--context-window <tokens>] [--json]\n" +" o2b brain context-presets diff <preset-id> [current-value flags] [--override <path>...] [--json]\n" +- "Dry-run model-aware context budget preset diagnostics. Never writes config.\n",+ "Dry-run model-aware context budget preset diagnostics. Never writes config.\n" ++ "With --model alone (no --context-window), the window resolves from the model id\n" ++ "first (declared table, then a trailing 1m suffix); a preset hint answers only\n" ++ "when nothing places the id, and the reason names what decided.\n","pre-compact-extract":"usage: o2b brain pre-compact-extract --vault <path> --session-id <id> --turn-start <id> --turn-end <id> --text <text> [--host <name>] [--max-chars <n>] [--dry-run] [--json]\n" +"Extract Decision/Commitment/Outcome/Rule/Open question lines into idempotent continuity records.\n" +diff --git a/src/cli/brain/verbs/bench.ts b/src/cli/brain/verbs/bench.tsindex 371e4024..897c7f7a 100644--- a/src/cli/brain/verbs/bench.ts+++ b/src/cli/brain/verbs/bench.ts@@ -14,6 +14,7 @@ import { existsSync } from "node:fs";import { join, resolve } from "node:path";import { loadBenchFixture } from "../../../core/bench/fixture.ts";+import { BenchRefusalError } from "../../../core/bench/guards.ts";import { LONGMEMEVAL_SUITE_NAME, loadLongMemEvalFixture } from "../../../core/bench/longmemeval.ts";import { loadLocomoFixture } from "../../../core/bench/locomo.ts";import { loadReplayBenchFixture } from "../../../core/bench/replay.ts";@@ -444,18 +445,31 @@ export async function cmdBrainBench(argv: string[]): Promise<number> {typeof flags["recall-floor"] === "string" ? flags["recall-floor"] : undefined,);- const report = await runMemoryBench({- fixture,- runsDir,- ...(suite !== "" ? { suite } : {}),- capabilities: registration.capabilities,- ...(pinnedKnobs !== null ? { pinnedKnobs } : {}),- ...(recallFloor !== undefined ? { recallFloor } : {}),- ...(sample !== undefined ? { sample } : {}),- ...(loaded.receipt !== undefined ? { suiteReceipt: loaded.receipt } : {}),- ...(resume !== undefined && resume !== "" ? { resume } : {}),- ...(judgeCmd !== undefined ? { judgeCmd } : {}),- });+ // Refusals render the guard contract on stderr and exit nonzero: the+ // BenchRefusalError message IS the render - `refused (<kind>): <detail>`+ // - and every detail names the repair (--resume, a fresh run, a+ // writable --runs-dir). Any other error keeps propagating to the+ // dispatcher untouched.+ let report: BenchReport;+ try {+ report = await runMemoryBench({+ fixture,+ runsDir,+ ...(suite !== "" ? { suite } : {}),+ 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 } : {}),+ });+ } catch (e) {+ if (e instanceof BenchRefusalError) {+ return fail(`brain bench memory: ${e.message}`);+ }+ throw e;+ }if (flags["json"] === true) {process.stdout.write(`${JSON.stringify(report, null, 2)}\n`);diff --git a/src/cli/brain/verbs/context-pack.ts b/src/cli/brain/verbs/context-pack.tsindex cf79eecc..302a4a29 100644--- a/src/cli/brain/verbs/context-pack.ts+++ b/src/cli/brain/verbs/context-pack.ts@@ -4,9 +4,30 @@* Intended for agents priming a context window without manual page* curation. `--query <q>` adds a case/Unicode-insensitive substring* filter on topic + principle.+ *+ * `--max-tokens` is optional (t_a567cc12): when it is omitted, the+ * budget derives from the model context window the shared resolver+ * resolves - the vault's `context:` block, the environment override, or+ * `--model`, in that precedence - through the matching preset. A+ * hint-matching id budgets from its preset hint, the same mapping+ * `brain context-presets suggest` answers. An id nothing published+ * places - no table row, no `1m` suffix, no hint - is refused: pass+ * `--max-tokens` or set `context.window_tokens`. With nothing resolvable+ * the verb refuses exactly as it always has: never a silent default+ * budget.*/+import {+ presetForResolvedWindow,+ unrecognisedModelBudgetRefusal,+} from "../../../core/brain/context-presets.ts";+import {+ resolveModelContextWindowTokens,+ type ModelWindowSource,+} from "../../../core/brain/model-window.ts";+import { resolveModelContextWindowEnvTokens } from "../../../core/config.ts";import { packContext } from "../../../core/brain/context-pack.ts";+import { loadBrainConfig } from "../../../core/brain/policy.ts";import { RECALL_CHANNEL } from "../../../core/brain/recall-telemetry.ts";import { brainVerbContext, fail, okJson, parse } from "../helpers.ts";@@ -15,6 +36,7 @@ export async function cmdBrainContextPack(argv: string[]): Promise<number> {vault: { type: "string" },json: { type: "boolean" },"max-tokens": { type: "string" },+ model: { type: "string" },query: { type: "string" },lanes: { type: "boolean" },receipt: { type: "boolean" },@@ -28,15 +50,51 @@ export async function cmdBrainContextPack(argv: string[]): Promise<number> {});const { vault } = brainVerbContext(flags);- const maxTokensRaw = flags["max-tokens"] as string | undefined;- if (!maxTokensRaw) {- return fail("brain context-pack: --max-tokens <n> is required");- }- // Strict integer parsing - `Number()` rejects partial numeric- // strings like "12abc" that `parseInt` would silently accept.- const maxTokens = Number(maxTokensRaw);- if (!Number.isInteger(maxTokens) || maxTokens <= 0) {- return fail(`brain context-pack: --max-tokens must be a positive integer; got ${maxTokensRaw}`);+ const model = trimOrUndefined(flags["model"]);+ const maxTokensRaw = trimOrUndefined(flags["max-tokens"]);+ let maxTokens: number;+ let maxTokensSource: ModelWindowSource | undefined;+ if (maxTokensRaw !== undefined) {+ // Strict integer parsing - `Number()` rejects partial numeric+ // strings like "12abc" that `parseInt` would silently accept.+ maxTokens = Number(maxTokensRaw);+ if (!Number.isInteger(maxTokens) || maxTokens <= 0) {+ return fail(+ `brain context-pack: --max-tokens must be a positive integer; got ${maxTokensRaw}`,+ );+ }+ } else {+ // Derivation path (t_a567cc12). The vault channel is fail-soft: a+ // broken `_brain.yaml` raises later, inside `packContext`, exactly as+ // it always has. A malformed env value refuses here under its own+ // name - an operator typo must not silently shrink the budget to the+ // default.+ const operatorWindow = contextWindowConfigValue(vault);+ let envWindow: number | undefined;+ try {+ envWindow = resolveModelContextWindowEnvTokens();+ } catch (exc) {+ return fail(`brain context-pack: ${(exc as Error).message}`);+ }+ if (model === undefined && operatorWindow === undefined && envWindow === undefined) {+ return fail("brain context-pack: --max-tokens <n> is required");+ }+ const resolved = resolveModelContextWindowTokens({+ ...(model !== undefined ? { model } : {}),+ ...(operatorWindow !== undefined ? { operatorWindowTokens: operatorWindow } : {}),+ ...(envWindow !== undefined ? { envWindowTokens: envWindow } : {}),+ });+ // The hint fallback rides along exactly when the resolver's answer is+ // the default-sourced assumption, so a hint-only model budgets the+ // preset `brain context-presets suggest` names for it; the source+ // printed below stays the window's. An id NOTHING places - no table+ // row, no suffix, no hint - refuses instead: the conservative posture+ // this verb held before derivation existed, never the default+ // window's long-context budget an 8k local model cannot hold.+ const refusal = unrecognisedModelBudgetRefusal(model, resolved);+ if (refusal !== null) return fail(`brain context-pack: ${refusal}`);+ maxTokens = presetForResolvedWindow(model, resolved).context_pack.max_tokens;+ maxTokensSource = resolved.source;}// `packContext` reads the guardrail block and raises on a `_brain.yaml`@@ -94,6 +152,7 @@ export async function cmdBrainContextPack(argv: string[]): Promise<number> {if (flags["json"]) {okJson({max_tokens: report.maxTokens,+ ...(maxTokensSource !== undefined ? { max_tokens_source: maxTokensSource } : {}),tokens_used: report.tokensUsed,items: report.items.map((i) => ({id: i.id,@@ -116,6 +175,9 @@ export async function cmdBrainContextPack(argv: string[]): Promise<number> {}process.stdout.write(`tokens used: ${report.tokensUsed} / ${report.maxTokens}\n`);+ if (maxTokensSource !== undefined) {+ process.stdout.write(`budget source: ${maxTokensSource}\n`);+ }process.stdout.write(`pages included: ${report.items.length}\n`);process.stdout.write(`pages skipped: ${report.skipped.length}\n\n`);if (report.receiptId) process.stdout.write(`receipt: ${report.receiptId}\n`);@@ -125,6 +187,20 @@ export async function cmdBrainContextPack(argv: string[]): Promise<number> {return 0;}+/**+ * The vault's declared `context.window_tokens`; `undefined` when the+ * block is absent or the file cannot be read. Fail-soft on purpose: a+ * broken `_brain.yaml` raises later, inside `packContext`, exactly as it+ * always has.+ */+function contextWindowConfigValue(vault: string): number | undefined {+ try {+ return loadBrainConfig(vault).context?.window_tokens;+ } catch {+ return undefined;+ }+}+function trimOrDefault(value: string | boolean | string[] | undefined, fallback: string): string {return trimOrUndefined(value) ?? fallback;}diff --git a/src/cli/command-manifest.ts b/src/cli/command-manifest.tsindex 7faeb6e5..625cb67d 100644--- a/src/cli/command-manifest.ts+++ b/src/cli/command-manifest.ts@@ -912,6 +912,28 @@ export const CLI_COMMAND_MANIFEST: CliRootManifest = Object.freeze({flag("use", "string"),],),+ command(+ "eval",+ "Run or list the preregistered per-use evals (real spend; a promote writes the machine-side tuning mark)",+ [],+ [+ command(+ "run",+ "Grade the preregistered take for --use over the configured adapter; a promote verdict marks the profile-use pair tuned",+ [flag("use", "string"), flag("vault", "string"), flag("config", "string")],+ ),+ command(+ "list",+ "List cached decision_model_eval_grade records, oldest first; malformed records are skipped with a named note",+ [+ flag("use", "string"),+ flag("since", "string"),+ flag("vault", "string"),+ flag("config", "string"),+ ],+ ),+ ],+ ),],),command(@@ -1037,6 +1059,15 @@ export const CLI_COMMAND_MANIFEST: CliRootManifest = Object.freeze({flag("apply", "boolean"),],),+ // Both `schema` subcommands parse `--json` (export also `--stdout`),+ // so the inherited stand-in covers the one and `stdout` is declared+ // here; `tests/cli/search-query-flag-manifest.test.ts` holds this+ // row to both parse schemas like every sibling above.+ command(+ "schema",+ "Export or check the versioned search-query JSON Schema artifact (check exits 2 on drift from the descriptor)",+ [flag("stdout", "boolean")],+ ),// The whole `parseFlags` schema, for the reason the two builders// above give: there is no per-verb `--help` on this family, so a// flag the manifest does not model is a flag neither help nordiff --git a/src/cli/decision-model.ts b/src/cli/decision-model.tsindex c200fa8c..93adb33b 100644--- a/src/cli/decision-model.ts+++ b/src/cli/decision-model.ts@@ -4,16 +4,31 @@* check [--ping] the configured state: enabled or not, provider, base* URL, pinned model, the key variable's NAME and whether* it is set (never the value), per-use modes, vault- * opt-out, cost gate and today's spend, processor terms.+ * opt-out, cost gate and today's spend, processor terms,+ * the measured tuning state and the cached eval grades.* `--ping` sends one request over a synthetic state that* carries no vault content. Exit 1 only for a broken* configured provider (invalid config, or a failed ping* of an active one); a missing key is exit 0.- * report per use: calls, outcome mix, latency, tokens, cost, and- * rerank shadow agreement, from `decision_model_call`- * records.+ * report per use: calls, outcome mix, latency, tokens, cost,+ * rerank shadow agreement and the cached eval grades,+ * from `decision_model_call` and+ * `decision_model_eval_grade` records.+ * eval run the preregistered eval for one use (`--use`), over+ * the configured adapter: real spend, counted toward+ * the daily gate. A use that is off is refused by+ * name before anything is sent. A promote verdict+ * writes the machine-side tuning mark only when the+ * grade record exists and the day's recorded spend+ * stayed under the gate; anything else leaves the+ * gate exactly as it was.+ * eval list the cached grade records, oldest first, in prose or+ * `--json`; malformed records are skipped with a named+ * note, never silently.*- * Both are read-only; neither writes to the vault.+ * check and list are read-only. eval run writes only the grade record in+ * the vault's continuity log and, on a promote, the mark under the+ * platform state root.*/import { CliError, parseFlags } from "./argparse.ts";@@ -24,12 +39,22 @@ import {decisionModelCheckExitCode,renderDecisionModelCheck,renderDecisionModelReport,+ renderEvalGradeLine,+ type DecisionEvalGradeLine,} from "../core/decision-model/diagnostics.ts";-import { isDecisionModelUse } from "../core/decision-model/contract.ts";+import { isDecisionModelUse, type DecisionModelUse } from "../core/decision-model/contract.ts";+import { resolveDecisionModelConfig } from "../core/decision-model/config.ts";+import { decisionEvalSpecFor } from "../core/decision-model/eval-spec.ts";+import { runDecisionModelEval } from "../core/decision-model/eval/grade.ts";+import { listDecisionModelEvalGrades } from "../core/decision-model/record.ts";+import { processDirsEnv } from "../core/platform-dirs.ts";const USAGE ="usage: o2b decision-model check [--ping] [--vault <path>] [--config <path>] [--json]\n" +" o2b decision-model report [--since <date>] [--use <use>] [--vault <path>] " ++ "[--config <path>] [--json]\n" ++ " o2b decision-model eval run --use <use> [--vault <path>] [--config <path>] [--json]\n" ++ " o2b decision-model eval list [--use <use>] [--since <date>] [--vault <path>] " +"[--config <path>] [--json]\n";function resolveTargets(flags: Record<string, unknown>): {@@ -106,6 +131,171 @@ function reportVerb(argv: ReadonlyArray<string>): number {return 0;}+function sinceFlag(flags: Record<string, unknown>): string | undefined {+ const sinceRaw = flags["since"] as string | undefined;+ if (sinceRaw === undefined) return undefined;+ const ms = Date.parse(sinceRaw);+ if (!Number.isFinite(ms)) throw new CliError(`--since must be a date, got '${sinceRaw}'`);+ return new Date(ms).toISOString();+}++function useFlag(flags: Record<string, unknown>): DecisionModelUse | undefined {+ const use = flags["use"] as string | undefined;+ if (use !== undefined && !isDecisionModelUse(use)) {+ throw new CliError(`--use must be a decision-model use, got '${use}'`);+ }+ return use;+}++/** The cached grades as the CLI's list verb and its JSON print them. */+function gradeLines(+ vault: string,+ since: string | undefined,+ use: DecisionModelUse | undefined,+): { grades: DecisionEvalGradeLine[]; skipped: string[] } {+ const { grades, skipped } = listDecisionModelEvalGrades(vault, since);+ const lines: DecisionEvalGradeLine[] = grades+ .filter((g) => use === undefined || g.use === use)+ .map((g) => ({+ record_id: g.recordId,+ created_at: g.createdAt,+ use: g.use,+ profile: g.profile,+ verdict: g.verdict,+ spec_hash: g.specHash,+ counted_n: g.countedN,+ counted_error: g.countedError,+ baseline_error: g.baselineError,+ dev_error: g.devError,+ }));+ return { grades: lines, skipped: [...skipped] };+}++async function evalRunVerb(argv: ReadonlyArray<string>): Promise<number> {+ const { flags, positional } = parseFlags(argv, {+ vault: { type: "string" },+ config: { type: "string" },+ use: { type: "string" },+ });+ if (positional.length > 0) {+ throw new CliError(+ `decision-model eval run takes no positional arguments: ${positional.join(" ")}`,+ );+ }+ const use = useFlag(flags);+ if (use === undefined) throw new CliError("decision-model eval run needs --use <use>");+ const { config, vault } = resolveTargets(flags);+ // The same resolution the check verb reports: an inactive config is a+ // refusal naming the surface that explains it, not a half-run.+ const cfg = resolveDecisionModelConfig({+ config,+ vault,+ secretsVault: vault ?? undefined,+ });+ if (cfg.status !== "active") {+ throw new CliError(+ `decision-model eval run needs an active config (status ${cfg.status}); ` ++ "run `o2b decision-model check` for what is missing",+ );+ }+ // A use that is off measures nothing: the runner's mode override would+ // send no request, score every item degraded, cache that junk grade+ // record and exit 0. Refuse by name before grading - but keep the+ // specless use's own preregistration error, which already says the+ // same thing from the registry side.+ if (decisionEvalSpecFor(use) !== null && cfg.uses[use] === "off") {+ throw new CliError(+ `decision-model eval run: use '${use}' is off in decision_model_uses, so grading it ` ++ `would send nothing and measure nothing; enable it first (for example ` ++ `'${use}:shadow') and re-run`,+ );+ }+ // Every throw from the runner is a named refusal - no spec for the+ // use, a spec that names another use, a broken preregistration - and+ // is operator-actionable, so it exits 2 like the other refusals.+ let result: Awaited<ReturnType<typeof runDecisionModelEval>>;+ try {+ result = await runDecisionModelEval(use, {+ config: cfg,+ markSource: processDirsEnv(),+ });+ } catch (err) {+ throw new CliError((err as Error).message);+ }+ if (flags["json"] === true) {+ process.stdout.write(JSON.stringify(result, null, 2) + "\n");+ } else {+ process.stdout.write(renderEvalRun(result) + "\n");+ }+ return 0;+}++function renderEvalRun(result: Awaited<ReturnType<typeof runDecisionModelEval>>): string {+ const num = (v: number | null): string => (v === null ? "-" : v.toFixed(3));+ const lines = [+ `decision-model eval ${result.use}: ${result.verdict}`,+ ` profile: ${result.profile ?? "(none)"}, spec ${result.spec_hash.slice(0, 12)}…, seed ${result.seed}`,+ ` counted: n=${result.counted.n}, error ${num(result.counted.error)} (ceiling ${result.ceiling}); ` ++ `baseline error ${num(result.baseline_error)}`,+ ` dev: n=${result.dev.n}, error ${num(result.dev.error)}; degraded requests: ${result.degraded_n}`,+ ];+ if (result.grade_record_id !== null) {+ lines.push(` grade record: ${result.grade_record_id}`);+ }+ lines.push(+ result.mark_written+ ? ` tuning mark: written for (${result.profile ?? "?"}, ${result.use}) under the state root`+ : ` tuning mark: not written (${result.mark_note ?? "unknown reason"})`,+ );+ return lines.join("\n");+}++function evalListVerb(argv: ReadonlyArray<string>): number {+ const { flags, positional } = parseFlags(argv, {+ vault: { type: "string" },+ config: { type: "string" },+ since: { type: "string" },+ use: { type: "string" },+ });+ if (positional.length > 0) {+ throw new CliError(+ `decision-model eval list takes no positional arguments: ${positional.join(" ")}`,+ );+ }+ const { vault } = resolveTargets(flags);+ if (vault === null) {+ throw new CliError("no vault configured. Pass --vault <path>.");+ }+ const { grades, skipped } = gradeLines(vault, sinceFlag(flags), useFlag(flags));+ if (flags["json"] === true) {+ process.stdout.write(JSON.stringify({ grades, skipped }, null, 2) + "\n");+ } else {+ const lines =+ grades.length === 0 && skipped.length === 0+ ? ["eval grades: none cached"]+ : [+ `eval grades: ${grades.length} record(s)` ++ (skipped.length > 0 ? `, ${skipped.length} skipped` : ""),+ ...grades.map((g) => ` ${renderEvalGradeLine(g)}`),+ ...skipped.map((note) => ` skipped: ${note}`),+ ];+ process.stdout.write(lines.join("\n") + "\n");+ }+ return 0;+}++function evalVerb(argv: ReadonlyArray<string>): number | Promise<number> {+ switch (argv[0]) {+ case "run":+ return evalRunVerb(argv.slice(1));+ case "list":+ return evalListVerb(argv.slice(1));+ default:+ process.stderr.write(USAGE);+ return 2;+ }+}+export async function handleDecisionModelSubcommand(argv: ReadonlyArray<string>): Promise<number> {const verb = argv[0];const rest = argv.slice(1);@@ -114,6 +304,8 @@ export async function handleDecisionModelSubcommand(argv: ReadonlyArray<string>)return await checkVerb(rest);case "report":return reportVerb(rest);+ case "eval":+ return await evalVerb(rest);default:process.stderr.write(USAGE);return 2;diff --git a/src/cli/search.ts b/src/cli/search.tsindex 1e058646..b7c8ae21 100644--- a/src/cli/search.ts+++ b/src/cli/search.ts@@ -26,6 +26,7 @@ import { cmdSearchQuery } from "./search/verbs/query.ts";import { cmdSearchRerankFit } from "./search/verbs/rerank-fit.ts";import { cmdSearchRerankEval } from "./search/verbs/rerank-eval.ts";import { cmdSearchRestamp } from "./search/verbs/restamp.ts";+import { cmdSearchSchema } from "./search/verbs/schema-export.ts";import { cmdSearchStatus } from "./search/verbs/status.ts";import { cmdSearchVectorBackfill } from "./search/verbs/vector-backfill.ts";import { cmdSearchWatch } from "./search/verbs/watch.ts";@@ -46,6 +47,7 @@ const KNOWN_VERBS = new Set(["rerank-eval","plan","restamp",+ "schema","watch","vector-backfill","event-anchor-backfill",@@ -95,6 +97,8 @@ export async function handleSearchSubcommand(argv: ReadonlyArray<string>): Promireturn await cmdSearchPlan(rest);case "restamp":return await cmdSearchRestamp(rest);+ case "schema":+ return await cmdSearchSchema(rest);case "vector-backfill":return await cmdSearchVectorBackfill(rest);case "event-anchor-backfill":diff --git a/src/cli/search/verbs/query.ts b/src/cli/search/verbs/query.tsindex 6e9e94f8..f2334fc0 100644--- a/src/cli/search/verbs/query.ts+++ b/src/cli/search/verbs/query.ts@@ -14,6 +14,7 @@ import {} from "../../../core/search/index.ts";import { searchAcrossVaults } from "../../../core/search/cross-vault.ts";import type { SearchLaneTiming } from "../../../core/search/index.ts";+import { SEARCH_OPTION_ROWS } from "../../../core/search/search-options-descriptor.ts";import {parseDegreePredicate,type DegreePredicate,@@ -43,36 +44,54 @@ function propertyFormatError(entry: string): CliError {return new CliError(`--property must be KEY=VALUE, got: ${entry}`);}+/** The flags that belong to this verb's output and refresh behavior, not to the search language. */+const VERB_LOCAL_FLAGS: Readonly<Record<string, QueryFlagSpec>> = Object.freeze({+ "auto-refresh": { type: "boolean" },+ json: { type: "boolean" },+ verbose: { type: "boolean" },+});++/** The parser spec one flag carries - the verb's local spell of `FlagSpec`. */+interface QueryFlagSpec {+ readonly type: "string" | "boolean" | "string-array";+ readonly default?: string;+}++/**+ * The query verb's flag table, DERIVED from the search-options descriptor+ * (t_50c81d5c): one entry per cli-visible row, keyed by the row's declared+ * CLI spelling (`path_prefix` spells `--path`, `query_document` spells+ * `--query-doc`, `properties` the repeatable `--property`,+ * `record_access` its `cliNegates` inverse `--no-record-access`), with the+ * row's CLI parse kind. The served schema and this table are now two+ * projections of one table, so a flag cannot appear on one surface and+ * silently vanish from the other.+ *+ * Per-surface bounds stay where they are: the CLI limit keeps its+ * `SEARCH_LIMIT_MIN..SEARCH_LIMIT_MAX` bind at the read site (the MCP+ * schema's `MCP_LIMIT_MAX` is a different, deliberate edge), the query+ * stays uncapped here, and `semantic` stays the documented tri-state+ * asymmetry (the verb body passes `undefined` when no lane flag is given).+ * A row whose documented default is a bare integer carries it as the+ * parser default (`limit` -> "10"); prose defaults mean absent.+ */+export const SEARCH_QUERY_FLAGS: Readonly<Record<string, QueryFlagSpec>> = Object.freeze(+ (() => {+ const derived: Record<string, QueryFlagSpec> = {};+ for (const row of SEARCH_OPTION_ROWS) {+ if (!row.surfaces.includes("cli") || row.cliFlag === null) continue;+ // A pure-integer documented default is a parse default; prose ("absent:+ // ...", "false", "all") stays absent, exactly as the literal table did.+ derived[row.cliFlag] = /^\d+$/.test(row.default)+ ? { type: row.cliKind, default: row.default }+ : { type: row.cliKind };+ }+ return { ...VAULT_FLAGS, ...derived, ...VERB_LOCAL_FLAGS };+ })(),+);+export async function cmdSearchQuery(argv: ReadonlyArray<string>): Promise<number> {- const { flags, positional } = parseFlags(argv, {- ...VAULT_FLAGS,- limit: { type: "string", default: "10" },- semantic: { type: "boolean" },- "keyword-only": { type: "boolean" },- "match-mode": { type: "string" },- kind: { type: "string" },- path: { type: "string" },- "keyword-weight": { type: "string" },- "semantic-weight": { type: "string" },- "auto-refresh": { type: "boolean" },- property: { type: "string-array" },- degree: { type: "string-array" },- visibility: { type: "string-array" },- "agent-scope": { type: "string" },- "query-doc": { type: "string" },- expand: { type: "boolean" },- disclosure: { type: "string" },- profile: { type: "string" },- "evidence-pack": { type: "boolean" },- "include-superseded": { type: "boolean" },- since: { type: "string" },- until: { type: "string" },- global: { type: "boolean" },- "no-record-access": { type: "boolean" },- json: { type: "boolean" },- verbose: { type: "boolean" },- explain: { type: "boolean" },- });+ const { flags, positional } = parseFlags(argv, SEARCH_QUERY_FLAGS);const rawQueryDocument = flagString(flags, "query-doc");const structuredQuery =diff --git a/src/cli/search/verbs/schema-export.ts b/src/cli/search/verbs/schema-export.tsnew file mode 100644index 00000000..9a39088f--- /dev/null+++ b/src/cli/search/verbs/schema-export.ts@@ -0,0 +1,226 @@+/**+ * `o2b search schema export|check` — the committed, versioned JSON Schema+ * artifact for the search query language (t_50c81d5c, Task E4).+ *+ * The artifact is DERIVED, never hand-edited: {@link+ * buildSearchQueryArtifact} projects the search-options descriptor (the+ * same table that derives the served `SEARCH_INPUT_SCHEMA` and the CLI+ * flag table) into `schemas/brain/search-query.schema.json`, and adds the+ * `brain.search_query_document.v1` sibling grammar for the line-oriented+ * query_document program as a `$defs` entry. Regeneration is a human+ * action (`o2b search schema export`); `check` re-derives and diffs, so a+ * descriptor change that outgrew the committed file is named in CI and by+ * any operator who runs it.+ *+ * Deliberately NOT `o2b brain schema ...`: that verb group is the VAULT+ * schema pack (`_brain.yaml`), a wholly unrelated "schema". This artifact+ * describes the search language, so it lives under the search verb group.+ *+ * The artifact documents the per-surface asymmetries the descriptor+ * records (the MCP-side `limit` maximum of MCP_LIMIT_MAX, the+ * `maxLength` on `query` that only the MCP surface enforces) instead of+ * silently flattening them; the CLI keeps its own bounds at its read+ * site.+ */++import { dirname, resolve } from "node:path";+import { fileURLToPath } from "node:url";++import { readFileSync, writeFileSync } from "node:fs";+import { deriveSearchInputSchema } from "../../../core/search/search-options-descriptor.ts";+import type { QueryIntent } from "../../../core/search/types.ts";+import { info } from "../../output.ts";+import { CliError, parseFlags } from "../helpers.ts";++/** The committed artifact path, from the repo root this module ships in. */+export const SEARCH_QUERY_SCHEMA_PATH = resolve(+ dirname(fileURLToPath(import.meta.url)),+ "..",+ "..",+ "..",+ "..",+ "schemas",+ "brain",+ "search-query.schema.json",+);++const DRAFT_2020_12 = "https://json-schema.org/draft/2020-12/schema";++/**+ * The intent vocabulary, kept complete against the `QueryIntent` union:+ * a new intent is a tsc error here until the grammar names it - the same+ * probe pattern the descriptor's runtime anchor uses for `SearchOptions`.+ */+const QUERY_INTENT_COVERAGE: Record<QueryIntent, true> = {+ neutral: true,+ exact: true,+ entity: true,+ broad: true,+};+const QUERY_INTENT_NAMES: ReadonlyArray<QueryIntent> = Object.keys(+ QUERY_INTENT_COVERAGE,+) as ReadonlyArray<QueryIntent>;++/**+ * The line-oriented query_document grammar, as the artifact describes it.+ * The parser is hand-rolled (`parseStructuredRecallQueryDocument`); this+ * block is a faithful DESCRIPTION of it, held to the documented example+ * by the doc-example tests - not an enforcement engine.+ */+function queryDocumentGrammar() {+ return {+ $id: "brain.search_query_document.v1",+ title: "Brain Search Query Document v1",+ description:+ "Line-oriented query program steering each retrieval layer separately. One '<lane>: <value>' line per lane; blank lines and #-comments are ignored. At least one lane is required; the intent lane may appear at most once.",+ type: "object",+ required: [],+ additionalProperties: false,+ properties: {+ intent: {+ type: "string",+ enum: [...QUERY_INTENT_NAMES],+ description:+ "Retrieval posture: neutral (default ranking), exact (verbatim phrase preference), entity (tightly scoped subject), broad (recall-favouring). At most one intent line.",+ },+ lex: {+ type: "string",+ description:+ "Keyword-lane tokens, space separated; quote a multi-word token. A leading '-' excludes the token. Repeatable: later lex lines add tokens.",+ },+ vec: {+ type: "string",+ description: "Embedding-lane query text. Repeatable: later vec lines add queries.",+ },+ hyde: {+ type: "string",+ description:+ "Hypothetical passage the answer would look like. Repeatable: later hyde lines add passages.",+ },+ },+ };+}++/** The artifact's full shape: the served input schema plus the grammar block. */+export type SearchQueryArtifact = {+ readonly $schema: string;+ readonly $id: string;+ readonly title: string;+ readonly description: string;+ readonly type: "object";+ readonly required: string[];+ readonly additionalProperties: false;+ readonly properties: Record<string, unknown>;+ readonly $defs: Record<string, unknown>;+};++/**+ * The committed artifact, derived from the descriptor. The property set+ * IS `deriveSearchInputSchema()`'s - the served brain_search language -+ * re-anchored under a versioned `$id`, with the query-document grammar+ * beside it. Any descriptor row change flows here and is caught by the+ * generator check until `export` re-commits it.+ */+export function buildSearchQueryArtifact(): SearchQueryArtifact {+ const served = deriveSearchInputSchema();+ return {+ $schema: DRAFT_2020_12,+ $id: "brain.search_query.v1",+ title: "Brain Search Query v1",+ description:+ "The brain_search query language: every argument the MCP tool accepts, published as a versioned JSON Schema (draft 2020-12). The same table derives the served tools/list inputSchema and the o2b search CLI flags; see $defs.search_query_document for the line-oriented query_document grammar.",+ type: "object",+ required: [...served.required],+ additionalProperties: false,+ properties: JSON.parse(JSON.stringify(served.properties)),+ $defs: { search_query_document: queryDocumentGrammar() },+ };+}++/** The artifact serialized exactly the way `export` writes it. */+export function renderSearchQueryArtifact(): string {+ return `${JSON.stringify(buildSearchQueryArtifact(), null, 2)}\n`;+}++function usageError(message: string): CliError {+ return new CliError(+ `search schema: ${message} (usage: o2b search schema export [--stdout] | check)`,+ );+}++/** The property-name list of a schema object, for a one-line drift reason. */+function propertySetOf(schema: unknown): string {+ const properties =+ typeof schema === "object" && schema !== null && "properties" in schema+ ? (schema as { properties: Record<string, unknown> }).properties+ : {};+ return Object.keys(properties).toSorted().join(",");+}++/**+ * `o2b search schema export [--stdout]` - write the derived artifact to+ * the committed path (default) or, with `--stdout`, print exactly the+ * rendered bytes and touch nothing (the dry-run/CI preview the usage+ * string and cli-reference promise). `o2b search schema check` -+ * re-derive and compare with the committed file: exit 0 clean, exit 2 on+ * drift, so CI and operators share one named verdict. The comparison is+ * JSON equality, not byte equality: the committed file carries the repo+ * formatter's layout, so `export` writing raw builder bytes must never+ * read as drift - only content can drift. `--json` is `check`'s output+ * mode and is refused on export by name - `parseFlags` injects it into+ * every schema, and a flag the verb parses and ignores is the defect+ * `--stdout` once was.+ */+export async function cmdSearchSchema(argv: ReadonlyArray<string>): Promise<number> {+ const sub = argv[0];+ if (sub === "export") {+ const { flags } = parseFlags(argv.slice(1), {+ stdout: { type: "boolean" },+ json: { type: "boolean" },+ });+ if (flags["json"] === true) {+ throw usageError("--json is check's output mode; export takes only --stdout");+ }+ if (flags["stdout"] === true) {+ process.stdout.write(renderSearchQueryArtifact());+ return 0;+ }+ writeFileSync(SEARCH_QUERY_SCHEMA_PATH, renderSearchQueryArtifact(), "utf8");+ info(`search schema: wrote ${SEARCH_QUERY_SCHEMA_PATH}`);+ return 0;+ }+ if (sub === "check") {+ const { flags } = parseFlags(argv.slice(1), { json: { type: "boolean" } });+ const asJson = flags["json"] === true;+ let committed: unknown;+ try {+ committed = JSON.parse(readFileSync(SEARCH_QUERY_SCHEMA_PATH, "utf8"));+ } catch (cause) {+ const reason = cause instanceof Error ? cause.message : String(cause);+ process.stderr.write(+ `error: search schema: ${SEARCH_QUERY_SCHEMA_PATH} is missing or unreadable (${reason}) - run 'o2b search schema export'\n`,+ );+ return 2;+ }+ const derived: unknown = JSON.parse(JSON.stringify(buildSearchQueryArtifact()));+ if (JSON.stringify(committed) === JSON.stringify(derived)) {+ if (asJson) {+ process.stdout.write(`${JSON.stringify({ ok: true, $id: "brain.search_query.v1" })}\n`);+ } else {+ info(`search schema: ${SEARCH_QUERY_SCHEMA_PATH} matches the descriptor`);+ }+ return 0;+ }+ const fileSet = propertySetOf(committed);+ const derivedSet = propertySetOf(derived);+ const detail =+ fileSet !== derivedSet+ ? `property set drifted (file: ${fileSet}; descriptor: ${derivedSet})`+ : "content drifted from the descriptor derivation";+ process.stderr.write(+ `error: search schema: ${SEARCH_QUERY_SCHEMA_PATH} ${detail} - run 'o2b search schema export' and commit the result\n`,+ );+ return 2;+ }+ throw usageError(`unknown subcommand '${sub ?? ""}'`);+}diff --git a/src/cli/search/verbs/status.ts b/src/cli/search/verbs/status.tsindex 59e7a529..1a5f77a0 100644--- a/src/cli/search/verbs/status.ts+++ b/src/cli/search/verbs/status.ts@@ -12,6 +12,7 @@ import {} from "../../../core/search/freshen.ts";import {eventTimeStatus,+ indexBehindCount,indexStatus,renderEventTimeStatus,serializeEventTimeStatus,@@ -37,7 +38,13 @@ export async function cmdSearchStatus(argv: ReadonlyArray<string>): Promise<numbconst status = await indexStatus(cfg);// The event-time summary reads the index, so it exists only with one.const eventTime = status.exists ? await eventTimeStatus(cfg) : null;- const freshen = status.exists ? freshenStatus(cfg, status.lastIndexedAt) : null;+ // The live behind walk (t_e4438152): only with an index to diff+ // against, best-effort null on failure - the freshen block then reads+ // "(not measured)", never a fabricated zero.+ const behind = status.exists ? await indexBehindCount(cfg) : null;+ const freshen = status.exists+ ? freshenStatus(cfg, status.lastIndexedAt, undefined, behind?.behind ?? null)+ : null;if (flagBoolean(flags, "json")) {process.stdout.write(JSON.stringify({diff --git a/src/core/bench/guards.ts b/src/core/bench/guards.tsnew file mode 100644index 00000000..4f80fc69--- /dev/null+++ b/src/core/bench/guards.ts@@ -0,0 +1,596 @@+/**+ * Bench-run integrity guards (t_d7ce8baf): the named refusal vocabulary,+ * the pre-run preflight, and the pre-report trace validation.+ *+ * Two gaps motivated this module, both about a degraded run creating+ * state or publishing scores:+ *+ * - Ordering/atomicity: search-config resolution and the capability+ * gate used to run AFTER run creation (orphan run dirs on refusal),+ * a fresh run silently reset an existing same-identity run dir, and+ * a resume target with damaged or tampered artifacts failed late+ * with generic errors. {@link preflightBenchRun} catches all of+ * that BEFORE `createBenchRun`/`loadBenchRun` runs.+ * - Trace trust: the evaluate phase re-reads the persisted per-question+ * results and used to default absent fields into ordinary FAILs,+ * silently ignore truncated or foreign records, and publish faulted+ * decisions as if they were memory behavior. {@link+ * validateBenchTrace} refuses those BEFORE the report writes.+ *+ * What is deliberately NOT a refusal: score content. An+ * all-questions-failed run is the harness's purpose - a real+ * catastrophic regression is exactly what it must publish. Empty-but-+ * present trace fields are legitimate misses. The judge staying+ * `error` is advisory by contract (`judge.ts`).+ *+ * Guards abort; scorers score. `failure-modes.ts` is unchanged and the+ * guards add no knob, no measured behavior and zero stdout on success:+ * existing run ids, checkpoints and reports stay byte-identical+ * (`fixtureHash` remains content-only).+ */++import { accessSync, existsSync, mkdirSync, readFileSync, readdirSync } from "node:fs";+import { join } from "node:path";+import { constants as fsConstants } from "node:fs";++import { benchResultsDir, benchVaultDir, guardedRunDir, parseCheckpoint } from "./run-store.ts";+import { fixtureHash } from "./fixture.ts";+import {+ BENCH_PHASES,+ type BenchCheckpoint,+ type BenchFixture,+ type BenchPhase,+ type BenchQuestionResult,+ type BenchReport,+} from "./types.ts";++/**+ * The closed refusal vocabulary: one member per catchable pre-run (P1-P7)+ * or pre-report (T1-T7) state. Frozen, like `RECALL_FAILURE` - a kind+ * that renders to an operator must not be renamable silently.+ */+export const BENCH_REFUSAL = Object.freeze({+ /** P1: the runs directory cannot be created or written. */+ runsDirUnusable: "runs_dir_unusable",+ /** P2: a fresh run's identity collides with an existing run dir. */+ runDirExists: "run_dir_exists",+ /** P3: a resume target's checkpoint.json is missing required shape. */+ checkpointUnparseable: "checkpoint_unparseable",+ /** P4a: the checkpoint names a phase this build does not know. */+ checkpointPhaseUnknown: "checkpoint_phase_unknown",+ /** P4b: the checkpoint's phases are out of order or duplicated. */+ checkpointPhaseOrder: "checkpoint_phase_order",+ /**+ * P4c: the resume was handed a fixture the run did not start with -+ * another `--fixture`, an edited copy, or (on a sampled suite) a+ * different `--sample-seed`/`--sample-cap`, which samples a different+ * fixture. Refused BEFORE the artifact check, which would read the new+ * fixture's absent artifacts as a tampered run.+ */+ checkpointFixtureMismatch: "checkpoint_fixture_mismatch",+ /** P5: a phase is marked done whose artifacts are gone or truncated. */+ runArtifactMissing: "run_artifact_missing",+ /** P7: the fixture cross-references notes or sessions it never defines. */+ fixtureCrossReference: "fixture_cross_reference",+ /** T1: a fixture question has no persisted result file. */+ traceResultMissing: "trace_result_missing",+ /** T2: a result file is not parseable JSON. */+ traceResultUnparseable: "trace_result_unparseable",+ /** T3: a result file's `id` differs from the question it is stored under. */+ traceIdMismatch: "trace_id_mismatch",+ /** T4: a category-required field is ABSENT from a persisted record. */+ traceFieldAbsent: "trace_field_absent",+ /** T5: a persisted proactive decision faulted. */+ traceFaultedDecisions: "trace_faulted_decisions",+ /** T6: `results/` holds files beyond the fixture's question ids. */+ traceExtraResults: "trace_extra_results",+ /** T7: the assembled report's counts disagree with its own trace. */+ reportCountsMismatch: "report_counts_mismatch",+} as const);++/** Closed union over {@link BENCH_REFUSAL}. */+export type BenchRefusalKind = (typeof BENCH_REFUSAL)[keyof typeof BENCH_REFUSAL];++/** Membership list, for listings and narrowings. */+export const BENCH_REFUSAL_KINDS: ReadonlyArray<BenchRefusalKind> = Object.freeze(+ Object.values(BENCH_REFUSAL),+);++/** Narrow a value read back across a boundary. */+export function isBenchRefusalKind(value: unknown): value is BenchRefusalKind {+ return (+ typeof value === "string" && (BENCH_REFUSAL_KINDS as ReadonlyArray<string>).includes(value)+ );+}++/**+ * The one error the bench guards raise. The message is the full CLI+ * render - `refused (<kind>): <detail>` - so a handler that prints the+ * message prints the contract; `kind` and `detail` stay structured for+ * callers that want to branch on the kind.+ */+export class BenchRefusalError extends Error {+ readonly kind: BenchRefusalKind;+ readonly detail: string;++ constructor(kind: BenchRefusalKind, detail: string) {+ super(`refused (${kind}): ${detail}`);+ this.name = "BenchRefusalError";+ this.kind = kind;+ this.detail = detail;+ }+}++function refuse(kind: BenchRefusalKind, detail: string): never {+ throw new BenchRefusalError(kind, detail);+}++/** The report file a completed report phase promises. Kept beside the pipeline's own writer. */+const REPORT_FILENAME = "report.json";++/** What the preflight needs to decide a run may start. */+export interface BenchPreflightOptions {+ /** The runs directory the run will live under (created if missing). */+ readonly runsDir: string;+ readonly fixture: BenchFixture;+ /** Resume target run id; preflight validates its checkpoint and artifacts. */+ readonly resume?: string;+ /**+ * The run id a FRESH run is about to create (the caller resolves it so+ * the collision check reads the same identity the store will write).+ * Absent on resume-only preflights.+ */+ readonly freshRunId?: string;+}++/**+ * Refuse every damaged state catchable BEFORE a run exists (P1-P7), so a+ * refusal can never leave a run directory behind. Adds zero stdout and,+ * on success, only the runs directory itself - which the store would+ * create anyway.+ */+export function preflightBenchRun(opts: BenchPreflightOptions): void {+ // P1: the runs dir must be creatable and writable. Probing here buys a+ // named refusal where a raw ENOENT/EACCES used to surface mid-store.+ try {+ mkdirSync(opts.runsDir, { recursive: true });+ accessSync(opts.runsDir, fsConstants.W_OK);+ } catch (cause) {+ refuse(+ BENCH_REFUSAL.runsDirUnusable,+ `runs directory ${opts.runsDir} is not usable: ${describeCause(cause)} - ` ++ "create it or pass a writable --runs-dir",+ );+ }+ if (opts.resume !== undefined) {+ preflightResume(opts.runsDir, opts.resume, opts.fixture);+ } else if (opts.freshRunId !== undefined) {+ // P2: run ids are second-precision timestamp + identity hex, so a+ // same-second rerun of the same fixture collides. The store would+ // silently RESET the prior run's checkpoint; the preflight refuses+ // instead and points at --resume.+ const existing = join(opts.runsDir, opts.freshRunId, "checkpoint.json");+ if (existsSync(existing)) {+ refuse(+ BENCH_REFUSAL.runDirExists,+ `a run with this identity already exists at ${join(opts.runsDir, opts.freshRunId)} - ` ++ `pass --resume ${opts.freshRunId} to continue it, or choose another --runs-dir`,+ );+ }+ }+ // P7: fixture cross-references, on every run. A dangling reference+ // scores as an ordinary missing-expected FAIL - an authoring error+ // indistinguishable from a real regression - so it is refused by name+ // instead.+ preflightFixtureCrossReferences(opts.fixture);+}++function describeCause(cause: unknown): string {+ return cause instanceof Error ? cause.message : String(cause);+}++/** P3, P4, the fixture-hash match, P5: the resume target's checkpoint and its promised artifacts. */+function preflightResume(runsDir: string, runId: string, fixture: BenchFixture): void {+ // The run-id guard runs BEFORE any read (finding 30): a raw `--resume`+ // value the guard would refuse is refused here, by name - never+ // answered by whatever exists at the path it resolves to (`--resume ..`+ // used to read the parent directory's checkpoint.json and surface that+ // file's parse error as the refusal).+ const runDir = guardedRunDir(runsDir, runId);+ const path = join(runDir, "checkpoint.json");+ // A missing checkpoint keeps the store's own "bench run not found"+ // message: nothing here to add.+ if (!existsSync(path)) return;+ let raw: unknown;+ try {+ raw = JSON.parse(readFileSync(path, "utf8"));+ } catch (cause) {+ refuse(+ BENCH_REFUSAL.checkpointUnparseable,+ `${path} is not valid JSON: ${describeCause(cause)} - ` ++ "the run directory is damaged; start a fresh run",+ );+ }+ if (raw === null || typeof raw !== "object" || Array.isArray(raw)) {+ refuse(+ BENCH_REFUSAL.checkpointUnparseable,+ `${path} is not a checkpoint object - start a fresh run`,+ );+ }+ const record = raw as Record<string, unknown>;+ const phases = record["completed_phases"];+ if (+ !Array.isArray(phases) ||+ phases.some((phase) => typeof phase !== "string" || phase.length === 0)+ ) {+ refuse(+ BENCH_REFUSAL.checkpointUnparseable,+ `${path} has no usable completed_phases array - start a fresh run`,+ );+ }+ // P4a: unknown phase names mean a checkpoint from a different build;+ // the store's parser refuses these too, but naming the value here+ // renders the repair before any load work happens.+ const unknown = phases.filter(+ (phase) => !(BENCH_PHASES as ReadonlyArray<string>).includes(phase),+ );+ if (unknown.length > 0) {+ refuse(+ BENCH_REFUSAL.checkpointPhaseUnknown,+ `${path} lists unknown phase(s) ${unknown.map((phase) => `'${phase}'`).join(", ")} - ` ++ "the checkpoint was written by a different build; start a fresh run",+ );+ }+ // P4b: completed phases are appended in pipeline order and once each.+ let lastIndex = -1;+ for (const phase of phases as ReadonlyArray<BenchPhase>) {+ const index = BENCH_PHASES.indexOf(phase);+ if (index <= lastIndex) {+ refuse(+ BENCH_REFUSAL.checkpointPhaseOrder,+ `${path} lists '${phase}' out of order or duplicated (completed_phases: ${phases.join(", ")}) - ` ++ "the checkpoint is damaged or from a different build; start a fresh run",+ );+ }+ lastIndex = index;+ }+ // The store's parser is the ONE definition of a usable checkpoint, and+ // it runs HERE: a document that parses as JSON but lacks the required+ // fields passed the shape checks above (and P5, whenever the artifacts+ // on disk happened to exist) and then exploded in loadBenchRun as a+ // plain Error the verb does not catch - a source frame where the+ // contract promises `refused (checkpoint_unparseable)`. Mapped to that+ // refusal with the file and the missing fields named. P4a/P4b above+ // already refused the phase states under their own names, so any+ // failure left for the parser is a shape failure.+ let checkpoint: BenchCheckpoint;+ try {+ checkpoint = parseCheckpoint(raw);+ } catch (cause) {+ refuse(+ BENCH_REFUSAL.checkpointUnparseable,+ `${path} is not a usable checkpoint: ${describeCause(cause)} - start a fresh run`,+ );+ }+ // P4c: the fixture the resume was given is hashed the way loadBenchRun+ // hashes it and compared BEFORE P5. A different `--fixture`, an edited+ // fixture copy, or a different --sample-seed/--sample-cap (which sample+ // a different fixture) changes this hash - and P5, comparing the run+ // directory against the NEW fixture, would read its absent artifacts as+ // `run_artifact_missing` and advise discarding a run that is healthy+ // under its own fixture.+ const expectedHash = fixtureHash(fixture);+ if (checkpoint.fixture_hash !== expectedHash) {+ refuse(+ BENCH_REFUSAL.checkpointFixtureMismatch,+ `${path} records fixture hash '${checkpoint.fixture_hash}' but this resume was given ` ++ `a fixture hashing to '${expectedHash}' - ` ++ "resume with the same fixture, seed and cap, or start a fresh run",+ );+ }+ const completed = new Set<string>(phases as ReadonlyArray<string>);+ const done = (phase: BenchPhase): boolean => completed.has(phase);+ // P5: a phase marked done promises artifacts. Only phases the coming+ // invocation still READS are required: evaluate/report rerun from the+ // persisted results on every resume, but the disposable vault is+ // legitimately deletable once retrieval is done (it is never read+ // again), so the vault is required exactly when retrieval still has to+ // run against it.+ if (done("ingest") && !done("retrieve")) {+ const vault = benchVaultDir(runDir);+ if (!existsSync(vault)) {+ refuse(+ BENCH_REFUSAL.runArtifactMissing,+ `the run claims ingest done but the materialized vault is missing at ${vault} - ` ++ "the run directory was tampered with or truncated; start a fresh run",+ );+ }+ const missingNote = fixture.notes.find((note) => !existsSync(join(vault, note.path)));+ if (missingNote !== undefined) {+ refuse(+ BENCH_REFUSAL.runArtifactMissing,+ `the materialized vault is missing the fixture note ${missingNote.path} - ` ++ "the run directory was tampered with or truncated; start a fresh run",+ );+ }+ }+ if (done("retrieve")) {+ const results = benchResultsDir(runDir);+ if (!existsSync(results)) {+ refuse(+ BENCH_REFUSAL.runArtifactMissing,+ `the run claims retrieve done but the results directory is missing at ${results} - ` ++ "the run directory was tampered with or truncated; start a fresh run",+ );+ }+ const missingQuestion = fixture.questions.find(+ (question) => !existsSync(join(results, `${question.id}.json`)),+ );+ if (missingQuestion !== undefined) {+ refuse(+ BENCH_REFUSAL.runArtifactMissing,+ `the run claims retrieve done but ${join(results, `${missingQuestion.id}.json`)} is missing - ` ++ "the run directory was tampered with or truncated; start a fresh run",+ );+ }+ }+ if (done("report")) {+ const report = join(runDir, REPORT_FILENAME);+ if (!existsSync(report)) {+ refuse(+ BENCH_REFUSAL.runArtifactMissing,+ `the run claims report done but ${report} is missing - ` ++ "the run directory was tampered with or truncated; start a fresh run",+ );+ }+ }+}++/** P7: every referenced note path and session id must exist in the fixture. */+function preflightFixtureCrossReferences(fixture: BenchFixture): void {+ const notePaths = new Set(fixture.notes.map((note) => note.path));+ const sessionIds = new Set(+ fixture.continuity.flatMap((record) => {+ const sessionId = record.payload["session_id"];+ return typeof sessionId === "string" ? [sessionId] : [];+ }),+ );+ for (const question of fixture.questions) {+ for (const referenced of question.expected_paths ?? []) {+ if (!notePaths.has(referenced)) {+ refuse(+ BENCH_REFUSAL.fixtureCrossReference,+ `question ${question.id} expects note ${referenced}, which the fixture never defines - ` ++ "fix the fixture (the question cannot be scored as authored)",+ );+ }+ }+ for (const referenced of question.not_expected_above ?? []) {+ if (!notePaths.has(referenced)) {+ refuse(+ BENCH_REFUSAL.fixtureCrossReference,+ `question ${question.id} names ${referenced} in not_expected_above, ` ++ "which the fixture never defines - fix the fixture (the question cannot be scored as authored)",+ );+ }+ }+ if (question.session_id !== undefined && !sessionIds.has(question.session_id)) {+ refuse(+ BENCH_REFUSAL.fixtureCrossReference,+ `question ${question.id} (session_handoff) names session '${question.session_id}', ` ++ "which the fixture's continuity never records - fix the fixture (the question cannot be scored as authored)",+ );+ }+ }+}++/** The category-field contract the trace validators enforce (T4). */+const CATEGORY_REQUIRED_FIELDS: Readonly<Record<string, string>> = Object.freeze({+ retrieval: "paths",+ session_handoff: "turn_texts",+ budget: "item_ids",+ source_isolation: "item_ids",+ proactive_recall: "recall_decision",+ write_fidelity: "labels",+ standing_instruction: "standing_items",+});++/** The trace field a question's category requires, absent never allowed. */+export function requiredTraceField(category: string): string {+ // The six non-retrieval categories name their field explicitly; every+ // other category is a retrieval family (single_hop, temporal, ...),+ // whose required field is `paths`.+ return CATEGORY_REQUIRED_FIELDS[category] ?? "paths";+}++/** What the trace validator needs; `results`/`report` arm the counts check. */+export interface BenchTraceValidationOptions {+ readonly runDir: string;+ readonly fixture: BenchFixture;+ /** The evaluated results; required together with `report`. */+ readonly results?: ReadonlyArray<BenchQuestionResult>;+ /**+ * The assembled report. Provided on the pre-write validation call, it+ * arms T7: the report's published counts must equal the counts+ * recomputed from the results by the same aggregation buildReport used.+ */+ readonly report?: BenchReport;+}++/**+ * The shared atomic writer's own leftover shape (`<target>.<pid>.tmp`):+ * a process killed between the write and the rename leaves it beside its+ * target - the `rmSync` cleanup only runs on a thrown error - and T6+ * must not turn that crash artifact into an unresumable run (finding 29):+ * the resume exists precisely to recover a crashed one. Only this exact+ * shape is exempt; every other leftover still refuses.+ */+function isAtomicWriteTemp(entry: string): boolean {+ return /\.json\.\d+\.tmp$/.test(entry);+}++/**+ * Refuse every damaged trace state catchable BEFORE the report writes+ * (T1-T7). Called by the pipeline once before scoring (no report yet -+ * T1-T6) and once before the write (with the report - the full set), so+ * both fresh and resumed runs are covered.+ */+export function validateBenchTrace(opts: BenchTraceValidationOptions): void {+ const resultsDir = benchResultsDir(opts.runDir);+ const expectedIds = opts.fixture.questions.map((question) => question.id);+ const expectedFiles = new Set(expectedIds.map((id) => `${id}.json`));+ // T6: leftovers in a reused or tampered run dir silently skew nothing+ // today only because they are ignored - which is exactly the problem:+ // they would hide a stale trace from every check below. The atomic+ // writer's own crash-orphaned temp ({@link isAtomicWriteTemp}) is the+ // one exempt shape.+ if (existsSync(resultsDir)) {+ const extras = readdirSync(resultsDir).filter(+ (entry) => !expectedFiles.has(entry) && !isAtomicWriteTemp(entry),+ );+ if (extras.length > 0) {+ refuse(+ BENCH_REFUSAL.traceExtraResults,+ `${resultsDir} holds file(s) beyond the fixture's questions: ${extras.join(", ")} - ` ++ "delete the stale result files or start a fresh run",+ );+ }+ }+ const faulted: string[] = [];+ for (let index = 0; index < opts.fixture.questions.length; index++) {+ const question = opts.fixture.questions[index]!;+ const path = join(resultsDir, `${question.id}.json`);+ // T1: the result file every fixture question was promised.+ if (!existsSync(path)) {+ refuse(+ BENCH_REFUSAL.traceResultMissing,+ `no persisted result for question ${question.id} at ${path} - ` ++ "the retrieve phase did not complete for this run; start a fresh run",+ );+ }+ let raw: unknown;+ try {+ raw = JSON.parse(readFileSync(path, "utf8"));+ } catch (cause) {+ // T2: a crash mid-write (writes are atomic now, but the state must+ // stay refused by name, never a raw SyntaxError).+ refuse(+ BENCH_REFUSAL.traceResultUnparseable,+ `${path} is not valid JSON: ${describeCause(cause)} - ` ++ "the result file was truncated by a crash; start a fresh run",+ );+ }+ if (raw === null || typeof raw !== "object" || Array.isArray(raw)) {+ refuse(+ BENCH_REFUSAL.traceResultUnparseable,+ `${path} is not a result object - start a fresh run`,+ );+ }+ const record = raw as Record<string, unknown>;+ // T3: the id INSIDE the file must be the question it was stored under.+ if (record["id"] !== question.id) {+ refuse(+ BENCH_REFUSAL.traceIdMismatch,+ `${path} records id '${String(record["id"])}' but is stored under question ${question.id} - ` ++ "start a fresh run",+ );+ }+ // T4: category-required field ABSENT. The builders always set these+ // fields, so absence is structural (a truncated or foreign trace);+ // present-but-empty is a legitimate retrieval miss and passes.+ const field = requiredTraceField(question.category);+ if (record[field] === undefined || record[field] === null) {+ refuse(+ BENCH_REFUSAL.traceFieldAbsent,+ `question ${question.id} (${question.category}) has no '${field}' in ${path} - ` ++ "a truncated or foreign trace (present-but-empty would be a legitimate miss); start a fresh run",+ );+ }+ // T5: a faulted decision is the harness failing, and the scorer only+ // counts it - the report must never dress harness breakage up as+ // memory behavior. Resume would re-evaluate the same persisted+ // decision, so the repair is a fresh run.+ const decision = record["recall_decision"] as { kind?: string; fault?: string } | undefined;+ if (decision !== undefined && decision !== null && decision.kind === "error") {+ faulted.push(`${question.id} (${String(decision.fault ?? "unknown fault")})`);+ }+ }+ if (faulted.length > 0) {+ refuse(+ BENCH_REFUSAL.traceFaultedDecisions,+ `the decision core faulted on ${faulted.join(", ")} - the report must not publish harness ` ++ "breakage as memory behavior; start a fresh run (a resumed run re-evaluates the same persisted decisions)",+ );+ }+ // T7: the report must agree with the trace it was built from, by the+ // SAME aggregation buildReport uses (standing_instruction excluded from+ // the headline, never from by_category).+ if (opts.report !== undefined) {+ const counts = countQuestionResults(opts.results ?? []);+ const quality = opts.report.quality;+ const drifted: string[] = [];+ if (quality.passed !== counts.passed)+ drifted.push(`passed ${quality.passed} != ${counts.passed}`);+ if (quality.total !== counts.total) drifted.push(`total ${quality.total} != ${counts.total}`);+ for (const [category, bucket] of Object.entries(counts.byCategory)) {+ const published = quality.by_category[category];+ if (+ published === undefined ||+ published.passed !== bucket.passed ||+ published.total !== bucket.total+ ) {+ drifted.push(`by_category.${category} != trace`);+ }+ }+ for (const category of Object.keys(quality.by_category)) {+ if (counts.byCategory[category] === undefined) {+ drifted.push(`by_category.${category} not in trace`);+ }+ }+ if (drifted.length > 0) {+ refuse(+ BENCH_REFUSAL.reportCountsMismatch,+ `the report disagrees with its own trace: ${drifted.join("; ")} - start a fresh run`,+ );+ }+ }+}++/** The aggregate behind `buildReport`'s quality family, shared with T7. */+export interface BenchResultCounts {+ /** Headline passed count, excluding the standing_instruction category. */+ readonly passed: number;+ /** Headline total, same exclusion. */+ readonly total: number;+ /** Per-category passed/total, every category including the excluded one. */+ readonly byCategory: Record<string, { passed: number; total: number }>;+}++/**+ * Aggregate question results the way `buildReport` does. ONE copy of the+ * counting rule - including the standing_instruction headline exclusion -+ * so the report and the T7 cross-check cannot drift apart.+ */+export function countQuestionResults(+ results: ReadonlyArray<BenchQuestionResult>,+): BenchResultCounts {+ const byCategory: Record<string, { passed: number; total: number }> = {};+ let passed = 0;+ let total = 0;+ for (const result of results) {+ const bucket = (byCategory[result.category] ??= { passed: 0, total: 0 });+ bucket.total += 1;+ if (result.pass) {+ bucket.passed += 1;+ }+ // The standing_instruction category never folds into the headline+ // (recall-lane-latency): its rate stays the named line of its own in+ // `by_category`, so adding facet questions to a fixture cannot shift+ // the headline pass rate a baseline compares.+ if (result.category !== "standing_instruction") {+ total += 1;+ if (result.pass) passed += 1;+ }+ }+ return { passed, total, byCategory };+}diff --git a/src/core/bench/phases.ts b/src/core/bench/phases.tsindex 3034e6ba..fb2f379f 100644--- a/src/core/bench/phases.ts+++ b/src/core/bench/phases.ts@@ -35,6 +35,19 @@ import {embedBenchVaultIndex,readBenchEmbeddingReceipt,} from "./embedding-cache.ts";+import { countQuestionResults, preflightBenchRun, validateBenchTrace } from "./guards.ts";+import {+ benchResultsDir,+ benchRunDirPath,+ benchVaultDir,+ atomicWriteFileSync,+ completeBenchPhase,+ createBenchRun,+ loadBenchRun,+ nextBenchRunId,+ phaseDone,+ type BenchRunHandle,+} from "./run-store.ts";import {benchRecallRetriever,classifyRecallDecision,@@ -46,15 +59,6 @@ import {import { fixtureHash, materializeBenchVault } from "./fixture.ts";import { runJudge } from "./judge.ts";import { LONGMEMEVAL_SUITE_NAME, scoreLongMemEvalRecall } from "./longmemeval.ts";-import {- benchResultsDir,- benchVaultDir,- completeBenchPhase,- createBenchRun,- loadBenchRun,- phaseDone,- type BenchRunHandle,-} from "./run-store.ts";import {BENCH_REPORT_SCHEMA,DEFAULT_BENCH_KNOB_PIN,@@ -268,6 +272,48 @@ export async function runMemoryBench(opts: BenchRunOptions): Promise<BenchReport}}const pinnedKnobs = opts.pinnedKnobs ?? DEFAULT_BENCH_KNOB_PIN;+ // The run's clock is resolved once so every consumer sees the same+ // second: the preflight's collision check must read the identity the+ // store is about to write.+ const now = opts.now ?? new Date();+ // The preflight catches every damaged state catchable BEFORE a run+ // exists (unusable runs dir, fresh-run collision, damaged or tampered+ // resume target, fixture cross-reference defects), so a refusal can+ // never leave a run directory behind. Guards add zero stdout and no+ // knobs: a healthy run is untouched.+ const freshRunId =+ opts.resume !== undefined+ ? undefined+ : nextBenchRunId(opts.fixture, {+ now,+ pinnedKnobs,+ ...(opts.recallFloor !== undefined ? { recallFloor: opts.recallFloor } : {}),+ ...(opts.sample !== undefined ? { sample: opts.sample } : {}),+ });+ preflightBenchRun({+ runsDir: opts.runsDir,+ fixture: opts.fixture,+ ...(opts.resume !== undefined ? { resume: opts.resume } : {}),+ ...(freshRunId !== undefined ? { freshRunId } : {}),+ });+ // Resolved BEFORE the run is created (t_d7ce8baf): `resolveSearchConfig`+ // parses the env BEFORE merging overrides, so an env var naming a+ // provider it does not recognise throws - and that refusal used to+ // leave an orphan run dir behind. The vault path is computed the way+ // the store resolves it, so the config here is the config the searches+ // will run under.+ const runDir = benchRunDirPath(opts.runsDir, opts.resume ?? freshRunId!);+ const vault = benchVaultDir(runDir);+ const config = benchSearchConfig(vault, pinnedKnobs);+ // The capability gate: the semantic lane is reachable only when the+ // run's suite declared the embeddings capability, so a pin can never+ // silently arm a lane the suite never asked for. Same ordering rule:+ // this refusal also used to orphan a run dir.+ if (config.semantic.enabled && opts.capabilities?.embeddings !== true) {+ throw new Error(+ "bench run pins the semantic lane on without the embeddings capability - declare { embeddings: true } for the suite or keep the semantic lane pinned off",+ );+ }const run: BenchRunHandle =opts.resume !== undefined? loadBenchRun(opts.runsDir, opts.resume, {@@ -277,24 +323,12 @@ export async function runMemoryBench(opts: BenchRunOptions): Promise<BenchReport...(opts.sample !== undefined ? { sample: opts.sample } : {}),}): createBenchRun(opts.runsDir, opts.fixture, {- ...(opts.now !== undefined ? { now: opts.now } : {}),+ now,pinnedKnobs,...(opts.recallFloor !== undefined ? { recallFloor: opts.recallFloor } : {}),...(opts.sample !== undefined ? { sample: opts.sample } : {}),});let checkpoint = run.checkpoint;- const vault = benchVaultDir(run.runDir);- // One resolved config for every phase: the pin cannot drift between- // the index warmup and the timed retrievals.- const config = benchSearchConfig(vault, pinnedKnobs);- // The capability gate: the semantic lane is reachable only when the- // run's suite declared the embeddings capability, so a pin can never- // silently arm a lane the suite never asked for.- if (config.semantic.enabled && opts.capabilities?.embeddings !== true) {- throw new Error(- "bench run pins the semantic lane on without the embeddings capability - declare { embeddings: true } for the suite or keep the semantic lane pinned off",- );- }// Present when this invocation ran the embedding index phase; read// back from the run artifact on a resumed run.let embeddings: BenchEmbeddingReceipt | undefined;@@ -342,15 +376,23 @@ export async function runMemoryBench(opts: BenchRunOptions): Promise<BenchReportpinnedKnobs,opts.recallFloor,);- writeFileSync(+ atomicWriteFileSync(join(benchResultsDir(run.runDir), `${question.id}.json`),`${JSON.stringify(retrieved, null, 2)}\n`,- "utf8",);}checkpoint = completeBenchPhase(run.runDir, checkpoint, "retrieve");}+ // The trace guard, FIRST pass: every fixture question must have a+ // parseable, correctly-keyed record carrying its category's required+ // fields, no faulted decisions and no leftover files - refused by name+ // BEFORE the evaluator scores anything, so a tampered or truncated+ // trace can never be dressed up as an ordinary failing run. (The+ // second pass runs pre-write with the assembled report, cross-checking+ // the published counts against the same trace.)+ validateBenchTrace({ runDir: run.runDir, fixture: opts.fixture });+// Phase: evaluate - pure over the persisted results; no vault access.// Each persisted record is read once and shared by the evaluator and// the suite metric families.@@ -420,7 +462,12 @@ export async function runMemoryBench(opts: BenchRunOptions): Promise<BenchReport);const judge = runJudge(opts.judgeCmd, results, judgeInputs);const report = buildReport(run, opts.fixture, results, judge, embeddings, longmemeval);- writeFileSync(join(run.runDir, "report.json"), `${JSON.stringify(report, null, 2)}\n`, "utf8");+ // The trace guard, SECOND pass: the assembled report must agree with+ // the trace it was built from (same aggregation, including the+ // standing_instruction headline exclusion) - refused before anything+ // is written, so a buildReport regression cannot publish silently.+ validateBenchTrace({ runDir: run.runDir, fixture: opts.fixture, results, report });+ atomicWriteFileSync(join(run.runDir, "report.json"), `${JSON.stringify(report, null, 2)}\n`);if (!phaseDone(checkpoint, "report")) {completeBenchPhase(run.runDir, checkpoint, "report");}@@ -913,24 +960,10 @@ function buildReport(embeddings?: BenchEmbeddingReceipt,longmemeval?: BenchLongMemEvalFamily,): BenchReport {- const byCategory: Record<string, { passed: number; total: number }> = {};- let passed = 0;- let total = 0;- for (const result of results) {- const bucket = (byCategory[result.category] ??= { passed: 0, total: 0 });- bucket.total += 1;- if (result.pass) {- bucket.passed += 1;- }- // The standing_instruction category never folds into the headline- // (recall-lane-latency): its rate stays the named line of its own in- // `by_category`, so adding facet questions to a fixture cannot shift- // the headline pass rate a baseline compares.- if (result.category !== STANDING_INSTRUCTION_CATEGORY) {- total += 1;- if (result.pass) passed += 1;- }- }+ // ONE copy of the counting rule - the guards' `countQuestionResults`,+ // which the pre-write trace cross-check (T7) runs against the same+ // results - so the published counts and their validation cannot drift.+ const { passed, total, byCategory } = countQuestionResults(results);const latencies = results.map((result) => result.latency_ms);// The latency family's overlap figure (recall-lane-latency): averaged// over the questions that attempted the semantic lane, present onlydiff --git a/src/core/bench/run-store.ts b/src/core/bench/run-store.tsindex b3340453..70cd5ce3 100644--- a/src/core/bench/run-store.ts+++ b/src/core/bench/run-store.ts@@ -13,7 +13,7 @@* guard refuses run ids that resolve outside the runs directory.*/-import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";+import { existsSync, mkdirSync, readFileSync, renameSync, rmSync, writeFileSync } from "node:fs";import { join, resolve, sep } from "node:path";import { canonicalJson, sha256Hex } from "../integrity/digest.ts";@@ -79,8 +79,25 @@ export function benchResultsDir(runDir: string): string {return join(runDir, "results");}-export function createBenchRun(- runsDir: string,+/**+ * The run directory for a run id, resolved exactly the way the store+ * resolves it - through the {@link guardedRunDir} checks (finding 31):+ * the preflight and the pipeline consume this path BEFORE the store's+ * own guard runs (the search config is resolved against the run's future+ * vault so a refusal there can leave no run dir behind), so a run id the+ * guard would refuse is refused HERE, before any path is built or read.+ */+export function benchRunDirPath(runsDir: string, runId: string): string {+ return guardedRunDir(runsDir, runId);+}++/**+ * The run id a fresh run is about to take: second-precision timestamp+ * plus the identity hex. One fact, shared by `createBenchRun` and the+ * pipeline's preflight collision check, so the id the guard reads is the+ * id the store writes.+ */+export function nextBenchRunId(fixture: BenchFixture,opts: {now?: Date;@@ -88,16 +105,62 @@ export function createBenchRun(recallFloor?: number;sample?: BenchSampleRequest;} = {},-): BenchRunHandle {+): string {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, opts.sample);const stamp = now.toISOString().replace(/[^0-9]/g, "").slice(0, 14);- const runId = `run-${stamp}-${identity.slice(0, 6)}`;+ return `run-${stamp}-${identity.slice(0, 6)}`;+}++/**+ * Write `data` atomically: a temp file renamed over the target, so a+ * crash mid-write leaves the previous generation intact instead of a+ * truncated published artifact. The bench vector cache established the+ * pattern (`embedding-cache.ts`); checkpoints, per-question results and+ * the report all go through it now.+ */+export function atomicWriteFileSync(filePath: string, data: string): void {+ const tmp = `${filePath}.${process.pid}.tmp`;+ try {+ writeFileSync(tmp, data, "utf8");+ renameSync(tmp, filePath);+ } catch (cause) {+ try {+ rmSync(tmp, { force: true });+ } catch {+ // The original failure is the one to report.+ }+ throw cause;+ }+}++export function createBenchRun(+ runsDir: string,+ fixture: BenchFixture,+ 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);+ // The identity is computed from the same inputs the run id was, so the+ // checkpoint's knobs_hash stays the exact value the id embeds a slice+ // of (`nextBenchRunId` shares this computation for the collision check).+ const identity = benchRunIdentityHash(fixture, knobs, opts.recallFloor, opts.sample);+ const runId = nextBenchRunId(fixture, {+ now,+ pinnedKnobs: knobs,+ ...(opts.recallFloor !== undefined ? { recallFloor: opts.recallFloor } : {}),+ ...(opts.sample !== undefined ? { sample: opts.sample } : {}),+ });const runDir = guardedRunDir(runsDir, runId);mkdirSync(runDir, { recursive: true });const checkpoint: BenchCheckpoint = Object.freeze({@@ -124,12 +187,7 @@ export function loadBenchRun(sample?: BenchSampleRequest;} = {},): BenchRunHandle {- const runDir = guardedRunDir(runsDir, runId);- const path = join(runDir, CHECKPOINT_FILE);- if (!existsSync(path)) {- throw new Error(`bench run not found: ${runId}`);- }- const checkpoint = parseCheckpoint(JSON.parse(readFileSync(path, "utf8")));+ const checkpoint = readBenchCheckpoint(runsDir, runId);if (opts.expectFixture !== undefined) {const expected = fixtureHash(opts.expectFixture);if (expected !== checkpoint.fixture_hash) {@@ -155,7 +213,7 @@ export function loadBenchRun();}}- return Object.freeze({ runId, runDir, checkpoint });+ return Object.freeze({ runId, runDir: benchRunDirPath(runsDir, runId), checkpoint });}/** Mark a phase complete (idempotent) and persist the checkpoint. */@@ -177,11 +235,44 @@ export function phaseDone(checkpoint: BenchCheckpoint, phase: BenchPhase): boolereturn checkpoint.completed_phases.includes(phase);}+/**+ * Read and parse one run's checkpoint. Missing run: the long-standing+ * "bench run not found" error. Corrupt JSON: a NAMED error carrying the+ * file path - never a raw SyntaxError; the pipeline's preflight refuses+ * the same state with the rendering contract before this is reached.+ */+export function readBenchCheckpoint(runsDir: string, runId: string): BenchCheckpoint {+ const runDir = guardedRunDir(runsDir, runId);+ const path = join(runDir, CHECKPOINT_FILE);+ if (!existsSync(path)) {+ throw new Error(`bench run not found: ${runId}`);+ }+ let raw: unknown;+ try {+ raw = JSON.parse(readFileSync(path, "utf8"));+ } catch (cause) {+ throw new Error(+ `bench checkpoint at ${path} is not valid JSON: ${+ cause instanceof Error ? cause.message : String(cause)+ } - the run directory is damaged; start a fresh run`,+ );+ }+ return parseCheckpoint(raw);+}+function persist(runDir: string, checkpoint: BenchCheckpoint): void {- writeFileSync(join(runDir, CHECKPOINT_FILE), `${JSON.stringify(checkpoint, null, 2)}\n`, "utf8");+ atomicWriteFileSync(join(runDir, CHECKPOINT_FILE), `${JSON.stringify(checkpoint, null, 2)}\n`);}-function parseCheckpoint(raw: unknown): BenchCheckpoint {+/**+ * Parse and validate one raw checkpoint document: the ONE definition of+ * the shape a resume may act on. Exported so the pipeline's resume+ * preflight runs this SAME gate before the store loads - a document that+ * parses as JSON but lacks the required fields is refused there by name+ * (the file and the missing fields) instead of surfacing here as a plain+ * Error the CLI does not render (M11).+ */+export function parseCheckpoint(raw: unknown): BenchCheckpoint {if (raw === null || typeof raw !== "object") {throw new Error("bench checkpoint: malformed JSON");}@@ -194,6 +285,11 @@ function parseCheckpoint(raw: unknown): BenchCheckpoint {const knobsHash = record["knobs_hash"];const pinnedKnobs = record["pinned_knobs"];const sample = record["sample"];+ // The missing fields are NAMED - the preflight renders this message as+ // the refusal detail, and an operator repairing a damaged run needs to+ // know which fields the checkpoint lost, not just that it lost some.+ // (The combined condition is what narrows the fields for the rest of+ // the parser, so the names are collected inside it.)if (typeof runId !== "string" ||typeof fixtureName !== "string" ||@@ -201,7 +297,14 @@ function parseCheckpoint(raw: unknown): BenchCheckpoint {typeof createdAt !== "string" ||!Array.isArray(phases)) {- throw new Error("bench checkpoint: missing required fields");+ const missing = [+ ...(typeof runId !== "string" ? ["run_id"] : []),+ ...(typeof fixtureName !== "string" ? ["fixture_name"] : []),+ ...(typeof hash !== "string" ? ["fixture_hash"] : []),+ ...(typeof createdAt !== "string" ? ["created_at"] : []),+ ...(!Array.isArray(phases) ? ["completed_phases"] : []),+ ];+ throw new Error(`bench checkpoint: missing required field(s) ${missing.join(", ")}`);}if (knobsHash !== undefined && typeof knobsHash !== "string") {throw new Error("bench checkpoint: knobs_hash must be a string");@@ -218,10 +321,24 @@ function parseCheckpoint(raw: unknown): BenchCheckpoint {) {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),- );+ // A phase name this build does not know means the checkpoint was+ // written by a different build. The old behavior silently FILTERED the+ // unknown name out and resumed as if the phase never happened - which+ // re-ran work under an identity that claimed it was done. Refuse by+ // name instead (the pipeline's preflight refuses the same state with+ // the `refused (<kind>)` render before this is reached).+ const completed: BenchPhase[] = [];+ for (const phase of phases) {+ if (typeof phase !== "string" || !(BENCH_PHASES as ReadonlyArray<string>).includes(phase)) {+ throw new Error(+ `bench checkpoint: unknown phase '${String(phase)}' in completed_phases - ` ++ "the checkpoint was written by a different build; restart the run",+ );+ }+ // The includes() guard above is the membership proof; the array's+ // element type does not carry it, so the narrow is asserted here.+ completed.push(phase as BenchPhase);+ }return Object.freeze({run_id: runId,fixture_name: fixtureName,@@ -244,8 +361,16 @@ function parseCheckpoint(raw: unknown): BenchCheckpoint {});}-/** Resolve a run directory and refuse anything outside the runs dir. */-function guardedRunDir(runsDir: string, runId: string): string {+/**+ * Resolve a run directory and refuse anything outside the runs dir: the+ * charset rule (a run id is `[A-Za-z0-9._-]+`), the all-dots rule (`.` and+ * `..` pass the charset and resolve inside the root) and the containment+ * rule (the resolved dir must stay under the runs dir). Exported so every+ * site that derives a run-dir path from a CLI-typed id - the preflight's+ * probe reads, the pipeline's pre-creation path resolution - applies the+ * SAME guard BEFORE any read, not only the store's own checkpoint read.+ */+export function guardedRunDir(runsDir: string, runId: string): string {if (!/^[A-Za-z0-9._-]+$/.test(runId)) {throw new Error(`bench run id contains unsafe characters: ${runId}`);}diff --git a/src/core/brain/anticipatory-cache.ts b/src/core/brain/anticipatory-cache.tsindex 632b7774..5e18f3e5 100644--- a/src/core/brain/anticipatory-cache.ts+++ b/src/core/brain/anticipatory-cache.ts@@ -21,9 +21,11 @@ import { createHash } from "node:crypto";import { existsSync, mkdirSync, readFileSync } from "node:fs";import { join, posix } from "node:path";+import { resolveModelContextWindowEnvTokens } from "../config.ts";import { atomicWriteFileSync } from "../fs-atomic.ts";import type { StampTokens } from "../integrity/stamp.ts";import { packContext, type ContextPackItem } from "./context-pack.ts";+import { resolveModelContextWindowTokens } from "./model-window.ts";import { readLineageLedger } from "./lineage/ledger.ts";import { packStampRefusal, packStampTokens, type ContextPackStamp } from "./pack-stamp.ts";import { resolveOwnerScopeDelivery } from "./preferences-collect.ts";@@ -31,6 +33,7 @@ import { resolveSessionLineage } from "./lineage/resolve.ts";import { BRAIN_ROOT_REL, ensureInsideVault } from "./paths.ts";import { assertVaultIdentityForWrite } from "./vault-identity.ts";import { searchSessionRecall, type SessionRecallHit } from "./session-recall.ts";+import { loadBrainConfig } from "./policy.ts";/*** Cache-file schema token. Bumped to `v2` by context-integrity-gates@@ -47,6 +50,14 @@ export const ANTICIPATORY_SCHEMA_VERSION = "o2b.anticipatory.v2";export const DEFAULT_ANTICIPATORY_TTL_SECONDS = 120;/** Default token budget for the cached context pack. */export const DEFAULT_ANTICIPATORY_MAX_TOKENS = 2_000;+/**+ * The share of a resolved context window the default budget becomes when+ * the window-fraction derivation fires (t_a567cc12, B4): 1/100th, so a+ * declared 1M window budgets 10_000 and a 500k one 5_000. A divisor, not+ * a float fraction, so the division is exact at every value the resolver+ * can hand over (integers in [100_000, 1_000_000]).+ */+const ANTICIPATORY_WINDOW_BUDGET_DIVISOR = 100;const DEFAULT_SESSION_HITS = 5;const CACHE_DIR_REL = posix.join(BRAIN_ROOT_REL, ".state", "anticipatory");@@ -78,6 +89,15 @@ export interface RefreshAnticipatoryCacheResult {readonly refreshed: boolean;readonly rootSessionId: string;readonly path: string;+ /**+ * The window-derived budget the refresh answered under (t_a567cc12,+ * B4), present only when a resolved context window - the operator's+ * `context:` block or the environment override - lifted the default+ * above its historical 2_000 floor. Absent on an explicit-budget call+ * and whenever nothing resolvable left the constant standing, so the+ * default-vault result is byte-identical.+ */+ readonly derivedMaxTokens?: number;}export type AnticipatoryCacheState = "warm" | "stale" | "miss";@@ -112,6 +132,15 @@ export interface ReadAnticipatoryContextResult {*/readonly cache_refusal?: string;readonly context: AnticipatoryContext;+ /**+ * The window-derived budget this read answered under (t_a567cc12, B4),+ * present only when a resolved context window lifted the default above+ * its historical 2_000 floor - the read-side twin of+ * `derivedMaxTokens`, so a consumer can tell a derived warm cache from+ * a constant-budget one. Absent on an explicit-budget read and on the+ * default-vault path.+ */+ readonly derived_max_tokens?: number;}/** On-disk form of {@link ContextPackStamp} (snake_case, like its siblings). */@@ -287,6 +316,64 @@ function cacheRefusal(vault: string, cached: CacheFile, now: Date): string | nulreturn packStampRefusal(fromCacheStamp(cached.stamp), packStampTokens(vault), now);}+/**+ * The window-derived default budget (t_a567cc12, B4), or `undefined` when+ * the historical constant stands.+ *+ * Fires only on the derivation path - an explicit `maxTokens` input never+ * reads the vault or the environment, so the explicit path behaves+ * byte-identically to before the resolver existed. When it fires, the+ * operator's `context:` block and the environment override are resolved+ * through the shared model-window resolver (config > env; no model id+ * reaches this module, so the declared/suffix tiers have no channel+ * here), and the budget becomes the window's {@link+ * ANTICIPATORY_WINDOW_BUDGET_DIVISOR}th part, floored at+ * {@link DEFAULT_ANTICIPATORY_MAX_TOKENS} so it only ever scales UP.+ *+ * `disclosed` is the derived budget only when it lifted above the+ * historical constant: at the floor the derivation answered with exactly+ * the value the constant would have, so there is nothing derived to+ * disclose and nothing observable changed.+ *+ * Fail-soft on both channels, matching this module's contract: a broken+ * `_brain.yaml` or a malformed env value leaves the derivation empty -+ * the config raise happens later, where the pack builds, exactly as it+ * always has, and this channel must not answer for the operator's config+ * before the real reader does.+ */+interface DerivedWindowBudget {+ readonly budget: number;+ readonly disclosed: number | undefined;+}++function deriveWindowBudget(vault: string): DerivedWindowBudget | undefined {+ let operatorWindow: number | undefined;+ try {+ operatorWindow = loadBrainConfig(vault).context?.window_tokens;+ } catch {+ operatorWindow = undefined;+ }+ let envWindow: number | undefined;+ try {+ envWindow = resolveModelContextWindowEnvTokens();+ } catch {+ envWindow = undefined;+ }+ if (operatorWindow === undefined && envWindow === undefined) return undefined;+ const resolved = resolveModelContextWindowTokens({+ ...(operatorWindow !== undefined ? { operatorWindowTokens: operatorWindow } : {}),+ ...(envWindow !== undefined ? { envWindowTokens: envWindow } : {}),+ });+ const budget = Math.max(+ DEFAULT_ANTICIPATORY_MAX_TOKENS,+ Math.floor(resolved.windowTokens / ANTICIPATORY_WINDOW_BUDGET_DIVISOR),+ );+ return {+ budget,+ disclosed: budget === DEFAULT_ANTICIPATORY_MAX_TOKENS ? undefined : budget,+ };+}+/*** Refresh the cache for the session's lineage root unless a fresh copy* already exists (TTL debounce).@@ -307,7 +394,10 @@ export function refreshAnticipatoryCache(const rootId = resolveRootId(vault, input.sessionId);const path = anticipatoryCachePath(vault, rootId, input.agentScope);const ttlMs = (input.ttlSeconds ?? DEFAULT_ANTICIPATORY_TTL_SECONDS) * 1_000;- const maxTokens = input.maxTokens ?? DEFAULT_ANTICIPATORY_MAX_TOKENS;+ const derived = input.maxTokens === undefined ? deriveWindowBudget(vault) : undefined;+ const maxTokens = input.maxTokens ?? derived?.budget ?? DEFAULT_ANTICIPATORY_MAX_TOKENS;+ const disclosure =+ derived?.disclosed !== undefined ? { derivedMaxTokens: derived.disclosed } : {};try {const existing = readCacheFile(path);// TTL debounce applies only to a cache built under the same token@@ -329,7 +419,12 @@ export function refreshAnticipatoryCache(age < ttlMs &&cacheRefusal(vault, existing, input.now) === null) {- return Object.freeze({ refreshed: false, rootSessionId: rootId, path });+ return Object.freeze({+ refreshed: false,+ rootSessionId: rootId,+ path,+ ...disclosure,+ });}}const bundle = buildBundle(vault, {@@ -352,9 +447,19 @@ export function refreshAnticipatoryCache(};mkdirSync(join(vault, CACHE_DIR_REL), { recursive: true });atomicWriteFileSync(path, `${JSON.stringify(cache, null, 2)}\n`);- return Object.freeze({ refreshed: true, rootSessionId: rootId, path });+ return Object.freeze({+ refreshed: true,+ rootSessionId: rootId,+ path,+ ...disclosure,+ });} catch {- return Object.freeze({ refreshed: false, rootSessionId: rootId, path });+ return Object.freeze({+ refreshed: false,+ rootSessionId: rootId,+ path,+ ...disclosure,+ });}}@@ -378,7 +483,10 @@ export function readAnticipatoryContext(const rootId = resolveRootId(vault, input.sessionId);const path = anticipatoryCachePath(vault, rootId, input.agentScope);const ttlMs = (input.ttlSeconds ?? DEFAULT_ANTICIPATORY_TTL_SECONDS) * 1_000;- const requestedTokens = input.maxTokens ?? DEFAULT_ANTICIPATORY_MAX_TOKENS;+ const derived = input.maxTokens === undefined ? deriveWindowBudget(vault) : undefined;+ const requestedTokens = input.maxTokens ?? derived?.budget ?? DEFAULT_ANTICIPATORY_MAX_TOKENS;+ const disclosure =+ derived?.disclosed !== undefined ? { derived_max_tokens: derived.disclosed } : {};const cached = readCacheFile(path);if (cached !== null) {const age = input.now.getTime() - Date.parse(cached.generated_at);@@ -394,6 +502,7 @@ export function readAnticipatoryContext(root_session_id: rootId,generated_at: cached.generated_at,context: cached.context,+ ...disclosure,});}return Object.freeze({@@ -407,6 +516,7 @@ export function readAnticipatoryContext(agentScope: input.agentScope,now: input.now,}).context,+ ...disclosure,});}return Object.freeze({@@ -419,6 +529,7 @@ export function readAnticipatoryContext(agentScope: input.agentScope,now: input.now,}).context,+ ...disclosure,});}return Object.freeze({@@ -431,6 +542,7 @@ export function readAnticipatoryContext(agentScope: input.agentScope,now: input.now,}).context,+ ...disclosure,});}@@ -458,16 +570,18 @@ export function buildReaderAnticipatoryContext(): ReadAnticipatoryContextResult {const rootId = resolveRootId(vault, input.sessionId);const signal = input.signalText?.trim();+ const derived = input.maxTokens === undefined ? deriveWindowBudget(vault) : undefined;return Object.freeze({cache_state: "miss" as const,root_session_id: rootId,context: buildBundle(vault, {sessionId: input.sessionId,signalText: signal !== undefined && signal.length > 0 ? signal : undefined,- maxTokens: input.maxTokens ?? DEFAULT_ANTICIPATORY_MAX_TOKENS,+ maxTokens: input.maxTokens ?? derived?.budget ?? DEFAULT_ANTICIPATORY_MAX_TOKENS,agentScope: input.agentScope,now: input.now,visible: input.visible,}).context,+ ...(derived?.disclosed !== undefined ? { derived_max_tokens: derived.disclosed } : {}),});}diff --git a/src/core/brain/config-template.ts b/src/core/brain/config-template.tsindex 007067d9..4bcbfb0f 100644--- a/src/core/brain/config-template.ts+++ b/src/core/brain/config-template.ts@@ -74,6 +74,7 @@ import {DEFAULT_ROLLUP_IDENTITY_THRESHOLD,} from "./rollup-ladder.ts";import { SCHEMA_VOCAB_CATEGORIES } from "./schema-vocab.ts";+import { CONTEXT_WINDOW_TOKENS_DEFAULT } from "./policy.ts";/*** How one key is emitted.@@ -324,6 +325,40 @@ export const BRAIN_CONFIG_TEMPLATE: ReadonlyArray<BrainTemplateBlock> = Object.fdef("max_tokens", DEFAULT_ANTICIPATORY_MAX_TOKENS),],},+ {+ key: "context",+ doc: [+ "The host model's context window, in tokens. Sizes context packs,",+ "preset suggestions and compact guidance. This key wins over the",+ "OPEN_SECOND_BRAIN_MODEL_CONTEXT_WINDOW environment variable, and a",+ "well-formed value is used exactly as declared - the operator knows",+ "the true window - never clamped.",+ ],+ emit: "commented-default",+ keys: [def("window_tokens", CONTEXT_WINDOW_TOKENS_DEFAULT)],+ },+ {+ key: "cross_topic",+ doc: [+ "Opt-in dream-pass promotion of a recurring cross-topic rule:",+ "confirmed preferences in at least min_topics distinct topics whose",+ "principles reach jaccard similarity, promoted once per owner per",+ "calendar day. The whole block absent means off - the default",+ "install never fires it.",+ ],+ emit: "commented-default",+ keys: [+ def("enabled", false),+ example("min_topics", 2, [+ "The value below is an illustration, not a default: the planner",+ "ships its own floors. Set it to tune when a cluster may fire.",+ ]),+ example("jaccard", 0.6, [+ "The similarity floor, in [0, 1]. Also an illustration, not a",+ "default.",+ ]),+ ],+ },{key: "discipline_report",doc: [diff --git a/src/core/brain/context-presets.ts b/src/core/brain/context-presets.tsindex a1349f64..1bae3f99 100644--- a/src/core/brain/context-presets.ts+++ b/src/core/brain/context-presets.ts@@ -1,3 +1,5 @@+import { resolveModelContextWindowTokens, type ResolvedModelWindow } from "./model-window.ts";+export type ContextPresetId = "tight-context" | "long-context";export type ContextPresetConfidence = "high" | "medium" | "low";@@ -31,6 +33,15 @@ export interface ContextPresetSuggestion {readonly confidence: ContextPresetConfidence;readonly reason: string;readonly preset: ContextBudgetPreset;+ /**+ * Present only when the window was RESOLVED from the model id through+ * the shared resolver AND that resolution decided the preset (a+ * declared table hit, a `1m` suffix, or the default when no hint+ * outranks it). An explicit window is the caller's own number, and a+ * hint-only model answers from its hint: neither claims a resolved+ * window.+ */+ readonly resolvedWindow?: ResolvedModelWindow;}export interface ContextPresetCurrentConfig {@@ -105,42 +116,176 @@ export function getContextPreset(id: string): ContextBudgetPreset | null {return PRESETS.find((preset) => preset.id === id) ?? null;}+/**+ * The preset whose window bucket contains `window`. The one definition of+ * the bucket mapping - suggest sizes from it, and so does every surface+ * that derives a budget from a resolved window (t_a567cc12) - so a caller+ * can never size from a different mapping than a suggestion named. A+ * budget derived for a MODEL goes through {@link presetForResolvedWindow},+ * which layers the shared hint fallback on this mapping when the+ * resolver's answer is the default-sourced assumption.+ */+export function presetForWindowTokens(window: number): ContextBudgetPreset {+ const hit = PRESETS.find(+ (preset) =>+ window >= preset.context_window_tokens.min &&+ (preset.context_window_tokens.max === null || window <= preset.context_window_tokens.max),+ );+ // The buckets tile [0, ∞), so the fallback is unreachable; it keeps the+ // compiler honest without inventing a third preset.+ return hit ?? PRESETS[0]!;+}++/**+ * The `model_hints` fallback, defined once: the preset whose hint list+ * contains a whole token of the id - the lowercased id split on+ * `[-_.:/@\s]+`, and the hint must EQUAL one token, so "mini" never+ * matches inside "gemini" while a real `mini` token still does.+ * {@link suggestContextPreset} answers from it when the resolver has+ * nothing published to say, and {@link presetForResolvedWindow} budgets+ * from it on exactly the same condition - so a hint-only model suggests+ * and budgets one mapping.+ */+function hintPresetForModel(model: string | null | undefined): ContextBudgetPreset | null {+ const id = model?.toLowerCase() ?? "";+ if (id === "") return null;+ const tokens = new Set(id.split(/[-_.:/@\s]+/));+ return PRESETS.find((preset) => preset.model_hints.some((hint) => tokens.has(hint))) ?? null;+}++/**+ * The pack-budget refusal for a model id nothing published places: no+ * declared table row, no `1m`/`[1m]` suffix, no matching hint. The+ * derived budget used to answer such an id with the default window's+ * long-context `max_tokens` - about three times an 8k local model's+ * whole window - so the pack surfaces refuse instead, the conservative+ * posture they held before derivation existed. `null` means the id IS+ * placed and budgets from its resolved window (table, suffix) or its+ * hint. A blank or absent model is ABSENT - the same condition the+ * surfaces' nothing-resolvable refusal already answers - so the two+ * refusals agree, and {@link suggestContextPreset} answers its+ * conservative fallback on exactly this predicate.+ */+export function unrecognisedModelBudgetRefusal(+ model: string | null | undefined,+ resolved: ResolvedModelWindow,+): string | null {+ if (resolved.source !== "default") return null;+ const id = model?.trim() ?? "";+ if (id !== "" && hintPresetForModel(id) !== null) return null;+ return id === ""+ ? "model not recognised; pass max_tokens or set context.window_tokens"+ : `model '${id}' not recognised; pass max_tokens or set context.window_tokens`;+}++/**+ * The preset a DERIVED budget sizes from for one model id: the mapping+ * the resolved window names - except when that answer is the resolver's+ * `default`-sourced assumption about the host, where the same+ * `model_hints` fallback {@link suggestContextPreset} answers with+ * applies, so a hint-only id (the reviewed disagreement: `gemini-2.5-flash`+ * suggested tight-context from its hint while the pack budgeted+ * long-context from the default window) budgets and suggests one mapping.+ * An id the table knows resolves from the table on both surfaces and+ * never from its hint; a model-free call (an operator channel resolved+ * the window) has no hint to apply and sizes from the resolved window.+ * An id NOTHING places (default source, no hint) never reaches a pack+ * budget from here - the pack surfaces refuse it first through+ * {@link unrecognisedModelBudgetRefusal} - and the pre-compress caps+ * path, which must always answer, keeps this mapping for it.+ * The window's `source` stays what the surface discloses either way.+ */+export function presetForResolvedWindow(+ model: string | null | undefined,+ resolved: ResolvedModelWindow,+): ContextBudgetPreset {+ if (resolved.source === "default") {+ const byHint = hintPresetForModel(model);+ if (byHint !== null) return byHint;+ }+ return presetForWindowTokens(resolved.windowTokens);+}++/**+ * The conservative fallback, defined once: tight-context, low+ * confidence, the answer for every call nothing published places - a+ * model-free call, or a model id with no window source, no suffix and no+ * hint. Never claims a resolved window.+ */+function conservativeFallbackSuggestion(): ContextPresetSuggestion {+ const fallback = PRESETS[0]!;+ return {+ preset_id: fallback.id,+ confidence: "low",+ reason: "no model or context-window hint matched; using conservative default",+ preset: fallback,+ };+}+export function suggestContextPreset(input: ContextPresetSuggestionInput): ContextPresetSuggestion {const model = input.model?.toLowerCase() ?? "";- const byModel = PRESETS.find((preset) => preset.model_hints.some((hint) => model.includes(hint)));- if (byModel) {++ // Order (deliberate, changed by this branch from the hint-first order+ // it replaced): an explicit window wins over a matching `model_hints`+ // token. The window is authoritative - it is the caller's own+ // number for the deployment at hand, the same figure a derived budget+ // sizes from, just as the operator-config channel is authoritative in+ // the resolver - while a hint is a heuristic read off the id, and a+ // hint answers only when the resolver has nothing published to say. A+ // caller passing both therefore gets the window's mapping, and nothing+ // is resolved: the number was given, not inferred.+ const window = input.contextWindowTokens;+ if (window !== undefined && Number.isFinite(window)) {+ const byWindow = presetForWindowTokens(window);return {- preset_id: byModel.id,+ preset_id: byWindow.id,confidence: "high",- reason: `model hint matched ${byModel.id}`,- preset: byModel,+ reason: `context window ${window} tokens matched ${byWindow.id}`,+ preset: byWindow,};}- const window = input.contextWindowTokens;- if (window !== undefined && Number.isFinite(window)) {- const byWindow = PRESETS.find(- (preset) =>- window >= preset.context_window_tokens.min &&- (preset.context_window_tokens.max === null || window <= preset.context_window_tokens.max),- );- if (byWindow) {+ // The window resolves FIRST, through the same resolver every derived+ // budget sizes from, so a suggestion can never name a different mapping+ // than the pack uses for the same model: a table-declared id that also+ // matches a hint answers from the table here AND in the pack budget+ // (the reviewed disagreement), and a hint-only id falls to the SAME+ // `model_hints` fallback on both surfaces - the pack derivation applies+ // it through presetForResolvedWindow whenever the resolver's+ // answer is the default-sourced assumption. A hint never masquerades as+ // a resolved window: the hint answer claims no `resolvedWindow`.+ if (model !== "") {+ const resolved = resolveModelContextWindowTokens({ model: input.model });+ if (resolved.source !== "default") {+ const byWindow = presetForWindowTokens(resolved.windowTokens);+ const clampedNote = resolved.clamped ? " (clamped)" : "";return {preset_id: byWindow.id,confidence: "high",- reason: `context window ${window} tokens matched ${byWindow.id}`,+ reason: `context window ${resolved.windowTokens} tokens resolved from ${resolved.source}${clampedNote} matched ${byWindow.id}`,preset: byWindow,+ resolvedWindow: resolved,};}+ const byModel = hintPresetForModel(input.model);+ if (byModel) {+ return {+ preset_id: byModel.id,+ confidence: "high",+ reason: `model hint matched ${byModel.id}`,+ preset: byModel,+ };+ }+ // Nothing published places the id: the resolver's answer is the+ // default-sourced assumption and no hint matched, so the conservative+ // fallback answers - the same tight-context/low answer a model-free+ // call gets, and the exact condition the pack budget surfaces refuse+ // on ({@link unrecognisedModelBudgetRefusal}). An ASSUMED window is+ // never a basis for a suggestion: no `resolvedWindow` is claimed.+ return conservativeFallbackSuggestion();}- const fallback = PRESETS[0]!;- return {- preset_id: fallback.id,- confidence: "low",- reason: "no model or context-window hint matched; using conservative default",- preset: fallback,- };+ return conservativeFallbackSuggestion();}export function diffContextPreset(diff --git a/src/core/brain/continuity/types.ts b/src/core/brain/continuity/types.tsindex d98d4b01..50fdda10 100644--- a/src/core/brain/continuity/types.ts+++ b/src/core/brain/continuity/types.ts@@ -85,6 +85,16 @@ export type ContinuityRecordKind =* pre-filter's regret metric.*/| "decision_model_extract_commit"+ /**+ * One cached verdict set of the preregistered decision-model eval+ * (cycle 20261020, t_4e1681b3). Spec hash, fixture hash, profile, use,+ * take item ids, boolean verdicts and the counted metric -+ * identifiers, numbers and booleans, never item text. Review evidence+ * only: the machine-consumed tuning mark lives outside the vault, and+ * this kind is kept (never folded) so `o2b decision-model eval list`+ * can audit what any mark claimed.+ */+ | "decision_model_eval_grade"/*** One mined entity mention from a session turn (recall-quality wave,* Lane B): one record per (family, key, sessionRef), where family is a@@ -147,6 +157,7 @@ export const CONTINUITY_RECORD_KINDS: ReadonlyArray<ContinuityRecordKind> = Obje"negative_recall","decision_model_call","decision_model_extract_commit",+ "decision_model_eval_grade","session_entity_mention","receipt_compaction",]);diff --git a/src/core/brain/dream-apply.ts b/src/core/brain/dream-apply.tsindex dfd929e2..04012b02 100644--- a/src/core/brain/dream-apply.ts+++ b/src/core/brain/dream-apply.ts@@ -199,6 +199,45 @@ function writePreferences(input: DreamApplyInput, agent: string): void {);}+ // Cross-topic rule promotion (t_642bc2b8): the planned rule is an+ // ordinary unconfirmed preference through the same txn chokepoint -+ // `inferred` provenance plus the evidence wikilinks and `related`+ // lineage are what make it a promotion rather than a new claim.+ // `overwrite: false` like the topic plan: the planner's content-slug+ // dedup already decided the file is new, and a surprise collision+ // must fail loudly rather than clobber.+ for (const ct of plan.crossTopicRules) {+ writePreferenceTxn(+ vault,+ {+ slug: ct.slug,+ topic: ct.topic,+ principle: ct.principle,+ created_at: isoSecond(now),+ unconfirmed_until: isoSecond(addDays(now, cfg.dream.unconfirmed_window_days)),+ status: BRAIN_PREFERENCE_STATUS.unconfirmed,+ evidenced_by: ct.evidencedBy,+ // No evidence yet, matching the topic plan's pre-seeding.+ confidence_value: 0,+ recentApplied: [],+ recentViolated: [],+ provenance: "inferred",+ related: ct.related,+ // The strictest visibility of the sources (review finding 63):+ // the rule restates a source's principle verbatim, so it may+ // never land at default visibility behind a restricted source.+ // Written only when non-empty, like the topic plan's stamp.+ ...(ct.visibility.length > 0 ? { visibility: ct.visibility } : {}),+ // The sources' shared owner token, so owner-scoped recall keeps+ // the rule as private as its sources; ownerless rules omit it.+ ...(ct.owner ? { owner: ct.owner } : {}),+ },+ [],+ { overwrite: false },+ historyOpts,+ );+ }+for (const update of refresh.updated.values()) {// Rebuild the evidence slice from the log on every pass so the// pref body stays in sync with the counters even when the@@ -231,6 +270,22 @@ function writePreferences(input: DreamApplyInput, agent: string): void {...(update.freshness_trend !== undefined? { freshness_trend: update.freshness_trend }: {}),+ // Derived-fact fields (finding 77): the update carries a promoted+ // rule's provenance and lineage through its counter changes, in+ // the same render position the writer uses, so the bytes match+ // the no-op pre-flight and the fields survive every rewrite.+ ...(update.provenance !== undefined ? { provenance: update.provenance } : {}),+ ...(update.related !== undefined && update.related.length > 0+ ? { related: update.related }+ : {}),+ // The record's `visibility:` tokens (review round 2), threaded like+ // provenance and related: the update write is the only thing that+ // keeps the line on a restricted rule through its counter changes,+ // and the no-op pre-flight needs the input to carry it to match the+ // bytes on disk. Written only when non-empty, like every stamp.+ ...(update.visibility !== undefined && update.visibility.length > 0+ ? { visibility: update.visibility }+ : {}),...(update.scope ? { scope: update.scope } : {}),lenientScopeTags: true,},diff --git a/src/core/brain/dream-plan-cross-topic.ts b/src/core/brain/dream-plan-cross-topic.tsnew file mode 100644index 00000000..fa2e1412--- /dev/null+++ b/src/core/brain/dream-plan-cross-topic.ts@@ -0,0 +1,635 @@+/**+ * Cross-topic rule promotion (t_642bc2b8): the pure planner that elects+ * ONE recurring cross-topic rule per owner token per calendar day, plus+ * the `Brain/cross-topic-rules.json` ledger that carries that budget.+ *+ * One reason to change: what makes a pattern "recurring across topics"+ * and what may be promoted about it. The deterministic, always-available+ * signal is shared principle text across distinct topic buckets - the+ * lexical layer the same-topic merge machinery (`findSimilarPairs`,+ * `findMergeCandidates`) is blind to by construction, since both bucket+ * entries by topic before comparing. This module inverts that walk:+ * pairs are only considered ACROSS buckets, so a cluster is by+ * construction something no same-topic pass could have acted on.+ *+ * The promoted artifact is an ordinary unconfirmed preference+ * (`provenance: "inferred"`, `evidenced_by` wikilinks to every source,+ * `related` lineage), written by the dream apply stage through+ * `writePreferenceTxn` and left to the normal refresh/confirm/retire+ * machinery afterwards. The planner is pure - no I/O, no wall clock;+ * the ledger is read by the caller and the date comes from the pass's+ * injected `now`, so the same corpus elects the same rule on every+ * machine and a rerun plans nothing.+ *+ * Deliberate limits, named rather than hidden:+ *+ * - Sources are never modified or retired. The planner only reads+ * `scan.preferences` and enqueues one new entry; the promotion is+ * append-only by construction.+ * - A source the same pass plans to retire is not eligible: citing a+ * rule the run is about to move into `retired/` would hang evidence+ * off a moved file.+ * - Sources must share one normalized owner token (ownerless counts+ * as the shared token). A cross-owner cluster is never promoted, so+ * owner-scoped recall cannot leak one agent's rules into another's+ * rule body.+ * - Because the rule restates a source verbatim, the hygiene dedup+ * detector and the digest's merge suggestions WILL eventually+ * nominate it against its own sources. Teaching those predicates to+ * skip pairs where one side cites the other is a follow-up unit;+ * this module only keeps its own output idempotent: the+ * content-derived slug dedups the exact source set, and the+ * duplicate-rule guard below keeps membership churn (a source+ * joining or leaving a promoted cluster, which mints a fresh slug)+ * from re-creating a live rule for a principle the owner's existing+ * inferred rules already carry.+ * - Topic-keyed recall (`query.ts` compares raw topic bytes) will not+ * surface the rule: its synthetic topic is a key no signal carries.+ * The `related` lineage and evidence wikilinks are the way back to+ * it; stretching recall into that key is deliberately out of scope.+ */++import { basename, dirname } from "node:path";+import { existsSync, readFileSync } from "node:fs";++import { strictestVisibilityOf } from "../graph/visibility.ts";+import { atomicWriteFileSync } from "../fs-atomic.ts";+import { sha256Hex } from "../integrity/digest.ts";+import {+ preferenceSlug,+ topicKey,+ RETIRED_ID_PREFIX,+ type PlanState,+ type ScanResult,+} from "./dream-plan.ts";+import type { RefreshResult } from "./dream-refresh.ts";+import { JACCARD_MERGE_SUGGEST_THRESHOLD } from "./merge-candidates.ts";+import { preferenceOwner } from "./owner-scoped-facts.ts";+import { crossTopicLedgerPath } from "./paths.ts";+import { jaccard, tokenise } from "./similarity.ts";+import { isoDate } from "./time.ts";+import { BRAIN_PREFERENCE_STATUS, type BrainConfig } from "./types.ts";+import { assertVaultIdentityForWrite } from "./vault-identity.ts";++/**+ * Minimum distinct folded topic buckets before a cluster may fire.+ * Two is the smallest honest "across topics"; one would re-implement+ * the same-topic merge machinery.+ */+export const DEFAULT_CROSS_TOPIC_MIN_TOPICS = 2;++/**+ * Principle-similarity floor for a cross-bucket pair. Matches the+ * merge-suggestion detector's level (`merge-candidates.ts`): strict+ * enough that a fired cluster reads as "the same rule stated twice in+ * two subjects", loose enough that paraphrase counts.+ */+export const DEFAULT_CROSS_TOPIC_JACCARD = 0.6;++/**+ * The resolver's floor for `min_topics`, the figure the block contract+ * clamps to. Same number as the default, for the reason the default+ * gives: two is the smallest honest "across topics", and a declared 1+ * would elect singletons - each pass copying an arbitrary confirmed+ * preference under a `cross-` slug, the same-topic duplication the+ * floor exists to prevent.+ */+export const MIN_CROSS_TOPIC_MIN_TOPICS = DEFAULT_CROSS_TOPIC_MIN_TOPICS;++/**+ * The resolver's floor for `jaccard`: the merge-suggestion detector's+ * level, the calibration both detectors share. Below it a fired cluster+ * no longer reads as "the same rule stated twice"; at 0 every+ * same-owner cross-bucket pair edges and the whole pool unions into one+ * giant cluster whose representative principle is whatever the sort+ * order put first.+ */+export const MIN_CROSS_TOPIC_JACCARD = JACCARD_MERGE_SUGGEST_THRESHOLD;++/** On-disk ledger schema version. */+export const CROSS_TOPIC_LEDGER_VERSION = 1;++/** Slug prefix of every promoted rule, reserved by content shape. */+const CROSS_SLUG_PREFIX = "cross-";++/** Separator of the slug hash input (sorted source ids). */+const SLUG_ID_JOIN = "\n";++/** Separator of the synthetic topic display. */+const TOPIC_JOIN = " + ";++/**+ * Disclosure code carried by every promotion the duplicate-rule guard+ * declined. The skips ride the planner's result summary - the same+ * channel the daily budget's skips answer on (`fired: false`, nothing+ * written) - so a caller can lift them onto its own warning surface+ * without the planner owning one.+ */+export const CROSS_TOPIC_DUPLICATE_RULE_CODE = "cross-topic-duplicate-rule";++/** Frozen empty skips, shared by every pass that declined nothing. */+const NO_SKIPS: ReadonlyArray<CrossTopicSkip> = Object.freeze([]);++/** Resolved knobs the planner plans against. */+export interface ResolvedCrossTopicConfig {+ readonly minTopics: number;+ readonly jaccard: number;+}++/**+ * One clamp the resolver applied to a declared knob, delivered as a+ * (code, message) pair so the caller files it on whatever warning+ * surface it owns (the dream pass: `DreamRunSummary.warnings`).+ */+export type CrossTopicClampDisclosure = (code: string, message: string) => void;++/**+ * Resolve the planner knobs from the `cross_topic:` block. The block+ * absent, or present with `enabled: false`, is OFF: `null` tells the+ * caller to skip the planner (and the ledger read) entirely, which is+ * what keeps an un-opted-in vault byte-identical.+ *+ * Declared-but-underfloor values resolve to the floors, per the block+ * parser's contract ("an out-of-range but well-formed number is stored+ * by the parser and clamped - and the clamp disclosed - by the consumer+ * that resolves it"): every clamp is delivered through `disclose` when+ * the caller provides one. The parser still refuses wrong-SHAPE values,+ * so what reaches here is always a number; only the range is corrected.+ */+export function resolveCrossTopicConfig(+ cfg: BrainConfig,+ disclose?: CrossTopicClampDisclosure,+): ResolvedCrossTopicConfig | null {+ const block = cfg.cross_topic;+ if (!block?.enabled) return null;+ const declaredMinTopics = block.min_topics ?? DEFAULT_CROSS_TOPIC_MIN_TOPICS;+ const minTopics = Math.max(declaredMinTopics, MIN_CROSS_TOPIC_MIN_TOPICS);+ if (minTopics !== declaredMinTopics) {+ disclose?.(+ "cross-topic-config-clamped",+ `cross_topic.min_topics: ${declaredMinTopics} is below the floor ` ++ `${MIN_CROSS_TOPIC_MIN_TOPICS}; using ${minTopics} (a cluster spans ` ++ `distinct topic buckets)`,+ );+ }+ const declaredJaccard = block.jaccard ?? DEFAULT_CROSS_TOPIC_JACCARD;+ const jaccard = Math.max(declaredJaccard, MIN_CROSS_TOPIC_JACCARD);+ if (jaccard !== declaredJaccard) {+ disclose?.(+ "cross-topic-config-clamped",+ `cross_topic.jaccard: ${declaredJaccard} is below the floor ` ++ `${MIN_CROSS_TOPIC_JACCARD}; using ${jaccard}`,+ );+ }+ return Object.freeze({+ minTopics,+ jaccard,+ });+}++/**+ * Persisted daily budget: the last calendar date each owner token+ * promoted a cross-topic rule. Read fail-open (absent or unparseable+ * treats every owner as under budget - a corrupt ledger must never+ * block the pass it audits).+ */+export interface CrossTopicLedger {+ readonly version: number;+ readonly last_promoted: Readonly<Record<string, string>>;+}++/** Read the ledger, or null when absent or unparseable (treated as fresh). */+export function readCrossTopicLedger(vault: string): CrossTopicLedger | null {+ const path = crossTopicLedgerPath(vault);+ if (!existsSync(path)) return null;+ try {+ const parsed = JSON.parse(readFileSync(path, "utf8")) as Partial<CrossTopicLedger>;+ return Object.freeze({+ version: typeof parsed.version === "number" ? parsed.version : CROSS_TOPIC_LEDGER_VERSION,+ last_promoted: Object.freeze({ ...parsed.last_promoted }),+ });+ } catch {+ return null;+ }+}++/** Persist the ledger. Called only when a promotion fired. */+export function writeCrossTopicLedger(vault: string, ledger: CrossTopicLedger): void {+ // Vault-identity write guard (context-integrity-gates, Unit J), the+ // same discipline as the rollup ledger: the shared atomic writer+ // keeps the write-site census exactly as it was.+ assertVaultIdentityForWrite(vault);+ atomicWriteFileSync(crossTopicLedgerPath(vault), `${JSON.stringify(ledger, null, 2)}\n`);+}++/** One eligible source preference, projected for the pair walk. */+interface Source {+ /** Raw scanned id (`pref-<slug>`, or a hand-authored bare id). */+ readonly id: string;+ /** Normalized slug behind {@link id}. */+ readonly slug: string;+ /** The normalized `pref-<slug>` form used for output and hashing. */+ readonly normalizedId: string;+ /** Folded topic key (the same fold the consolidation pass uses). */+ readonly key: string;+ /** Raw topic display as the file spells it. */+ readonly topic: string;+ readonly principle: string;+ readonly tokens: ReadonlySet<string>;+ /** Budget token: the owner's normalized token, or "" when ownerless. */+ readonly ownerKey: string;+ /**+ * The record's normalised `visibility:` tokens; empty (the default)+ * for an untagged source.+ */+ readonly visibility: ReadonlyArray<string>;+}++export interface CrossTopicPlannerInput {+ readonly scan: ScanResult;+ /**+ * Post-refresh status: a preference the refresh pass promotes to+ * `confirmed` THIS run is an eligible source even though its scanned+ * frontmatter still says `unconfirmed` - the apply stage will have+ * promoted it before the cross-topic write lands.+ */+ readonly refresh: RefreshResult;+ /** Resolved knobs, or null when the feature is off. */+ readonly config: ResolvedCrossTopicConfig | null;+ /** Prior ledger, or null when none has been written yet. */+ readonly ledger: CrossTopicLedger | null;+ /** The pass's injected clock; the budget date comes from here. */+ readonly now: Date;+ /** Entries are pushed onto `plan.crossTopicRules`. */+ readonly plan: PlanState;+}++/** One promotion the duplicate-rule guard declined, with its reason. */+export interface CrossTopicSkip {+ readonly code: string;+ readonly message: string;+}++export interface CrossTopicPlannerResult {+ readonly fired: boolean;+ /**+ * The complete updated ledger to persist when `fired`; null otherwise,+ * so a below-threshold or budgeted-out pass never touches the file -+ * the same byte-identical opt-out the rollup ledger uses.+ */+ readonly ledger: CrossTopicLedger | null;+ /**+ * Promotions the duplicate-rule guard declined this pass, each naming+ * the live rule it would have duplicated. Disclosed, never written: a+ * skipped cluster spends no daily budget, stamps no ledger, and on+ * the run summary reads exactly like the budget's skips -+ * `cross_topic_rules` simply stays absent.+ */+ readonly skips: ReadonlyArray<CrossTopicSkip>;+}++/**+ * Plan the pass's cross-topic promotions. Deterministic in its inputs:+ * sources are walked in code-unit id order, edges in that order, roots+ * are the smallest member index, clusters are elected by their sorted+ * source-id join, and at most one cluster per owner token fires (the+ * daily budget, stamped into the returned ledger).+ *+ * Each elected cluster survives three gates in order: the daily budget+ * (a budgeted-out pass is a no-op), the content-slug check (the exact+ * source set promoted before, live or dead), and the duplicate-rule+ * guard (M8) - a near-identical principle, or a superset of a live+ * rule's evidence, skips the promotion with a disclosure instead of+ * minting a second live rule.+ */+export function planCrossTopicRules(input: CrossTopicPlannerInput): CrossTopicPlannerResult {+ const { scan, refresh, config, ledger, now, plan } = input;+ if (config === null) return { fired: false, ledger: null, skips: NO_SKIPS };+ const today = isoDate(now);++ const sources = collectSources(scan, refresh, plan);+ const clusters = electClusters(sources, config);+ const existingRules = collectExistingRules(scan, plan);+ const lastPromoted: Record<string, string> = { ...ledger?.last_promoted };+ let fired = false;+ const skips: CrossTopicSkip[] = [];++ for (const cluster of clusters) {+ const ownerKey = cluster.members[0]!.ownerKey;+ // The daily budget: one promotion per owner token per calendar+ // day, checked BEFORE anything else so a budgeted-out pass is a+ // no-op rather than a changed run that wrote nothing.+ if (lastPromoted[ownerKey] === today) continue;+ const normalizedIds = cluster.members.map((m) => m.normalizedId);+ const slug = `${CROSS_SLUG_PREFIX}${sha256Hex(normalizedIds.join(SLUG_ID_JOIN)).slice(0, 12)}`;+ if (slugTaken(slug, scan)) continue;+ const duplicate = findDuplicateRule(cluster, existingRules.get(ownerKey), config.jaccard);+ if (duplicate !== null) {+ // The dedup guard: membership churn mints a new content slug, so+ // the exact-set check above cannot catch a re-statement of a live+ // rule. Skip with a disclosure, and spend no budget - nothing was+ // promoted, so nothing is stamped into the ledger.+ skips.push(skipDuplicate(duplicate, config.jaccard));+ continue;+ }+ lastPromoted[ownerKey] = today;+ fired = true;+ const representative = cluster.members[0]!;+ plan.crossTopicRules.push(+ Object.freeze({+ slug,+ topic: [...new Set(cluster.members.map((m) => m.topic))].sort().join(TOPIC_JOIN),+ principle: representative.principle,+ evidencedBy: Object.freeze(normalizedIds.map((id) => `[[${id}]]`)),+ related: Object.freeze(normalizedIds),+ // The strictest visibility of the sources: the rule restates a+ // source's principle verbatim, so it may never be more public+ // than the most restricted member (the topic plan's own+ // strictestVisibilityOf rule; an intersection that misses falls+ // closed on the reserved token). Empty is default visibility.+ visibility: strictestVisibilityOf(cluster.members.map((m) => m.visibility)),+ ...(ownerKey ? { owner: ownerKey } : {}),+ }),+ );+ }++ return {+ fired,+ ledger: fired+ ? Object.freeze({+ version: CROSS_TOPIC_LEDGER_VERSION,+ last_promoted: Object.freeze(lastPromoted),+ })+ : null,+ skips: skips.length > 0 ? Object.freeze(skips) : NO_SKIPS,+ };+}++/**+ * The eligible source pool: confirmed preferences (at scan time or by+ * this run's refresh) that the pass is not retiring, projected and+ * sorted by raw id in code-unit order so every downstream choice is a+ * property of the corpus alone.+ *+ * A promoted cross-topic rule is NEVER a source. It restates its+ * representative source's principle verbatim (jaccard 1.0) and folds to+ * its own synthetic topic key, so once the refresh machinery confirms it+ * - one applied event does - an admitted rule would put every later pass+ * one `cross-` slug away from "discovering" a new cross-topic cluster+ * containing it and minting another promotion, one per owner per day+ * until the daily budget was the only thing left stopping it. Two+ * identifiers, because the artifact is user-editable: the reserved slug+ * prefix, and the `inferred` provenance every promoted rule carries+ * (which also keeps one inferred fact from citing another inferred fact+ * as its cross-topic evidence).+ *+ * The same two identifiers are what let {@link collectExistingRules}+ * find those records again as duplicate-rule guards: excluded from the+ * sources, admitted against them.+ */+function collectSources(scan: ScanResult, refresh: RefreshResult, plan: PlanState): Source[] {+ const retiring = new Set(plan.retires.map((r) => r.slug));+ const sources: Source[] = [];+ for (const record of scan.preferences) {+ const slug = preferenceSlug(record.pref.id);+ const confirmed =+ record.pref.status === BRAIN_PREFERENCE_STATUS.confirmed || refresh.confirmed.has(slug);+ if (!confirmed || retiring.has(slug)) continue;+ if (slug.startsWith(CROSS_SLUG_PREFIX) || record.pref.provenance === "inferred") continue;+ const owner = preferenceOwner(record.pref);+ sources.push({+ id: record.pref.id,+ slug,+ normalizedId: `pref-${slug}`,+ key: topicKey(record.pref.topic),+ topic: record.pref.topic,+ principle: record.pref.principle,+ tokens: tokenise(record.pref.principle),+ ownerKey: owner ?? "",+ visibility: record.visibility ?? [],+ });+ }+ sources.sort((a, b) => (a.id < b.id ? -1 : a.id > b.id ? 1 : 0));+ return sources;+}++interface Cluster {+ /** Members in code-unit id order (the source pool's order). */+ readonly members: Source[];+ /** Sorted-id join; the cluster's deterministic election key. */+ readonly idJoin: string;+}++/**+ * Union sources across bucket boundaries wherever their principles are+ * similar enough, then keep the components that span at least+ * `min_topics` distinct buckets and share one owner token, ordered by+ * their sorted source-id join.+ *+ * Same-bucket pairs never edge, so a bucket of mutual near-duplicates+ * is invisible here by construction - that is the merge machinery's+ * job, and it already has it.+ */+function electClusters(+ sources: ReadonlyArray<Source>,+ config: ResolvedCrossTopicConfig,+): Cluster[] {+ const parent = sources.map((_, i) => i);+ const find = (start: number): number => {+ let i = start;+ while (parent[i] !== i) {+ const grandparent = parent[parent[i]!]!;+ parent[i] = grandparent;+ i = grandparent;+ }+ return i;+ };+ for (let i = 0; i < sources.length; i++) {+ for (let j = i + 1; j < sources.length; j++) {+ const a = sources[i]!;+ const b = sources[j]!;+ if (a.key === b.key) continue;+ if (a.ownerKey !== b.ownerKey) continue;+ if (jaccard(a.tokens, b.tokens) < config.jaccard) continue;+ const ra = find(i);+ const rb = find(j);+ if (ra !== rb) parent[Math.max(ra, rb)] = Math.min(ra, rb);+ }+ }++ const byRoot = new Map<number, Source[]>();+ for (let i = 0; i < sources.length; i++) {+ const root = find(i);+ const members = byRoot.get(root) ?? [];+ members.push(sources[i]!);+ byRoot.set(root, members);+ }++ const clusters: Cluster[] = [];+ for (const members of byRoot.values()) {+ const keys = new Set(members.map((m) => m.key));+ if (keys.size < config.minTopics) continue;+ clusters.push({ members, idJoin: members.map((m) => m.normalizedId).join(SLUG_ID_JOIN) });+ }+ clusters.sort((a, b) => (a.idJoin < b.idJoin ? -1 : a.idJoin > b.idJoin ? 1 : 0));+ return clusters;+}++/** One live inferred cross-topic rule the duplicate guard compares against. */+interface ExistingCrossRule {+ /** The `pref-<slug>` id a disclosure names. */+ readonly id: string;+ readonly tokens: ReadonlySet<string>;+ /** The rule's evidenced_by wikilinks, normalized to source slugs. */+ readonly evidenceSlugs: ReadonlySet<string>;+}++/** The first live rule a cluster would duplicate, and which gate caught it. */+interface DuplicateHit {+ readonly rule: ExistingCrossRule;+ /** True when the principles matched at the floor; false means evidence. */+ readonly byPrinciple: boolean;+ /** The representative-vs-rule score, for the principle disclosure. */+ readonly score: number;+}++/**+ * The owner's live cross-topic rules, grouped by owner token, projected+ * from the very records the source pool excludes: a preference carrying+ * the reserved `cross-` slug prefix, or the `inferred` provenance every+ * promotion carries.+ *+ * An UNCONFIRMED rule guards too - the churn window this guard closes+ * sits exactly in the trial days before a promoted rule's first applied+ * evidence confirms it - but a rule this same pass plans to retire does+ * not, by the same discipline that keeps retiring sources ineligible:+ * replacing a rule the run is moving into `retired/` is how a+ * principle's evidence is allowed to grow.+ */+function collectExistingRules(scan: ScanResult, plan: PlanState): Map<string, ExistingCrossRule[]> {+ const retiring = new Set(plan.retires.map((r) => r.slug));+ const byOwner = new Map<string, ExistingCrossRule[]>();+ for (const record of scan.preferences) {+ const slug = preferenceSlug(record.pref.id);+ if (!slug.startsWith(CROSS_SLUG_PREFIX) && record.pref.provenance !== "inferred") continue;+ if (retiring.has(slug)) continue;+ const ownerKey = preferenceOwner(record.pref) ?? "";+ const rules = byOwner.get(ownerKey) ?? [];+ rules.push({+ id: `pref-${slug}`,+ tokens: tokenise(record.pref.principle),+ evidenceSlugs: new Set(+ record.pref.evidenced_by.map((link) => preferenceSlug(evidenceLinkId(link))),+ ),+ });+ byOwner.set(ownerKey, rules);+ }+ // Deterministic comparison order: the disclosure names the first+ // matching rule in code-unit id order, a property of the corpus alone.+ for (const rules of byOwner.values()) {+ rules.sort((a, b) => (a.id < b.id ? -1 : a.id > b.id ? 1 : 0));+ }+ return byOwner;+}++/** The pref id a `[[pref-...]]` evidence wikilink spells (alias-tolerant). */+function evidenceLinkId(link: string): string {+ return link.replace(/^\[\[/, "").replace(/\]\]$/, "").split("|")[0] ?? "";+}++/**+ * The first live rule this cluster would duplicate, or null. Either the+ * cluster's representative principle is near-identical to the rule's -+ * at the same jaccard floor the clusters themselves elect at, so an+ * operator who raised the knob raised it for both - or the cluster's+ * source set already superset-evidences the rule, which is membership+ * churn by another route: the sources are cited, only their membership+ * moved. Extending the existing rule's evidence is a future concern,+ * deliberately not planned here.+ */+function findDuplicateRule(+ cluster: Cluster,+ ownerRules: ReadonlyArray<ExistingCrossRule> | undefined,+ floor: number,+): DuplicateHit | null {+ if (!ownerRules) return null;+ const representative = cluster.members[0]!;+ const sourceSlugs = new Set(cluster.members.map((m) => m.slug));+ for (const rule of ownerRules) {+ const score = jaccard(representative.tokens, rule.tokens);+ if (score >= floor) {+ return { rule, byPrinciple: true, score };+ }+ // An empty evidence list never matches: the superset of nothing is+ // everything, and a hand-made inferred rule with no lineage must+ // not veto every cluster its owner ever elects.+ if (rule.evidenceSlugs.size === 0) continue;+ let covered = true;+ for (const slug of rule.evidenceSlugs) {+ if (!sourceSlugs.has(slug)) {+ covered = false;+ break;+ }+ }+ if (covered) return { rule, byPrinciple: false, score };+ }+ return null;+}++/** The disclosure for a declined promotion: the code, the rule, the reason. */+function skipDuplicate(hit: DuplicateHit, floor: number): CrossTopicSkip {+ const message = hit.byPrinciple+ ? `cross_topic: skipped a duplicate promotion; ${hit.rule.id} already carries this ` ++ `principle (jaccard ${hit.score.toFixed(2)} >= ${floor})`+ : `cross_topic: skipped a duplicate promotion; the cluster's sources already evidence ` ++ `${hit.rule.id}, and extending that rule's evidence is not planned here`;+ return Object.freeze({ code: CROSS_TOPIC_DUPLICATE_RULE_CODE, message });+}++/**+ * Whether the promoted file (or its tombstone) already exists. The+ * content-derived slug makes this exact: the same source set maps to+ * one slug forever, so a present id - live or retired - is proof the+ * cluster already promoted, and a rerun must plan nothing.+ *+ * A `pref-cross-*` path the scan could not parse into a record is just+ * as taken (finding 64): a tombstoned file keeps its bytes in place and+ * a corrupted one keeps its filename, and apply's `overwrite: false`+ * write would throw on either, blocking every later pass. The slug is+ * read off the filename, which is the only identity such a file still+ * carries.+ *+ * The corrupted check is directory-scoped (review round 2): `scan.corrupted`+ * also holds unparseable signal files (`inbox/`, `processed/`, `archived/`)+ * and retired files, none of which apply ever writes to. Only a file under+ * `Brain/preferences/` can occupy the exact path the `overwrite: false`+ * promotion targets, so the comparison considers that directory alone -+ * the scan's own preference records name it, every one of them having been+ * read from it. With no preference records nothing can fire anyway (no+ * sources, no clusters), so a null directory simply never matches.+ */+function slugTaken(slug: string, scan: ScanResult): boolean {+ const preferencesDir = scan.preferences.length > 0 ? dirname(scan.preferences[0]!.path) : null;+ for (const p of scan.preferences) {+ if (preferenceSlug(p.pref.id) === slug) return true;+ }+ for (const r of scan.retired) {+ const retiredSlug = r.id.startsWith(RETIRED_ID_PREFIX)+ ? r.id.slice(RETIRED_ID_PREFIX.length)+ : r.id;+ if (retiredSlug === slug) return true;+ }+ for (const t of scan.tombstonedPreferences ?? []) {+ if (unparsedSlug(t.path) === slug) return true;+ }+ for (const c of scan.corrupted) {+ if (preferencesDir === null || dirname(c.path) !== preferencesDir) continue;+ if (unparsedSlug(c.path) === slug) return true;+ }+ return false;+}++/** The slug a skipped preference file still carries in its basename. */+function unparsedSlug(path: string): string {+ return preferenceSlug(basename(path).replace(/\.md$/, ""));+}diff --git a/src/core/brain/dream-plan.ts b/src/core/brain/dream-plan.tsindex a1026863..9f35f830 100644--- a/src/core/brain/dream-plan.ts+++ b/src/core/brain/dream-plan.ts@@ -164,6 +164,16 @@ export interface ScanResult {readonly preferences: PreferenceRecord[];readonly retired: RetiredRecord[];readonly corrupted: CorruptedEntry[];+ /**+ * Preferences the scan skipped because a tombstone marks them+ * (`_status: tombstoned`, Belief lifecycle suite t_7d5a3589). The pass+ * never plans over them, but the path-only entries still matter to the+ * cross-topic slug check (finding 64): a tombstoned `pref-cross-*` file+ * holds the exact path a re-promotion would write, and `overwrite:+ * false` must never find that path occupied by surprise. Absent on a+ * scan built by hand.+ */+ readonly tombstonedPreferences?: ReadonlyArray<CorruptedEntry>;/*** Every entry name in `inbox/archived/`, parseable or not. The archive* step checks a move's destination name against this listing rather than@@ -239,6 +249,14 @@ export interface PlanState {* overlaps {@link signalsToMove}.*/readonly signalsToArchive: Map<string, SignalArchivePlan>;+ /**+ * Cross-topic rule promotions (t_642bc2b8): one new unconfirmed+ * preference per elected cross-bucket cluster, at most one per owner+ * token per calendar day. Planned by `dream-plan-cross-topic.ts`+ * after the refresh pass (it needs post-refresh confirmation state);+ * every write happens in the apply stage like every other entry.+ */+ readonly crossTopicRules: CrossTopicRulePlan[];}export interface SignalArchivePlan {@@ -255,6 +273,56 @@ export interface SignalSuppressedPlan {readonly topic: string;}+/**+ * One planned cross-topic rule promotion (t_642bc2b8).+ *+ * The promoted artifact is an ordinary unconfirmed preference whose+ * evidence is the set of per-topic rules it generalises, so nothing in+ * the persistence format is new. What the planner decides:+ *+ * - `slug` is content-derived (`cross-<sha256-12>` over the sorted+ * source ids), so the same source set always maps to one file and a+ * rerun dedups itself below the changed gate.+ * - `topic` is the deterministic join of the sorted raw topic+ * displays - a key no signal will ever carry, which is exactly why+ * the rule cannot re-enter the per-topic "one preference per topic"+ * world. Topic-keyed recall will not surface it; the `related`+ * lineage and `evidenced_by` wikilinks are the way back.+ * - `principle` is one source's principle verbatim (the+ * lexicographically smallest source's) - the kernel stays LLM-free+ * and the rule says exactly what its sources say. The cross-topic+ * fact lives in the evidence, not in invented prose.+ * - `owner` carries the sources' shared owner token when they have+ * one, so owner-scoped recall keeps the rule as private as its+ * sources; ownerless sources produce an ownerless rule.+ * - `visibility` is the strictest of the sources' `visibility:` token+ * sets (`strictestVisibilityOf`, the topic plan's own rule): the+ * rule restates a source's principle verbatim, so it may never be+ * more public than the most restricted member. An intersection that+ * misses falls closed on the reserved token. Empty means default+ * visibility, and the writer omits the field then.+ */+export interface CrossTopicRulePlan {+ /** `cross-<sha256-12>`; the file basename without the `pref-` prefix. */+ readonly slug: string;+ /** Deterministic join of the sorted source topic displays. */+ readonly topic: string;+ /** One source's principle, verbatim. */+ readonly principle: string;+ /** `[[pref-<slug>]]` wikilinks to every source, in code-unit order. */+ readonly evidencedBy: ReadonlyArray<string>;+ /** The source preference ids (`pref-<slug>`), in code-unit order. */+ readonly related: ReadonlyArray<string>;+ /**+ * The strictest `visibility:` tokens of the cluster members. Written+ * to the promoted rule's frontmatter when non-empty; empty is default+ * visibility.+ */+ readonly visibility: ReadonlyArray<string>;+ /** The sources' shared owner token; absent for ownerless sources. */+ readonly owner?: string;+}+export interface NewUnconfirmedPlan {readonly slug: string;readonly topic: string;@@ -335,6 +403,7 @@ export function emptyPlan(): PlanState {quarantined: [],topicKeyContentions: [],signalsToArchive: new Map(),+ crossTopicRules: [],};}diff --git a/src/core/brain/dream-refresh.ts b/src/core/brain/dream-refresh.tsindex d8a4acc8..6d5eb135 100644--- a/src/core/brain/dream-refresh.ts+++ b/src/core/brain/dream-refresh.ts@@ -23,6 +23,7 @@ import {BRAIN_RETIRED_REASON,type BrainConfidence,type BrainConfig,+ type BrainPreference,} from "./types.ts";export interface RefreshUpdate {@@ -51,6 +52,30 @@ export interface RefreshUpdate {* legacy vaults keep their no-op dream guarantees.*/readonly freshness_trend?: string;+ /**+ * Derived-fact fields (finding 77), carried for the same reason the+ * pre-flight carries them: the renderer emits a non-default+ * `provenance` and a non-empty `related` only when the write input+ * supplies them, so an update loop that omitted them would strip both+ * from a promoted rule on its first counter change - and, because the+ * no-op pre-flight renders from the input too, leave the file looking+ * "needs rewrite" on every pass after that. Absent stays absent: a+ * pref without these fields is written exactly as before.+ */+ readonly provenance?: BrainPreference["provenance"];+ readonly related?: ReadonlyArray<string>;+ /**+ * The record's `visibility:` tokens, carried for the same reason the+ * derived-fact fields are (finding 77; review round 2): the renderer+ * emits a `visibility:` line only when the write input supplies it,+ * and `wouldRewritePreference` builds its output from the input alone+ * - it does not run the tiered merge that keeps the file's existing+ * line - so an update that omitted the tokens would leave every pref+ * carrying `visibility:` on disk looking "needs rewrite" on every+ * pass, each rewrite a real `_revision` bump. Absent stays absent: a+ * pref without the field is written exactly as before.+ */+ readonly visibility?: ReadonlyArray<string>;}/**@@ -373,6 +398,29 @@ export function planRefresh(confidence_value: confidence.value,pinned: rec.pref.pinned,...(trendLabel !== undefined ? { freshness_trend: trendLabel } : {}),+ // Carrying the derived-fact fields through the no-op pre-flight.+ // The renderer emits a non-default `provenance` and a non-empty+ // `related`, so a render that omitted them could never match a+ // preference that carries them (`deriveFact` output, the dream+ // pass's own cross-topic promotions): every pass would see the+ // file as "needs rewrite", and the txn's `_revision` auto-stamp+ // would then make each rewrite real, flipping every rerun into a+ // changed run forever. Absent stays absent, so prefs without+ // these fields render exactly the bytes they always did.+ ...(rec.pref.provenance !== undefined && rec.pref.provenance !== "stated"+ ? { provenance: rec.pref.provenance }+ : {}),+ ...(rec.pref.related !== undefined && rec.pref.related.length > 0+ ? { related: rec.pref.related }+ : {}),+ // The record's `visibility:` tokens ride along like provenance and+ // related above: the scan reads them off the raw frontmatter (the+ // typed parser drops the field), and only a render that includes+ // them can match a file that carries the line. Empty is default+ // visibility and stays absent, exactly like the writer's own rule.+ ...(rec.visibility !== undefined && rec.visibility.length > 0+ ? { visibility: rec.visibility }+ : {}),};if (!countersChanged) {diff --git a/src/core/brain/dream-report.ts b/src/core/brain/dream-report.tsindex e6e5d303..8104c628 100644--- a/src/core/brain/dream-report.ts+++ b/src/core/brain/dream-report.ts@@ -13,6 +13,7 @@*/import { preferenceSlug, type PlanState, type ScanResult } from "./dream-plan.ts";+import { writeCrossTopicLedger, type CrossTopicLedger } from "./dream-plan-cross-topic.ts";import type { RefreshResult } from "./dream-refresh.ts";import { WORKRUN_PHASE, type WorkrunHandle } from "./dream-workrun.ts";import { appendLogEvent } from "./log.ts";@@ -38,6 +39,13 @@ export interface DreamReportInput {readonly refresh: RefreshResult;readonly reconcile: ReconcileOutcomes;readonly rollupPlan: RollupLadderPlan;+ /**+ * The updated cross-topic daily budget (t_642bc2b8) to persist when a+ * promotion fired this run; null when none did, so a below-threshold+ * or budgeted-out run never touches the ledger - the same+ * byte-identical opt-out the rollup ledger uses.+ */+ readonly crossTopicLedger: CrossTopicLedger | null;/** Signal ids that actually reached `processed/`. */readonly moved: ReadonlyArray<string>;/** Signal ids moved into `inbox/archived/` by this run. */@@ -159,6 +167,12 @@ export function writeDreamLog(input: DreamReportInput): void {// fired. A below-threshold run never touches the ledger, so its// absence is the byte-identical opt-out.if (input.rollupPlan.fired) writeRollupLedger(vault, input.rollupPlan.ledger);++ // Cross-topic promotion (t_642bc2b8): persist the advanced per-owner+ // daily budget beside the rollup ledger, under the same discipline -+ // written only when a promotion actually fired, through the shared+ // atomic writer.+ if (input.crossTopicLedger) writeCrossTopicLedger(vault, input.crossTopicLedger);}/**@@ -253,5 +267,15 @@ function buildSummaryBody(input: DreamReportInput): Record<string, string | Read(e) => `${e.tier} -> ${e.produces} (${e.fromCount} -> ${e.toCount})`,);}+ // Cross-topic promotion (t_642bc2b8): each promoted rule rendered+ // like a new unconfirmed pref, with its source lineage after an arrow+ // so the audit trail shows what the rule generalises without opening+ // a single source file. Absent when nothing fired.+ if (plan.crossTopicRules.length > 0) {+ body["cross_topic_rules"] = plan.crossTopicRules.map(+ (r) =>+ `${renderPrefLink({ id: `pref-${r.slug}`, principle: r.principle })} ← ${r.related.join(", ")}`,+ );+ }return body;}diff --git a/src/core/brain/dream-scan.ts b/src/core/brain/dream-scan.tsindex 328b143d..0e878028 100644--- a/src/core/brain/dream-scan.ts+++ b/src/core/brain/dream-scan.ts@@ -150,11 +150,19 @@ function collectPreferences(preferences: PreferenceRecord[],corrupted: CorruptedEntry[],walk: DirectoryWalk,+ tombstoned: CorruptedEntry[],): void {for (const full of files) {walk.step();const rawMeta = parseFrontmatter(full)[0];- if (isTombstoned(rawMeta)) continue;+ // The tombstoned file stays on disk for audit; the pass never plans+ // over it, but its path is still recorded (finding 64): the cross-+ // topic slug check must see a `pref-cross-*` filename it would+ // otherwise re-plan and collide with under `overwrite: false`.+ if (isTombstoned(rawMeta)) {+ tombstoned.push({ path: full });+ continue;+ }// Belief lifecycle suite (A4): capture the raw superseded_by pointer// (the typed parser drops it) so accelerated chain decay can see a// temporally-superseded ancestor.@@ -278,6 +286,7 @@ function scanBrainRun(const preferences: PreferenceRecord[] = [];const retired: RetiredRecord[] = [];const corrupted: CorruptedEntry[] = [];+ const tombstonedPreferences: CorruptedEntry[] = [];// One boundary for all four collectors: the per-file read is where the// work is, so it is where the deadline is honoured and where a reader// learns the scan is still moving. Collapsed into one object because@@ -300,7 +309,7 @@ function scanBrainRun(() => collectSignals(inbox, true, signals, corrupted, walk),() => collectSignals(processed, false, signals, corrupted, walk),() => collectSignals(archived, false, signals, corrupted, walk, true),- () => collectPreferences(preferenceFiles, preferences, corrupted, walk),+ () => collectPreferences(preferenceFiles, preferences, corrupted, walk, tombstonedPreferences),() => collectRetired(vault, retiredFiles, retired, corrupted, walk),];for (const collect of collectors) {@@ -308,7 +317,14 @@ function scanBrainRun(collect();}- return { signals, preferences, retired, corrupted, archivedNames: entryNamesIn(dirs.archived) };+ return {+ signals,+ preferences,+ retired,+ corrupted,+ tombstonedPreferences,+ archivedNames: entryNamesIn(dirs.archived),+ };}/** Every entry name directly inside `dir`, or none when it does not exist. */diff --git a/src/core/brain/dream-stage.ts b/src/core/brain/dream-stage.tsindex cc70878c..3693bfb5 100644--- a/src/core/brain/dream-stage.ts+++ b/src/core/brain/dream-stage.ts@@ -72,6 +72,15 @@ export interface DreamStagePlan {* grows with the clock alone (see `HOUSEKEEPING_PLAN_KEYS`).*/readonly archived_signals?: ReadonlyArray<string>;+ /**+ * Cross-topic rule promotions (t_642bc2b8) the pass would create - the+ * `pref-*` ids, like `new_unconfirmed` but for the planner's own+ * separate list. Absent when empty (finding 65), so every projection+ * before the feature - and every pass that promotes nothing - keeps+ * its exact shape, and the drift comparison sees a changed promotion+ * as the ordinary key drift it is.+ */+ readonly cross_topic_rules?: ReadonlyArray<string>;readonly suppressed: ReadonlyArray<string>;readonly quarantined: ReadonlyArray<{ topic: string; failed_gates: ReadonlyArray<string> }>;readonly gated_retires: ReadonlyArray<{ pref_id: string; attempted_reason: string }>;@@ -182,6 +191,9 @@ export function projectDreamPlan(summary: DreamRunSummary): DreamStagePlan {...(summary.archived_signals !== undefined && summary.archived_signals.length > 0? { archived_signals: Object.freeze([...summary.archived_signals].toSorted()) }: {}),+ ...(summary.cross_topic_rules !== undefined && summary.cross_topic_rules.length > 0+ ? { cross_topic_rules: Object.freeze([...summary.cross_topic_rules].toSorted()) }+ : {}),suppressed: Object.freeze([...summary.suppressed].toSorted()),quarantined: Object.freeze(sorted(@@ -245,6 +257,10 @@ function scanSources(vault: string): DreamStageSource[] {function planToProposals(plan: DreamStagePlan): Array<Record<string, unknown>> {const rows: Array<Record<string, unknown>> = [];for (const id of plan.new_unconfirmed) rows.push({ type: "create_preference", id });+ // A cross-topic promotion is a new unconfirmed preference file like any+ // other; apply writes it through the same transactional writer, so its+ // proposal row is the same shape (finding 65).+ for (const id of plan.cross_topic_rules ?? []) rows.push({ type: "create_preference", id });for (const id of plan.confirmed) rows.push({ type: "confirm_preference", id });for (const r of plan.retired)rows.push({ type: "retire_preference", id: r.id, reason: r.reason });@@ -288,6 +304,7 @@ function renderReport(]),"",...section("Would create (unconfirmed)", plan.new_unconfirmed),+ ...section("Would create (cross-topic rules)", plan.cross_topic_rules ?? []),...section("Would confirm", plan.confirmed),...section("Would retire",diff --git a/src/core/brain/dream-summary.ts b/src/core/brain/dream-summary.tsindex 393b3c31..eb9ecefb 100644--- a/src/core/brain/dream-summary.ts+++ b/src/core/brain/dream-summary.ts@@ -123,6 +123,13 @@ export function buildChangedSummary(input: DreamChangedSummaryInput): DreamRunSu// Absent rather than empty, so a run that archived nothing keeps the// summary shape it has always had....(input.archived.length > 0 ? { archived_signals: input.archived } : {}),+ // Cross-topic rule promotions (t_642bc2b8). Absent rather than+ // empty for the same reason: a pass that promoted nothing - every+ // un-opted-in pass among them - keeps the summary bytes it always+ // had.+ ...(plan.crossTopicRules.length > 0+ ? { cross_topic_rules: plan.crossTopicRules.map((r) => `pref-${r.slug}`) }+ : {}),suppressed: plan.signalsSuppressed.map((s) =>s.signal.replace(/^\[\[/, "").replace(/\]\]$/, ""),),@@ -158,6 +165,7 @@ function buildPhaseSummaries(input: DreamChangedSummaryInput): ReadonlyArray<DrephaseSummary(DREAM_PHASE.synthesize, {new_unconfirmed: plan.newUnconfirmed.length,confirmed: refresh.confirmed.size,+ cross_topic_rules: plan.crossTopicRules.length,}),phaseSummary(DREAM_PHASE.heal, {retired: plan.retires.filter((r) => !gatedSlugs.has(r.slug)).length,diff --git a/src/core/brain/dream-types.ts b/src/core/brain/dream-types.tsindex 3e71542d..5432b4d1 100644--- a/src/core/brain/dream-types.ts+++ b/src/core/brain/dream-types.ts@@ -87,6 +87,14 @@ export interface DreamRunSummary {* the pass archived nothing.*/readonly archived_signals?: ReadonlyArray<string>;+ /**+ * Cross-topic rule promotions (t_642bc2b8): the ids of the new+ * unconfirmed rules this pass promoted over a recurring cross-bucket+ * cluster of confirmed preferences. Absent when the pass promoted+ * nothing - every pass of an un-opted-in vault among them - so the+ * summary stays byte-identical there.+ */+ readonly cross_topic_rules?: ReadonlyArray<string>;/*** Signal ids dropped by §6 signal-suppression — a user-rejected* retired pref with the same topic blocked them from re-promotion.diff --git a/src/core/brain/dream.ts b/src/core/brain/dream.tsindex d85a6db0..c7c919a0 100644--- a/src/core/brain/dream.ts+++ b/src/core/brain/dream.ts@@ -66,6 +66,11 @@ import { resolveNearDuplicateRetireSiblingsEnabled } from "../config.ts";import { planAutoRetires } from "./dream-plan-retires.ts";import { planTopics, topicKeyContentionWarnings } from "./dream-plan-topics.ts";import type { PlanState, ScanResult } from "./dream-plan.ts";+import {+ planCrossTopicRules,+ readCrossTopicLedger,+ resolveCrossTopicConfig,+} from "./dream-plan-cross-topic.ts";import { planRefresh, scanApplyEvidence, type RefreshResult } from "./dream-refresh.ts";import { writeDreamLog } from "./dream-report.ts";import { scanBrain } from "./dream-scan.ts";@@ -191,6 +196,7 @@ function scanAsAdmitted(preferences: scan.preferences.filter((r) => keep(r.path)),retired: scan.retired.filter((r) => keep(r.path)),corrupted: scan.corrupted.filter((r) => keep(r.path)),+ tombstonedPreferences: scan.tombstonedPreferences?.filter((r) => keep(r.path)),};}@@ -306,6 +312,30 @@ function dreamRun(// retire.planAutoRetires(scan, cfg, now, plan, refresh);+ // 4b. Cross-topic rule promotion (t_642bc2b8). Planned after the+ // refresh pass - the source pool reads post-refresh confirmation+ // state - and after the retire plan, so a preference this pass is+ // about to retire is never cited as evidence. Before the `changed`+ // gate, so a fired promotion counts as a state change and a+ // below-threshold or budgeted-out pass stays byte-identical; the+ // rollup ladder is the structural precedent (plan before the+ // gate, persist the ledger only when fired). The ledger read is+ // skipped entirely when the feature is off: an un-opted-in vault+ // pays no I/O here. The disclosure sink is the run's warning list:+ // a declared knob the resolver floored (finding 62) is named on+ // the summary, never applied silently.+ const crossTopicConfig = resolveCrossTopicConfig(cfg, (code, message) =>+ warnings.push({ code, message }),+ );+ const crossTopic = planCrossTopicRules({+ scan,+ refresh,+ config: crossTopicConfig,+ ledger: crossTopicConfig ? readCrossTopicLedger(vault) : null,+ now,+ plan,+ });+// 5. §7.3 step "move consumed signals out of inbox/" needs no pass of// its own: both routes that consume a signal - the topic loop and// the active-pref handler - already enqueued it into@@ -476,6 +506,7 @@ function dreamRun(refresh,reconcile,rollupPlan,+ crossTopicLedger: crossTopic.ledger,moved: exec.moved,archived: exec.archived,gatedSlugs,@@ -624,6 +655,7 @@ function collectWarnings(* - a corrupted frontmatter (we want the skip event recorded)* - any pinned-rebut-attempt warning* - a fired rollup-ladder rung (S3)+ * - a cross-topic rule promotion (t_642bc2b8)*/function hasStateChange(plan: PlanState,@@ -645,6 +677,7 @@ function hasStateChange(// so a run that produces only quarantine entries is still a// meaningful run from the operator's perspective.plan.quarantined.length > 0 ||+ plan.crossTopicRules.length > 0 ||rollupPlan.fired ||corruptedCount > 0);diff --git a/src/core/brain/link-graph/bridge-discovery.ts b/src/core/brain/link-graph/bridge-discovery.tsindex 3d229062..baa97052 100644--- a/src/core/brain/link-graph/bridge-discovery.ts+++ b/src/core/brain/link-graph/bridge-discovery.ts@@ -21,13 +21,15 @@*/import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";-import { basename, dirname, join } from "node:path";+import { basename, dirname, join, relative } from "node:path";import type { Store } from "../../search/store.ts";import { linkConstraintAllows } from "../../search/link-constraints.ts";import { normalizeRelationTarget } from "../../graph/frontmatter-relations.ts";import { atomicWriteFileSync } from "../../fs-atomic.ts";+import { toPosix } from "../../path-safety.ts";import { isoSecond } from "../time.ts";+import { matchScope, resolveVaultScope } from "../../vault-scope/index.ts";import {formatFrontmatter,listVaultPages,@@ -326,7 +328,7 @@ export function acceptBridge(const [meta, body] = parseFrontmatter(sourceAbs);const targetBase = noteId(target);const targetFull = target.replace(/\.md$/u, "");- const ambiguous = countBasenameMatches(vault, targetBase) > 1;+ const ambiguous = countBasenameMatches(vault, targetBase, target) > 1;const link = `[[${ambiguous ? targetFull : targetBase}]]`;const current = meta["related"];@@ -369,15 +371,53 @@ export function acceptBridge(/*** Number of vault pages sharing one basename (without `.md`).*- * The walk has no skip list, so it reaches `Brain/entities/` like any other- * subtree. A quarantined entity page must not make an operator's link- * target read as ambiguous, so it is not counted.+ * The page at `target` - the one the caller explicitly named and+ * `acceptBridge` has already validated to exist - is always counted.+ * The two rules below filter only the OTHER namesakes:+ *+ * - Entity status: a quarantined entity page is not counted (the walk+ * has no skip list, so it reaches `Brain/entities/` like any other+ * subtree).+ * - Vault scope (t_fd842db0): a page outside the operator's scope -+ * an `ignore_paths` entry, outside the `include_paths` allowlist, or+ * under a frozen default ignore - is not part of the vault by+ * definition (`vault-scope`'s own reading), so it can no more anchor+ * a wikilink than a missing file would. This is the same rule set+ * the scope-aware lint and resolution surfaces resolve by+ * (`page-dedup`'s basename census, the note-title resolver); the+ * narrow walk below stays untouched because its population feeds a+ * dozen unrelated products.+ *+ * Skipping the target itself would let an in-scope twin answer the+ * census alone: an out-of-scope target with a twin would then be+ * spelled `[[basename]]`, and the wikilink would resolve to the twin.+ *+ * The census decides the SPELLING only: `acceptBridge` validates+ * existence, not scope, so a caller who explicitly names an+ * out-of-scope target still gets it accepted - that edge predates the+ * scope filter and is unchanged by it.*/-function countBasenameMatches(vault: string, base: string): number {+function countBasenameMatches(vault: string, base: string, target: string): number {+ // Resolved once, above the loop: one existsSync + YAML load per+ // accept, which is per operator action.+ const rules = resolveVaultScope(vault).rules;+ const targetRel = toPosix(target);let count = 0;for (const page of listVaultPages(vault, { reach: MAINTENANCE_LANE_REACH })) {+ if (basename(page.path, ".md") !== base) continue;+ // The scope predicate needs the vault-relative POSIX path: a raw+ // host path would silently never match a path rule.+ const pageRel = toPosix(relative(vault, page.path));+ // The named target counts itself, before any scope skip: its+ // existence is already validated, and only the OTHER candidates+ // are subject to the filters below.+ if (pageRel === targetRel) {+ count++;+ continue;+ }if (!vaultPageInStatusScope(page.metadata, ENTITY_STATUS_SCOPE.readable)) continue;- if (basename(page.path, ".md") === base) count++;+ if (!matchScope(pageRel, rules).inScope) continue;+ count++;}return count;}diff --git a/src/core/brain/model-window.ts b/src/core/brain/model-window.tsnew file mode 100644index 00000000..2291db5c--- /dev/null+++ b/src/core/brain/model-window.ts@@ -0,0 +1,278 @@+/**+ * The shared model-aware context-window resolver (t_a567cc12).+ *+ * Every context-pack, preset and compact budget in the repo used to be a+ * caller-declared guess; this module is the one place that turns a host+ * model id plus the operator's declarations into a window number, and it+ * states for each answer WHAT decided (`source`) so surfaces can disclose+ * it. Two inference tiers, with the embeddings-preset philosophy applied+ * verbatim: a window is a number that differs between checkpoints of one+ * family, so only PUBLISHED declarations may produce one.+ *+ * - Declared: an exact-id table entry (provenance noted per row). No+ * family substring ever resolves - "sonnet" matches nothing, and that+ * is the defect this module exists to remove. Host-side decorations+ * that still name exactly one row normalize away first (provider and+ * region prefixes like `openai/` and `us.anthropic.`, trailing date+ * snapshots, `-vN:N` revision suffixes), so `openai/gpt-4.1` and+ * `gpt-4.1-2025-04-14` reach the row; nothing else is ever widened+ * into a hit.+ * - Structural: a trailing, delimited `1m` suffix (`-1m` / `_1m`, or+ * the trailing `[1m]` bracket form hosts report). The suffix is+ * itself a published declaration, so reading it is safe;+ * generalizing it to "the family is big" is not, and never happens+ * here. Delimited means `-` or `_` (or the whole id): a dot-led+ * version fragment like the `4.1m` in `gpt-4.1m` is a version, not a+ * window.+ *+ * Everything else resolves to {@link DEFAULT_MODEL_CONTEXT_WINDOW_TOKENS},+ * the figure `token-footprint.ts` already treats as the de-facto standard+ * window - an unknown model is a default, never a guess from its name.+ *+ * Operator channels win over published facts (the operator knows the+ * deployment; the table knows the brochure), and a first-hand declaration+ * - operator config, operator env, an exact table row - passes through+ * EXACTLY as given. The declaration exists to keep budgets inside the+ * true window; clamping it would re-inflate a declared 8k local model to+ * a 100k window and long-context budgets that overflow the very model it+ * describes. The `[MIN_MODEL_CONTEXT_WINDOW_TOKENS,+ * MAX_MODEL_CONTEXT_WINDOW_TOKENS]` band governs the GUESSED answers+ * only - the `-1m` suffix expansion and the unknown-model default, where+ * the true window is unknown and the band is the sanity bound. Both+ * published figures sit inside the band today, so `clamped` is false on+ * every derivable answer; a table row outside the band is a table bug+ * the unit test catches.+ *+ * PURE by contract: no fs, no environment reads, no network, no+ * `loadBrainConfig`. The caller parses its own channels (the+ * `context.window_tokens` block, {@link MODEL_CONTEXT_WINDOW_ENV_KEY} via+ * `resolveModelContextWindowEnvTokens()`, the per-call model string) and+ * hands the parsed values in, which keeps this module testable and lets+ * MCP, CLI and hook callers thread their own config channels.+ */++import { CONTEXT_WINDOW_TOKENS_DEFAULT } from "./policy/blocks/context.ts";++/** One published model window. Exact ids only; see the module header. */+export interface ModelContextWindowEntry {+ /** Exact host model id, matched case-insensitively after trimming. */+ readonly model: string;+ /** The window the vendor publishes for exactly this id, in tokens. */+ readonly windowTokens: number;+ /** One-line provenance ("model card: ...") for the published figure. */+ readonly note: string;+}++/**+ * Exact-id table. Deliberately small: the structural `1m` suffix rule+ * carries most of the value, and an entry is a published fact this repo+ * now asserts, so rows are added only for ids whose window the vendor+ * states as a plain number. Ids whose published window differs by+ * configuration or beta flag stay out.+ */+export const MODEL_CONTEXT_WINDOWS: ReadonlyArray<ModelContextWindowEntry> = Object.freeze([+ {+ model: "gpt-4o",+ windowTokens: 128_000,+ note: "OpenAI model card: 128,000 token context window",+ },+ {+ model: "gpt-4.1",+ windowTokens: 1_000_000,+ note: "OpenAI announcement: 1,000,000 token context window",+ },+ {+ model: "gpt-4.1-mini",+ windowTokens: 1_000_000,+ note: "OpenAI announcement: 1,000,000 token context window",+ },+ {+ model: "gpt-4.1-nano",+ windowTokens: 1_000_000,+ note: "OpenAI announcement: 1,000,000 token context window",+ },+ {+ model: "claude-sonnet-4-5",+ windowTokens: 200_000,+ note: "Anthropic models overview: 200K context window",+ },+ {+ model: "claude-opus-4-1",+ windowTokens: 200_000,+ note: "Anthropic models overview: 200K context window",+ },+ {+ model: "claude-opus-4",+ windowTokens: 200_000,+ note: "Anthropic models overview: 200K context window",+ },+]);++/** The window nothing better resolves to; see the module header. */+export const DEFAULT_MODEL_CONTEXT_WINDOW_TOKENS = CONTEXT_WINDOW_TOKENS_DEFAULT;+/** Band floor for the GUESSED answers (suffix expansion, default); see the module header. */+export const MIN_MODEL_CONTEXT_WINDOW_TOKENS = 100_000;+/**+ * Band ceiling for the GUESSED answers; the `1m` suffix resolves to+ * exactly this edge. First-hand declarations are never held to it.+ */+export const MAX_MODEL_CONTEXT_WINDOW_TOKENS = 1_000_000;++/** The `_brain.yaml` key the operator's `context:` block spells the window with. */+export const MODEL_CONTEXT_WINDOW_CONFIG_KEY = "window_tokens";+/**+ * The environment channel for the operator's window. The vault+ * declaration WINS over it - the resolver's precedence is operator+ * config > operator env > declared table > `1m` suffix > default - so a+ * value here answers only where no `context.window_tokens` is set.+ */+export const MODEL_CONTEXT_WINDOW_ENV_KEY = "OPEN_SECOND_BRAIN_MODEL_CONTEXT_WINDOW";++/** What decided the resolved window; surfaces disclose this verbatim. */+export type ModelWindowSource =+ | "operator-config"+ | "operator-env"+ | "declared"+ | "suffix"+ | "default";++export interface ResolvedModelWindow {+ readonly windowTokens: number;+ readonly source: ModelWindowSource;+ /** True when a GUESSED answer was clamped into the band; see the module header. */+ readonly clamped: boolean;+}++export interface ResolveModelContextWindowInput {+ /** The host model id, as free-form as the caller received it. */+ readonly model?: string | null;+ /** Parsed `context.window_tokens`; `null`/`undefined` when absent. */+ readonly operatorWindowTokens?: number | null;+ /** Parsed {@link MODEL_CONTEXT_WINDOW_ENV_KEY} value; absent when unset. */+ readonly envWindowTokens?: number | null;+}++/**+ * The declared-window lookup: the id is normalized first - host-side+ * decorations that still name one published model (provider and region+ * prefixes, trailing date snapshots, `-vN:N` revision suffixes; see+ * {@link normalizeDeclaredModelId}) are stripped - then matched+ * case-insensitively against the exact rows. `null` means UNKNOWN and is+ * never treated as any default's synonym - the resolver applies the+ * default one tier later, where `source` can say so.+ */+export function declaredModelContextWindowTokens(model: string | null | undefined): number | null {+ const id = normalizeDeclaredModelId(model?.trim().toLowerCase() ?? "");+ if (id === "") return null;+ const hit = MODEL_CONTEXT_WINDOWS.find((entry) => entry.model.toLowerCase() === id);+ return hit ? hit.windowTokens : null;+}++/**+ * The structural tier: one million tokens, and only when the id carries a+ * trailing, delimited `1m` window suffix - `-1m` / `_1m` (or the whole+ * id), or the trailing `[1m]` bracket form hosts report+ * (`claude-sonnet-5-5[1m]`). See the module header for the delimiter set+ * and the near-misses it exists to refuse.+ */+export function structuralModelContextWindowTokens(+ model: string | null | undefined,+): number | null {+ const id = model?.trim().toLowerCase() ?? "";+ if (/(^|[-_])1m$/.test(id) || id.endsWith("[1m]")) return MAX_MODEL_CONTEXT_WINDOW_TOKENS;+ return null;+}++/** The remainder of a prefix strip still has to look like a model id. */+function looksLikeModelId(candidate: string): boolean {+ return /^[a-z]/.test(candidate) && candidate.replace(/[^a-z]/g, "").length >= 3;+}++/**+ * Strip the deployment plumbing an id can carry and still name exactly+ * one published model, so host-side spellings reach the exact-id table:+ * provider/router prefixes (`openai/gpt-4.1`), Bedrock-style region+ * prefixes (`us.anthropic.claude-...`), trailing date snapshots+ * (`gpt-4.1-2025-04-14`, the compact `-20250929`) and `-vN:N` revision+ * suffixes. A prefix is stripped only up to the first `.` or `/` AND+ * only while the remainder still looks like a model id, so the dot-led+ * minor version in `gpt-4.1` survives whole. Normalization feeds the+ * TABLE lookup only - it never invents a row, and unknown ids stay+ * unknown through it.+ */+function normalizeDeclaredModelId(rawId: string): string {+ let id = rawId;+ // Prefixes: repeatedly cut at the first `/` or `.`, whichever comes+ // first, while the remainder stays id-shaped -+ // `bedrock/us.anthropic.claude-...` sheds all three.+ for (;;) {+ const slash = id.indexOf("/");+ const dot = id.indexOf(".");+ const cut = slash === -1 ? dot : dot === -1 ? slash : Math.min(slash, dot);+ if (cut === -1) break;+ const rest = id.slice(cut + 1);+ if (!looksLikeModelId(rest)) break;+ id = rest;+ }+ // The decorated tail: `-vN:N` revision suffixes and date snapshots,+ // dotted and compact, each repeatedly so `...-20250929-v1:0` sheds+ // its whole tail.+ for (;;) {+ const stripped = id+ .replace(/-v\d+(:\d+)?$/, "")+ .replace(/-\d{4}-\d{2}-\d{2}$/, "")+ .replace(/-\d{8}$/, "");+ if (stripped === id) break;+ id = stripped;+ }+ return id;+}++/** A channel value is usable only when it is a positive finite number. */+function usableChannelValue(value: number | null | undefined): value is number {+ return typeof value === "number" && Number.isFinite(value) && value > 0;+}++/**+ * Clamp a GUESSED window into the band. First-hand declarations never+ * pass through here - they are the operator's or the vendor's own+ * number, and the declaration exists precisely to state the true window.+ * Both derived figures (the `1m` suffix expansion, the unknown-model+ * default) sit inside the band today, so this is a no-op invariant that+ * keeps a future constant edit from answering out of band unnoticed.+ */+function clampToBand(value: number): { windowTokens: number; clamped: boolean } {+ if (value < MIN_MODEL_CONTEXT_WINDOW_TOKENS) {+ return { windowTokens: MIN_MODEL_CONTEXT_WINDOW_TOKENS, clamped: true };+ }+ if (value > MAX_MODEL_CONTEXT_WINDOW_TOKENS) {+ return { windowTokens: MAX_MODEL_CONTEXT_WINDOW_TOKENS, clamped: true };+ }+ return { windowTokens: value, clamped: false };+}++/**+ * Resolve the model context window. Precedence: operator config >+ * operator env > declared table > `1m` suffix > default; see the module+ * header for the pass-through and clamping contracts.+ */+export function resolveModelContextWindowTokens(+ input: ResolveModelContextWindowInput,+): ResolvedModelWindow {+ // A first-hand declaration is the true window by definition: it passes+ // through exactly, so a declared 8k/32k model is budgeted inside its+ // real window instead of being re-inflated to the band floor.+ if (usableChannelValue(input.operatorWindowTokens)) {+ return { windowTokens: input.operatorWindowTokens, source: "operator-config", clamped: false };+ }+ if (usableChannelValue(input.envWindowTokens)) {+ return { windowTokens: input.envWindowTokens, source: "operator-env", clamped: false };+ }+ const declared = declaredModelContextWindowTokens(input.model);+ if (declared !== null) return { windowTokens: declared, source: "declared", clamped: false };+ // The guessed tiers: the band bounds both, where the true window is+ // unknown and the answer is an expansion or an assumption.+ const structural = structuralModelContextWindowTokens(input.model);+ if (structural !== null) return { ...clampToBand(structural), source: "suffix" };+ return { ...clampToBand(DEFAULT_MODEL_CONTEXT_WINDOW_TOKENS), source: "default" };+}diff --git a/src/core/brain/notes/index-refresh.ts b/src/core/brain/notes/index-refresh.tsindex 9c87f583..6ce4c8cb 100644--- a/src/core/brain/notes/index-refresh.ts+++ b/src/core/brain/notes/index-refresh.ts@@ -243,6 +243,15 @@ const NO_INDEX_CLAIM: PostWriteRefreshClaim = Object.freeze({* one refresh the write needs. Back-to-back applied writes spawn one run* each; the claim machinery itself - exclusivity, backoff, the* writer-lock probe - caps them.+ *+ * The claim is also the one seam every applied in-process write crosses,+ * which makes it the one place the search side's 60 s behind-count memo+ * can be retired from: the invalidation below fires before the stale+ * gate, because it is a fact about the WRITE (the vault changed; a+ * memoized count describes a vault that no longer exists), not a+ * decision about the index the way the refresh claim is. Without it, an+ * origin where nothing freshens serves a confident 0 across notes this+ * process just wrote (M9).*/export async function claimPostWriteRefresh(vault: string,@@ -251,19 +260,21 @@ export async function claimPostWriteRefresh(now?: Date,configPath?: string,): Promise<PostWriteRefreshClaim> {- // Stale is the only state that describes an index this call aged. An- // absent index holds nothing to refresh, an unreadable one has no- // stamp to force past, and both are already on the report with the- // command that rebuilds or reconciles them.- if (index.state !== INDEX_EVIDENCE.stale) return NO_INDEX_CLAIM;try {const { resolveSearchConfig } = await import("../../search/index.ts");- const { FRESHEN_SKIP, markFreshenPending, maybeFreshenIndex } =- await import("../../search/freshen.ts");const config = resolveSearchConfig({vault,...(configPath !== undefined ? { configPath } : {}),});+ const { invalidateIndexBehindMemo } = await import("../../search/search.ts");+ invalidateIndexBehindMemo(config);+ // Stale is the only state that describes an index this call aged. An+ // absent index holds nothing to refresh, an unreadable one has no+ // stamp to force past, and both are already on the report with the+ // command that rebuilds or reconciles them.+ if (index.state !== INDEX_EVIDENCE.stale) return NO_INDEX_CLAIM;+ const { FRESHEN_SKIP, markFreshenPending, maybeFreshenIndex } =+ await import("../../search/freshen.ts");const decision = maybeFreshenIndex(config, {lastIndexedAt: index.lastIndexedAt,force: true,diff --git a/src/core/brain/path-constants.ts b/src/core/brain/path-constants.tsindex 8109523f..46c5ac1b 100644--- a/src/core/brain/path-constants.ts+++ b/src/core/brain/path-constants.ts@@ -267,6 +267,12 @@ export const BRAIN_INDEX_FILE = "_INDEX.md";export const BRAIN_CLAIM_GRAPH_FILE = "claim-graph.json";/** Persisted rollup-ladder counter ledger (knowledge-intake-and-consolidation, S3). */export const BRAIN_ROLLUP_LEDGER_FILE = "rollup-ladder.json";+/**+ * Cross-topic rule promotion ledger (t_642bc2b8), beside the rollup+ * ladder ledger: the last date each owner token promoted, so a+ * budgeted-out dream pass plans nothing rather than re-promoting.+ */+export const BRAIN_CROSS_TOPIC_LEDGER_FILE = "cross-topic-rules.json";/** Vault-relative path of the `o2b index` output file. */export const BRAIN_INDEX_REL = posix.join(BRAIN_ROOT_REL, BRAIN_INDEX_FILE);diff --git a/src/core/brain/paths.ts b/src/core/brain/paths.tsindex 317b4cb8..f1c57655 100644--- a/src/core/brain/paths.ts+++ b/src/core/brain/paths.ts@@ -41,6 +41,7 @@ import {BRAIN_CAPTURES_REL,BRAIN_CLAIM_GRAPH_FILE,BRAIN_CONFIG_FILE,+ BRAIN_CROSS_TOPIC_LEDGER_FILE,BRAIN_DECISIONS_REL,BRAIN_DISTILLATIONS_REL,BRAIN_ENTITIES_REL,@@ -120,6 +121,11 @@ export function rollupLedgerPath(vault: string): string {return ensureInsideVault(join(brainDirs(vault).brain, BRAIN_ROLLUP_LEDGER_FILE), vault);}+/** Path of the cross-topic rule ledger: `Brain/cross-topic-rules.json` (t_642bc2b8). */+export function crossTopicLedgerPath(vault: string): string {+ return ensureInsideVault(join(brainDirs(vault).brain, BRAIN_CROSS_TOPIC_LEDGER_FILE), vault);+}+const ISO_DATE_RE = /^(\d{4})-(\d{2})-(\d{2})$/;// Run IDs follow `dream-<YYYY-MM-DD>-<HHMMSS>`; we accept the same genericdiff --git a/src/core/brain/policy.ts b/src/core/brain/policy.tsindex 3949c663..60691a4a 100644--- a/src/core/brain/policy.ts+++ b/src/core/brain/policy.ts@@ -157,3 +157,17 @@ export {} from "./policy/blocks/sessions.ts";export { resolveEmbeddingSunsetDeclaration } from "./policy/blocks/embeddings.ts";export { decisionModelDisabledByVault } from "./policy/blocks/decision-model.ts";+/**+ * The cross-topic and context-window blocks (cycle 20261020 substrate).+ * The parsers are re-exported beside their default the way the other+ * blocks' resolvers are, so a consumer reaches every `cross_topic:` /+ * `context:` knob from the one policy surface its neighbours already use.+ * The `context` window's resolution and clamping live with the resolver+ * that consumes the stored value, not here: this surface only stores+ * what the operator declared.+ */+export {+ CONTEXT_WINDOW_TOKENS_DEFAULT,+ parseContextBlock,+ parseCrossTopicBlock,+} from "./policy/blocks/context.ts";diff --git a/src/core/brain/policy/blocks/context.ts b/src/core/brain/policy/blocks/context.tsnew file mode 100644index 00000000..fdb8c20e--- /dev/null+++ b/src/core/brain/policy/blocks/context.ts@@ -0,0 +1,87 @@+/**+ * The two blocks of the cycle-20261020 substrate wave: `cross_topic:` -+ * the dream pass's opt-in promotion of recurring cross-topic rules - and+ * `context:` - the operator's declaration of the host model's context+ * window. They ship as one substrate commit and share this module the+ * way the continuity-hygiene trio does: each is consumed by another lane+ * (the dream lane and the context-window lane respectively) and neither+ * consumer exists yet, so the parsers live together until their features+ * arrive.+ *+ * One reason to change: what an operator may declare about a cross-topic+ * promotion or a declared window. Both blocks are pure opt-ins - a whole+ * block absent resolves to the pre-block behaviour byte-identically -+ * and both store what the operator declared rather than second-guessing+ * it: an out-of-range but well-formed number is stored here, and what+ * the consumer does next differs by block. The cross-topic resolver+ * floors its knobs, disclosing every clamp; the context window's+ * operator declarations are first-hand facts that pass through the+ * resolver UNCLAMPED (model-window.ts; design decision 2) - only the+ * resolver's GUESSED answers, the `1m` suffix expansion and the+ * unknown-model default, are clamped to its band. A value of the wrong+ * SHAPE is refused here, because a knob that silently ignored its+ * operator would mislead every run with no sign of why.+ */++import type { BrainContextConfig, BrainCrossTopicConfig } from "../../types.ts";+import { BrainConfigError } from "../errors.ts";+import { requirePositiveInteger, requireUnitInterval } from "../field-checks.ts";+import { openBlock, warnUnknownKeys, type BlockParseContext } from "../key-index.ts";++const CROSS_TOPIC_KEYS = ["enabled", "min_topics", "jaccard"] as const;+const CONTEXT_KEYS = ["window_tokens"] as const;++/**+ * The window an absent `context.window_tokens` resolves to downstream.+ * Named here rather than in the resolver that lands with its consumer+ * because the config template must render a default from a named table,+ * never a literal repeated beside its consumer - and it matches the+ * figure `token-footprint.ts` already treats as the de-facto standard+ * window.+ */+export const CONTEXT_WINDOW_TOKENS_DEFAULT = 200_000;++/** A boolean key; anything else is refused rather than coerced. */+function requireBoolean(field: string, value: unknown, source: string | null): boolean {+ if (typeof value !== "boolean") {+ throw new BrainConfigError(+ `${field} must be true or false; got ${JSON.stringify(value)}`,+ field,+ source,+ );+ }+ return value;+}++export function parseCrossTopicBlock(ctx: BlockParseContext): BrainCrossTopicConfig | undefined {+ const rawMap = openBlock(ctx, "cross_topic");+ if (rawMap === undefined) return undefined;++ const partial: { enabled?: boolean; min_topics?: number; jaccard?: number } = {};+ if ("enabled" in rawMap) {+ partial.enabled = requireBoolean("cross_topic.enabled", rawMap["enabled"], ctx.source);+ }+ if ("min_topics" in rawMap) {+ requirePositiveInteger("cross_topic.min_topics", rawMap["min_topics"], ctx.source);+ partial.min_topics = rawMap["min_topics"] as number;+ }+ if ("jaccard" in rawMap) {+ requireUnitInterval("cross_topic.jaccard", rawMap["jaccard"], ctx.source);+ partial.jaccard = rawMap["jaccard"] as number;+ }+ warnUnknownKeys(ctx, rawMap, CROSS_TOPIC_KEYS, "cross_topic");+ return Object.freeze(partial);+}++export function parseContextBlock(ctx: BlockParseContext): BrainContextConfig | undefined {+ const rawMap = openBlock(ctx, "context");+ if (rawMap === undefined) return undefined;++ const partial: { window_tokens?: number } = {};+ if ("window_tokens" in rawMap) {+ requirePositiveInteger("context.window_tokens", rawMap["window_tokens"], ctx.source);+ partial.window_tokens = rawMap["window_tokens"] as number;+ }+ warnUnknownKeys(ctx, rawMap, CONTEXT_KEYS, "context");+ return Object.freeze(partial);+}diff --git a/src/core/brain/policy/validate.ts b/src/core/brain/policy/validate.tsindex 85e60b7d..c09dcb17 100644--- a/src/core/brain/policy/validate.ts+++ b/src/core/brain/policy/validate.ts@@ -46,6 +46,7 @@ import {parseHygieneBlock,parseRecallBlock,} from "./blocks/continuity-hygiene.ts";+import { parseContextBlock, parseCrossTopicBlock } from "./blocks/context.ts";import { parseFeedbackBlock } from "./blocks/feedback.ts";import { parseDecisionModelBlock } from "./blocks/decision-model.ts";import { parseStorageBlock } from "./blocks/storage.ts";@@ -128,6 +129,8 @@ export function validateBrainConfigDetailed(const feedback = parseFeedbackBlock(ctx);const decisionModel = parseDecisionModelBlock(ctx);const storage = parseStorageBlock(ctx);+ const crossTopic = parseCrossTopicBlock(ctx);+ const context = parseContextBlock(ctx);warnUnknownTopLevelKeys(ctx);@@ -162,6 +165,8 @@ export function validateBrainConfigDetailed(...(feedback !== undefined ? { feedback } : {}),...(decisionModel !== undefined ? { decision_model: decisionModel } : {}),...(storage !== undefined ? { storage } : {}),+ ...(crossTopic !== undefined ? { cross_topic: crossTopic } : {}),+ ...(context !== undefined ? { context } : {}),};return { config, warnings: ctx.warnings, knownKeys: ctx.keys };diff --git a/src/core/brain/receipts/types.ts b/src/core/brain/receipts/types.tsindex 3ce7381d..a7ef5727 100644--- a/src/core/brain/receipts/types.ts+++ b/src/core/brain/receipts/types.ts@@ -175,6 +175,12 @@ export const FOLDABLE_CONTINUITY_KINDS: ReadonlyArray<ContinuityRecordKind> = Ob* on stays auditable after the answer has been given, which is* per-record identity past any correlation window; a fold would* destroy exactly that auditability;+ * - `decision_model_eval_grade` - the cached verdict sets of the+ * preregistered decision-model evaluation (t_4e1681b3), read back as+ * data by `o2b decision-model eval list` and by the check's+ * measured-state line so a tuning mark can be audited against what+ * the run actually recorded; a fold would erase exactly the evidence+ * a reviewer needs;* - `receipt_compaction` - the compaction audit trail itself; a fold* that removed the record of the run before it would erase the only* account of what the fold has already destroyed;@@ -196,6 +202,7 @@ export const KEPT_CONTINUITY_KINDS: ReadonlyArray<ContinuityRecordKind> = Object"generation_report","host_memory_write","session_entity_mention",+ "decision_model_eval_grade","recall_observed_use","negative_recall","receipt_compaction",diff --git a/src/core/brain/review-candidates.ts b/src/core/brain/review-candidates.tsindex bee2a23f..d8253537 100644--- a/src/core/brain/review-candidates.ts+++ b/src/core/brain/review-candidates.ts@@ -222,7 +222,11 @@ export async function buildReviewCandidates(: {}),...(siblings.semantic !== undefined ? { retire_siblings_semantic: siblings.semantic } : {}),...(siblings.detail !== undefined ? { retire_siblings_semantic_detail: siblings.detail } : {}),- would_create: Object.freeze([...summary.new_unconfirmed]),+ // Both creation lists: the topic plan's drafts and the cross-topic+ // planner's promotions are new unconfirmed preference files either+ // way, so an operator previews them as one decision surface+ // (finding 65) instead of a cross-topic-only pass reading as empty.+ would_create: Object.freeze([...summary.new_unconfirmed, ...(summary.cross_topic_rules ?? [])]),would_promote: Object.freeze([...summary.confirmed]),would_retire: Object.freeze(summary.retired.map((r) => Object.freeze({ id: r.id, reason: r.reason })),diff --git a/src/core/brain/types.ts b/src/core/brain/types.tsindex 77f2a92a..dab2cf30 100644--- a/src/core/brain/types.ts+++ b/src/core/brain/types.ts@@ -1482,6 +1482,26 @@ export interface BrainDreamConfig {readonly salience_threshold?: number;}+/**+ * Optional `cross_topic:` block (t_642bc2b8). Opts the dream pass into+ * promoting one recurring cross-topic rule per owner per calendar day:+ * confirmed preferences in at least `min_topics` distinct topic buckets+ * whose principles reach `jaccard` similarity, deduplicated through the+ * `Brain/cross-topic-rules.json` ledger. The whole block absent (the+ * default) keeps the pass off, so a vault that has never heard of it+ * behaves byte-identically. Declared beside {@link BrainDreamConfig}+ * because it feeds the same pass; it is a top-level block because the+ * `_brain.yaml` grammar is two levels deep.+ */+export interface BrainCrossTopicConfig {+ /** Master switch. Absent is treated as `false`. */+ readonly enabled?: boolean;+ /** Minimum distinct topic buckets before a cluster may fire. */+ readonly min_topics?: number;+ /** Principle-similarity floor, in `[0, 1]`, for a cross-bucket pair. */+ readonly jaccard?: number;+}+export interface BrainRetireConfig {/** Days without evidence after which a confirmed pref retires. */readonly stale_evidence_days: number;@@ -1902,6 +1922,12 @@ export interface BrainConfig {* back to the `DEFAULT_*_THRESHOLD` constants in `rollup-ladder.ts`.*/readonly rollup?: BrainRollupConfig;+ /**+ * Optional `cross_topic:` block (t_642bc2b8). Opts the dream pass+ * into promoting recurring cross-topic rules. Absent: the pass never+ * fires, byte-identical to a vault that predates the block.+ */+ readonly cross_topic?: BrainCrossTopicConfig;/*** Vault-wide exclusion policy (v0.10.9). Absent when the user* has not declared `vault.ignore_paths` in `_brain.yaml`; the@@ -2039,6 +2065,12 @@ export interface BrainConfig {* pre-compress. Absent: the historical hard cut.*/readonly recall?: BrainRecallConfig;+ /**+ * Optional `context:` block (t_a567cc12). The operator's declared+ * model context window. Absent: consumers resolve their default,+ * byte-identical to a vault that predates the block.+ */+ readonly context?: BrainContextConfig;/*** Optional `recall_inject:` block. Declares the named slices the* recall-inject hook retrieves and renders as headed groups. Absent:@@ -2077,6 +2109,19 @@ export interface BrainRecallConfig {readonly degradation?: "hard-cut" | "staged";}+/**+ * Optional `context:` block (t_a567cc12). The operator's declaration of+ * the host model's real context window, in tokens, sizing context packs,+ * preset suggestions and compact guidance. Absent: consumers resolve+ * their declared default. A stored value may lie outside the range a+ * consumer supports - this block records what the operator declared,+ * and the resolving consumer clamps it and discloses the clamp.+ */+export interface BrainContextConfig {+ /** The model context window, in tokens. */+ readonly window_tokens?: number;+}+/** One operator-declared recall slice from the `recall_inject:` block. */export interface RecallSliceSpec {/** Matches `^[a-z][a-z0-9]{0,23}$`, so `slice_<name>_<field>` splits unambiguously. */diff --git a/src/core/config.ts b/src/core/config.tsindex d925e497..2507dac2 100644--- a/src/core/config.ts+++ b/src/core/config.ts@@ -1120,6 +1120,36 @@ function resolveAdequacyMinResults(env: string | undefined, fileValue: string |return value;}+/**+ * Operator-declared model context window, environment channel+ * (t_a567cc12). The vault-side channel is the `context:` block of+ * `Brain/_brain.yaml`, and the BLOCK wins over a value here: the+ * resolver's deliberate precedence (plan B1) is operator config >+ * operator env > declared table > `1m` suffix > default, and an+ * explicit per-call argument wins over both operator channels. The+ * precedence lives with the resolver that consumes the parsed values,+ * exactly as the recall-adequacy floors above hand theirs to their+ * consumer.+ *+ * A well-formed positive integer is returned as-is: like every+ * first-hand declaration it passes through the resolver unclamped - the+ * declaration exists to state the true window. Any other value fails+ * fast, mirroring the trio above - a window that silently ignored its+ * operator would mis-size every pack.+ */+export const MODEL_CONTEXT_WINDOW_ENV_KEY = "OPEN_SECOND_BRAIN_MODEL_CONTEXT_WINDOW";++/** Parse {@link MODEL_CONTEXT_WINDOW_ENV_KEY}; `undefined` when unset or blank. */+export function resolveModelContextWindowEnvTokens(): number | undefined {+ const raw = process.env[MODEL_CONTEXT_WINDOW_ENV_KEY]?.trim() ?? "";+ if (raw === "") return undefined;+ const value = Number(raw);+ if (!Number.isInteger(value) || value <= 0) {+ throw new Error(`${MODEL_CONTEXT_WINDOW_ENV_KEY} must be a positive integer; got '${raw}'`);+ }+ return value;+}+/*** Generation-report tracing gate (Hindsight brain-loop ops, t_281c3edc).* Default OFF: the inbound `generation_report` continuity path staysdiff --git a/src/core/decision-model/config.ts b/src/core/decision-model/config.tsindex d12097af..ca609add 100644--- a/src/core/decision-model/config.ts+++ b/src/core/decision-model/config.ts@@ -51,6 +51,7 @@ import {DECISION_MODEL_WIRE_MAX_CHOICE_OPTIONS,decisionModelPreset,} from "./presets.ts";+import { machineTunedMarkReader } from "./eval/mark.ts";import {DECISION_THRESHOLD_PROFILE_NAMES,isDecisionThresholdProfile,@@ -117,14 +118,19 @@ function isLoopbackUrl(raw: string | null): boolean {/*** The modes the uses actually run in: `enforce` becomes `shadow` for every- * use whose thresholds are not tuned for `profile`.+ * use whose thresholds are not tuned for `profile` - unless the+ * injected measured reader says the preregistered eval has marked the+ * pair tuned (the machine-side tuning mark, `eval/mark.ts`).*/function holdToProfile(uses: DecisionModelUses,profile: string | null,+ measuredTuned?: ((use: DecisionModelUse) => boolean) | null,): { readonly uses: DecisionModelUses; readonly shadowOnly: ReadonlyArray<DecisionModelUse> } {const shadowOnly = DECISION_MODEL_USES.filter(- (use) => uses[use] === "enforce" && !thresholdsTunedFor(profile, use),+ (use) =>+ uses[use] === "enforce" &&+ !thresholdsTunedFor(profile, use, measuredTuned ? () => measuredTuned(use) : null),);if (shadowOnly.length === 0) return { uses, shadowOnly: Object.freeze([]) };const out: Record<DecisionModelUse, DecisionModelMode> = { ...uses };@@ -271,6 +277,15 @@ export interface ResolveDecisionModelOptions {* whole policy loader at startup; defaults to the real loader.*/readonly vaultOptOut?: (vault: string) => boolean;+ /**+ * The measured-tune reader: consulted only when the source table says+ * a use is untuned for the resolved profile. Undefined (the default)+ * reads the machine-side tuning marks under the platform state root -+ * one TTL-cached file read per untuned pair per minute; null disables+ * the measured path entirely, which is the behavior every hand-edit+ * test pins.+ */+ readonly measuredTunedMark?: ((profile: string | null, use: DecisionModelUse) => boolean) | null;}function defaultVaultOptOut(vault: string): boolean {@@ -518,7 +533,24 @@ export function resolveDecisionModelConfig();}}- const held = holdToProfile(configured, thresholdProfile);+ const held = holdToProfile(+ configured,+ thresholdProfile,+ thresholdProfile === null+ ? null+ : (use) => {+ // Disabled reader (null): the table alone decides. Default+ // (undefined): the machine-side marks, TTL-cached inside the+ // mark module, bound to THIS resolution's endpoint - a mark+ // earned by another provider, model or base URL never arms+ // enforce here.+ if (opts.measuredTunedMark === null) return false;+ const reader =+ opts.measuredTunedMark ??+ machineTunedMarkReader({ provider: providerRaw, model, baseUrl });+ return reader(thresholdProfile, use);+ },+ );const uses = held.uses;// A self-hosted server on this machine needs no key; anything that leavesdiff --git a/src/core/decision-model/diagnostics.ts b/src/core/decision-model/diagnostics.tsindex e1d3c11d..f0428f62 100644--- a/src/core/decision-model/diagnostics.ts+++ b/src/core/decision-model/diagnostics.ts@@ -24,9 +24,15 @@ import {DECISION_MODEL_CALL_KIND,emitDecisionModelCall,listDecisionModelCalls,+ listDecisionModelEvalGrades,todaySpendUsd,+ type DecisionEvalGrade,} from "./record.ts";import type { ContinuityRecord } from "../brain/continuity/types.ts";+import { DECISION_THRESHOLD_PROFILES, isDecisionThresholdProfile } from "./questions.ts";+import { decisionEvalSpecFor, decisionEvalSpecHash, type DecisionEvalSpec } from "./eval-spec.ts";+import { validatedTuningMark } from "./eval/mark.ts";+import { processDirsEnv, type PlatformDirsEnv } from "../platform-dirs.ts";import { USE_REPORTS } from "./reports/index.ts";/**@@ -71,6 +77,24 @@ export interface DecisionModelCheckReport {readonly threshold_profile: string | null;/** Uses configured `enforce` that run as `shadow` for want of tuned thresholds. */readonly shadow_only_uses: ReadonlyArray<DecisionModelUse>;+ /**+ * The measured tuning state of the resolved threshold profile: what the+ * source table claims, and which (profile, use) pairs a valid+ * machine-side mark covers (`eval/mark.ts`).+ */+ readonly tuning: MeasuredTuning;+ /** Cached preregistered-eval verdicts, per use, with the skip notes. */+ readonly eval_grades: {+ readonly total: number;+ readonly skipped: ReadonlyArray<string>;+ readonly uses: ReadonlyArray<{+ readonly use: string;+ readonly runs: number;+ readonly last_verdict: string | null;+ readonly last_at: string | null;+ readonly last_spec_hash: string | null;+ }>;+ };/** Most options one `choice` question may carry on this route. */readonly max_choice_options: number;readonly output_price_usd_per_mtok: number | null;@@ -115,6 +139,11 @@ export interface DecisionModelCheckOptions {readonly env?: NodeJS.ProcessEnv;readonly ping?: boolean;readonly now?: Date;+ /**+ * Where the machine-side tuning marks are read from. Defaults to the+ * running process's platform dirs; tests inject a state root.+ */+ readonly markSource?: PlatformDirsEnv | null;}const RERANK_ENDPOINT_KEYS = [@@ -123,6 +152,133 @@ const RERANK_ENDPOINT_KEYS = ["search_rerank_env_key",] as const;+// ----- the measured tuning state ----------------------------------------------++/** One (use, spec hash) pair a valid tuning mark covers. */+export interface MarkedUse {+ readonly use: DecisionModelUse;+ readonly spec_hash: string;+}++export interface MeasuredTuning {+ /** The resolved threshold profile; null when none resolves. */+ readonly profile: string | null;+ /**+ * `none`: no profile. `baseline`: the profile ships tuned for every+ * use. `hand`: the source table carries hand-registered uses.+ * `measured`: at least one pair carries a valid machine-side mark.+ * `measured_elsewhere`: a mark exists but is bound to another endpoint,+ * so enforce holds as shadow here. `untuned`: nothing tuned, so+ * enforce holds as shadow.+ */+ readonly state: "none" | "baseline" | "hand" | "measured" | "measured_elsewhere" | "untuned";+ readonly marked_uses: ReadonlyArray<MarkedUse>;+ /**+ * Pairs whose mark passes every acceptance axis but is bound to a+ * different endpoint (provider, model or base URL): the gate holds+ * them shadow on this one. Never armed, and never counted in+ * {@link marked_uses}.+ */+ readonly elsewhere_uses: ReadonlyArray<MarkedUse>;+}++/**+ * The measured tuning state of the resolved profile: the source table+ * decides first (baseline, or a hand-registered list), and only the+ * pairs the table leaves untuned can be carried by a valid machine-side+ * mark. Marks are checked against THIS config's endpoint - the same+ * provider, model and base URL the resolver's gate reader binds - so a+ * promote measured on one model never reads as measured for another.+ * The same vocabulary and the same short spec hash render into+ * `check`, the report and the doctor probe, so the surfaces cannot+ * disagree about what "tuned" means here.+ */+export function measuredTuning(+ cfg: ResolvedDecisionModelConfig,+ source: PlatformDirsEnv = processDirsEnv(),+): MeasuredTuning {+ const profile = cfg.thresholdProfile ?? null;+ if (profile === null || !isDecisionThresholdProfile(profile)) {+ return { profile, state: "none", marked_uses: [], elsewhere_uses: [] };+ }+ const tuned = DECISION_THRESHOLD_PROFILES[profile]?.tuned ?? [];+ if (tuned === "baseline") {+ return { profile, state: "baseline", marked_uses: [], elsewhere_uses: [] };+ }+ // The same endpoint shape the resolver's gate reader binds+ // (config.ts): a mark measured elsewhere never arms enforce here, so+ // it must never read as measured here either.+ const endpoint = { provider: cfg.provider, model: cfg.model, baseUrl: cfg.baseUrl };+ const marked: MarkedUse[] = [];+ const elsewhere: MarkedUse[] = [];+ for (const use of DECISION_MODEL_USES) {+ const spec: DecisionEvalSpec | null = decisionEvalSpecFor(use);+ if (spec === null) continue;+ if (validatedTuningMark(profile, use, source, spec, Date.now(), endpoint) !== null) {+ marked.push({ use, spec_hash: decisionEvalSpecHash(spec) });+ } else if (validatedTuningMark(profile, use, source, spec) !== null) {+ // Passes every axis but the endpoint: measured, but not here.+ elsewhere.push({ use, spec_hash: decisionEvalSpecHash(spec) });+ }+ }+ if (marked.length > 0) {+ return { profile, state: "measured", marked_uses: marked, elsewhere_uses: elsewhere };+ }+ if (elsewhere.length > 0) {+ return { profile, state: "measured_elsewhere", marked_uses: [], elsewhere_uses: elsewhere };+ }+ if (Array.isArray(tuned) && tuned.length > 0) {+ return { profile, state: "hand", marked_uses: [], elsewhere_uses: [] };+ }+ return { profile, state: "untuned", marked_uses: [], elsewhere_uses: [] };+}++/** The short form the prose surfaces print: first twelve hex characters. */+export function shortSpecHash(hash: string): string {+ return `${hash.slice(0, 12)}…`;+}++/** The one tuning sentence `check`, `report` and the doctor probe share. */+export function measuredTuningSummary(measured: MeasuredTuning): string {+ switch (measured.state) {+ case "none":+ return "no threshold profile resolves, so the source table alone gates enforce";+ case "baseline":+ return `profile '${measured.profile}' is the baseline`;+ case "hand":+ return `profile '${measured.profile}' carries hand-registered tuned uses`;+ case "measured": {+ const parts = measured.marked_uses+ .map((m) => `${shortSpecHash(m.spec_hash)} (${m.use})`)+ .join(", ");+ const sentence = `profile '${measured.profile}' measured under spec hash ${parts}`;+ if (measured.elsewhere_uses.length === 0) return sentence;+ const other = measured.elsewhere_uses+ .map((m) => `${shortSpecHash(m.spec_hash)} (${m.use})`)+ .join(", ");+ return (+ sentence ++ `; a mark for ${other} was measured on another endpoint ` ++ "(provider, model or base-url mismatch) and holds shadow here"+ );+ }+ case "measured_elsewhere": {+ const parts = measured.elsewhere_uses+ .map((m) => `${shortSpecHash(m.spec_hash)} (${m.use})`)+ .join(", ");+ return (+ `profile '${measured.profile}' measured under spec hash ${parts} on another ` ++ "endpoint (provider, model or base-url mismatch); enforce holds as shadow"+ );+ }+ case "untuned":+ return (+ `profile '${measured.profile}' is untuned; enforce holds as shadow ` ++ "(o2b decision-model eval run can measure a use)"+ );+ }+}+function hintFor(cfg: ResolvedDecisionModelConfig): string | null {switch (cfg.status) {case "disabled": {@@ -241,6 +397,59 @@ export async function buildDecisionModelCheck();}+ // The measured tuning state: read only when the feature is enabled and+ // a profile resolves - the same condition under which the resolver+ // consulted the marks - so a disabled install pays no file reads.+ const tuning = cfg.enabled+ ? measuredTuning(+ cfg,+ opts.markSource === null ? processDirsEnv() : (opts.markSource ?? processDirsEnv()),+ )+ : {+ profile: cfg.thresholdProfile ?? null,+ state: "none" as const,+ marked_uses: [],+ elsewhere_uses: [],+ };++ // The cached eval verdicts are review evidence for the mark; a check+ // that named the measured state without them would be unauditable.+ const gradeUses: {+ use: string;+ runs: number;+ last_verdict: string | null;+ last_at: string | null;+ last_spec_hash: string | null;+ }[] = [];+ let gradeTotal = 0;+ const gradeSkipped: string[] = [];+ if (cfg.enabled && opts.vault !== null) {+ try {+ const { grades, skipped } = listDecisionModelEvalGrades(opts.vault);+ gradeTotal = grades.length;+ gradeSkipped.push(...skipped);+ const byUse = new Map<string, DecisionEvalGrade[]>();+ for (const grade of grades) {+ const list = byUse.get(grade.use) ?? [];+ list.push(grade);+ byUse.set(grade.use, list);+ }+ for (const [use, list] of [...byUse].toSorted((a, b) => a[0].localeCompare(b[0]))) {+ const last = list[list.length - 1]!;+ gradeUses.push({+ use,+ runs: list.length,+ last_verdict: last.verdict,+ last_at: last.createdAt,+ last_spec_hash: last.specHash,+ });+ }+ } catch {+ // An unreadable log is reported as no cached grades, the same+ // fail-soft direction the spend probe above takes.+ }+ }+const kindRaw = env["OPEN_SECOND_BRAIN_SEARCH_RERANK_KIND"] || opts.config["search_rerank_kind"];const kindConfigured = kindRaw === "decision-model";const ignored = kindConfigured@@ -263,6 +472,8 @@ export async function buildDecisionModelCheck(calibrated: cfg.calibrated,threshold_profile: cfg.thresholdProfile ?? null,shadow_only_uses: shadowOnly,+ tuning,+ eval_grades: { total: gradeTotal, skipped: gradeSkipped, uses: gradeUses },max_choice_options: cfg.maxChoiceOptions ?? CHOICE_MAX_OPTIONS,output_price_usd_per_mtok: cfg.outputPriceUsdPerMtok ?? null,licence_note: cfg.licenceNote ?? null,@@ -369,6 +580,22 @@ export function renderDecisionModelCheck(report: DecisionModelCheckReport): stri` threshold profile: ${report.threshold_profile ?? "(unknown: no use enforces)"}; ` +`max choice options: ${report.max_choice_options}`,);+ lines.push(` tuning: ${measuredTuningSummary(report.tuning)}`);+ const gradeUse = report.eval_grades.uses+ .map((u) => {+ const at = u.last_at === null ? "" : ` at ${u.last_at}`;+ const spec = u.last_spec_hash === null ? "" : ` under ${shortSpecHash(u.last_spec_hash)}`;+ return `${u.use}: ${u.runs} run(s), last ${u.last_verdict ?? "?"}${spec}${at}`;+ })+ .join("; ");+ lines.push(+ report.eval_grades.total === 0+ ? " eval grades: none cached"+ : ` eval grades: ${report.eval_grades.total} record(s) (${gradeUse})` ++ (report.eval_grades.skipped.length > 0+ ? `, ${report.eval_grades.skipped.length} skipped`+ : ""),+ );const spend =report.today_spend_usd === null ? "unknown" : `$${report.today_spend_usd.toFixed(6)}`;const gate = report.cost_gate_usd > 0 ? `$${report.cost_gate_usd}` : "off";@@ -429,6 +656,41 @@ export interface DecisionModelReport {* absent for `rerank`, whose metric is the summary's shadow agreement.*/readonly use_report?: { readonly use: DecisionModelUse; readonly report: unknown };+ /**+ * The cached verdict sets of the preregistered evaluation+ * (`eval/grade.ts`), oldest first, with the named skip notes. Present+ * whenever the vault holds at least one, so a vault with none renders+ * no eval section at all rather than an empty one.+ */+ readonly eval?: {+ readonly grades: ReadonlyArray<DecisionEvalGradeLine>;+ readonly skipped: ReadonlyArray<string>;+ };+}++/** One cached eval grade, as the prose and JSON surfaces print it. */+export interface DecisionEvalGradeLine {+ readonly record_id: string;+ readonly created_at: string;+ readonly use: string;+ readonly profile: string | null;+ readonly verdict: string;+ readonly spec_hash: string;+ readonly counted_n: number;+ readonly counted_error: number | null;+ readonly baseline_error: number | null;+ readonly dev_error: number | null;+}++/** The one-line prose form of a cached eval grade, shared by the surfaces. */+export function renderEvalGradeLine(grade: DecisionEvalGradeLine): string {+ const num = (v: number | null): string => (v === null ? "-" : v.toFixed(3));+ return (+ `${grade.created_at} ${grade.use} (${grade.profile ?? "no profile"}) ${grade.verdict}: ` ++ `counted error ${num(grade.counted_error)} over n=${grade.counted_n}, ` ++ `baseline ${num(grade.baseline_error)}, dev ${num(grade.dev_error)}, ` ++ `spec ${shortSpecHash(grade.spec_hash)}`+ );}function percentile(sorted: ReadonlyArray<number>, p: number): number | null {@@ -521,13 +783,40 @@ export function buildDecisionModelReport(});}const summary: DecisionModelReport = { since: opts.since ?? null, total: records.length, uses };+ // The eval section is built for every report: `o2b decision-model+ // report` is the audit surface for the grades a mark was written from.+ const { grades, skipped } = listDecisionModelEvalGrades(vault, opts.since);+ const evalSection =+ grades.length > 0 || skipped.length > 0+ ? {+ grades: grades.map((g): DecisionEvalGradeLine => ({+ record_id: g.recordId,+ created_at: g.createdAt,+ use: g.use,+ profile: g.profile,+ verdict: g.verdict,+ spec_hash: g.specHash,+ counted_n: g.countedN,+ counted_error: g.countedError,+ baseline_error: g.baselineError,+ dev_error: g.devError,+ })),+ skipped,+ }+ : undefined;if (opts.use === undefined || opts.useReport === false || !isDecisionModelUse(opts.use)) {- return summary;+ return evalSection === undefined ? summary : { ...summary, eval: evalSection };}const entry = USE_REPORTS[opts.use];- if (entry === null) return summary;+ if (entry === null) {+ return evalSection === undefined ? summary : { ...summary, eval: evalSection };+ }const since = opts.since !== undefined ? { since: opts.since } : {};- return { ...summary, use_report: { use: opts.use, report: entry.build(vault, since) } };+ return {+ ...summary,+ ...(evalSection !== undefined ? { eval: evalSection } : {}),+ use_report: { use: opts.use, report: entry.build(vault, since) },+ };}export function renderDecisionModelReport(report: DecisionModelReport): string {@@ -553,6 +842,14 @@ export function renderDecisionModelReport(report: DecisionModelReport): string {);}}+ if (report.eval !== undefined) {+ lines.push(+ `decision model eval grades: ${report.eval.grades.length} record(s)` ++ (report.eval.skipped.length > 0 ? `, ${report.eval.skipped.length} skipped` : ""),+ );+ for (const grade of report.eval.grades) lines.push(` ${renderEvalGradeLine(grade)}`);+ for (const note of report.eval.skipped) lines.push(` skipped: ${note}`);+ }if (report.use_report !== undefined) {const entry = USE_REPORTS[report.use_report.use];if (entry !== null) lines.push(entry.render(report.use_report.report));diff --git a/src/core/decision-model/eval-spec.ts b/src/core/decision-model/eval-spec.tsnew file mode 100644index 00000000..e6b3cc02--- /dev/null+++ b/src/core/decision-model/eval-spec.ts@@ -0,0 +1,316 @@+/**+ * The preregistered decision-model eval specs (cycle 20261020, card+ * t_4e1681b3).+ *+ * "Preregistered" is a commitment with mechanical teeth: before any+ * grading happens, a spec freezes (a) the committed fixture and its+ * content hash, (b) the seed and the hash-order dev/counted split rule+ * with the derived membership as a frozen receipt, (c) the promotion+ * metric with its ceiling and minimum counted n, and (d) the exact+ * threshold values of the use being validated - so a profile can never+ * be marked tuned against thresholds that later moved. The whole spec is+ * content-hashed; every cached grade record and every machine-side+ * tuning mark stamps that hash, so a spec edited after grades were seen+ * invalidates them instead of quietly re-scoping the claim.+ *+ * This file, with the fixtures it references, landed in one reviewable+ * commit BEFORE the eval runner existed (task C1 precedes C2); the+ * runner verifies the fixture and take against the receipt at run time+ * (`eval/take.ts`) and refuses mismatches.+ *+ * Scope: the registry holds the uses with a committed, labeled take.+ * `extract_prefilter` is deliberately absent - its gate is the+ * zero-regret shadow-span rule already measured by its report+ * (`reports/extract-prefilter.ts`), and it keeps that loop. The other+ * advisory uses gain specs the same way when a take is committed for+ * them.+ *+ * Grading protocol, frozen with the specs: the deterministic scorer is+ * canonical, an external judge is advisory only, and graded requests are+ * real spend counted toward the daily cost gate (`eval/grade.ts`).+ */++import { canonicalJson, sha256Hex } from "../integrity/digest.ts";+import { isDecisionModelUse, type DecisionModelUse } from "./contract.ts";+import { RECALL_INJECT_ANY_MIN, RECALL_INJECT_NOTE_MIN } from "./questions.ts";++/** Bumped on any deliberate re-registration; part of the spec hash. */+export const DECISION_EVAL_SPEC_VERSION = 1;++/** The only split rule this build derives receipts with. */+export const DECISION_EVAL_SPLIT_RULE = "hash-order-30-70";++/** Dev share of the take; the counted remainder produces the metric. */+export const DECISION_EVAL_DEV_FRACTION = 0.3;++/** The only promotion metric this build writes marks for. */+export const DECISION_EVAL_METRIC = "counted_error_rate";++/**+ * The preregistered three-arm verdict, the same shape the+ * extract_prefilter report keeps: a use promotes only when the counted+ * error meets the ceiling, does not regress against the deterministic+ * baseline, and the counted n is met; too few counted items is its own+ * arm, not a failure.+ */+export type DecisionEvalVerdict = "promote" | "hold" | "not_enough_evidence";++export const DECISION_EVAL_VERDICTS: ReadonlyArray<DecisionEvalVerdict> = Object.freeze([+ "promote",+ "hold",+ "not_enough_evidence",+]);++/** sha-256 hex digest length. */+const HASH_HEX_LENGTH = 64;++export interface DecisionEvalSpec {+ readonly version: number;+ /** The use this spec validates. */+ readonly use: DecisionModelUse;+ /** The committed fixture file, repo-relative. */+ readonly fixture: string;+ /** The split seed; `sha256Hex(seed + ":" + id)` ranks the take ids. */+ readonly seed: string;+ readonly split: {+ readonly rule: typeof DECISION_EVAL_SPLIT_RULE;+ readonly dev_fraction: number;+ };+ /**+ * The frozen membership receipt: the take ids with their dev/counted+ * assignment, each list sorted lexicographically. Frozen at+ * preregistration so fixture growth cannot silently move the counted+ * boundary; the runner derives the split fresh and refuses mismatches.+ */+ readonly receipt: {+ readonly dev: ReadonlyArray<string>;+ readonly counted: ReadonlyArray<string>;+ };+ /** sha-256 of the canonical fixture document, frozen at preregistration. */+ readonly fixture_hash: string;+ readonly metric: typeof DECISION_EVAL_METRIC;+ /**+ * The counted error rate at or below which the use may be marked+ * tuned. Conservative starting constants: rerank 0.05 (one top-1 miss+ * in twenty), recall_inject 0 - a dropped useful note is regret, the+ * same zero-regret target its report family keeps.+ */+ readonly ceiling: number;+ /** Minimum counted n below which the verdict is "not enough evidence". */+ readonly min_counted: number;+ /**+ * The exact threshold values the use reads from `questions.ts` when it+ * enforces, pinned so a mark written against these values is refused+ * the day they move. Empty where the use reads no probability floor+ * from the table (rerank's reorder is threshold-free).+ */+ readonly thresholds: Readonly<Record<string, number>>;+}++/** Validate one spec. A missing or malformed element is a construction error. */+export function validateDecisionEvalSpec(spec: DecisionEvalSpec): void {+ const at = (what: string): string => `eval spec '${spec.use ?? "?"}': ${what}`;+ if (spec.version !== DECISION_EVAL_SPEC_VERSION) {+ throw new Error(+ at(`version must be ${DECISION_EVAL_SPEC_VERSION}, got ${String(spec.version)}`),+ );+ }+ if (!isDecisionModelUse(spec.use)) {+ throw new Error(at(`use ${JSON.stringify(spec.use)} is not a decision-model use`));+ }+ if (typeof spec.fixture !== "string" || spec.fixture.trim() === "") {+ throw new Error(at("fixture must name the committed fixture file"));+ }+ if (typeof spec.seed !== "string" || spec.seed.trim() === "") {+ throw new Error(at("seed must be a non-empty string"));+ }+ if (spec.split?.rule !== DECISION_EVAL_SPLIT_RULE) {+ throw new Error(at(`split rule must be '${DECISION_EVAL_SPLIT_RULE}'`));+ }+ if (spec.split?.dev_fraction !== DECISION_EVAL_DEV_FRACTION) {+ throw new Error(at(`dev fraction must be ${DECISION_EVAL_DEV_FRACTION}`));+ }+ const receiptOk =+ Array.isArray(spec.receipt?.dev) &&+ Array.isArray(spec.receipt?.counted) &&+ spec.receipt.dev.length > 0 &&+ spec.receipt.counted.length > 0 &&+ [...spec.receipt.dev, ...spec.receipt.counted].every(+ (id) => typeof id === "string" && id.trim() !== "",+ ) &&+ new Set([...spec.receipt.dev, ...spec.receipt.counted]).size ===+ spec.receipt.dev.length + spec.receipt.counted.length;+ if (!receiptOk) {+ throw new Error(at("receipt must freeze non-empty, disjoint dev and counted id lists"));+ }+ if (+ typeof spec.fixture_hash !== "string" ||+ !new RegExp(`^[0-9a-f]{${HASH_HEX_LENGTH}}$`).test(spec.fixture_hash)+ ) {+ throw new Error(at("fixture hash must be a 64-character sha-256 hex digest"));+ }+ if (spec.metric !== DECISION_EVAL_METRIC) {+ throw new Error(at(`metric must be '${DECISION_EVAL_METRIC}'`));+ }+ if (+ typeof spec.ceiling !== "number" ||+ !Number.isFinite(spec.ceiling) ||+ spec.ceiling < 0 ||+ spec.ceiling > 1+ ) {+ throw new Error(at("ceiling must be a number in [0, 1]"));+ }+ if (!Number.isInteger(spec.min_counted) || spec.min_counted < 1) {+ throw new Error(at("minimum counted n must be a positive integer"));+ }+ const thresholds = spec.thresholds ?? {};+ for (const [name, value] of Object.entries(thresholds)) {+ if (typeof value !== "number" || !Number.isFinite(value)) {+ throw new Error(at(`thresholds must hold finite numbers, got ${name}: ${String(value)}`));+ }+ }+}++/**+ * The spec hash every grade record and tuning mark stamps: sha-256 over+ * the canonical JSON of the whole spec, so any edit - receipt, seed,+ * ceiling, pinned thresholds, version - invalidates what came before.+ */+export function decisionEvalSpecHash(spec: DecisionEvalSpec): string {+ return sha256Hex(canonicalJson(spec));+}++/**+ * The preregistered specs, one per use with a committed labeled take.+ * `cycle-20261020` is the registration seed for this cycle's takes.+ */+export const DECISION_EVAL_SPECS: Readonly<Partial<Record<DecisionModelUse, DecisionEvalSpec>>> =+ Object.freeze({+ rerank: Object.freeze({+ version: DECISION_EVAL_SPEC_VERSION,+ use: "rerank",+ fixture: "tests/fixtures/decision-model/rerank-take.json",+ seed: "cycle-20261020",+ split: Object.freeze({+ rule: DECISION_EVAL_SPLIT_RULE,+ dev_fraction: DECISION_EVAL_DEV_FRACTION,+ }),+ receipt: Object.freeze({+ dev: Object.freeze([+ "rk-006",+ "rk-007",+ "rk-009",+ "rk-010",+ "rk-012",+ "rk-014",+ "rk-017",+ "rk-026",+ "rk-028",+ "rk-033",+ "rk-038",+ "rk-039",+ "rk-043",+ ]),+ counted: Object.freeze([+ "rk-001",+ "rk-002",+ "rk-003",+ "rk-004",+ "rk-005",+ "rk-008",+ "rk-011",+ "rk-013",+ "rk-015",+ "rk-016",+ "rk-018",+ "rk-019",+ "rk-020",+ "rk-021",+ "rk-022",+ "rk-023",+ "rk-024",+ "rk-025",+ "rk-027",+ "rk-029",+ "rk-030",+ "rk-031",+ "rk-032",+ "rk-034",+ "rk-035",+ "rk-036",+ "rk-037",+ "rk-040",+ "rk-041",+ "rk-042",+ ]),+ }),+ fixture_hash: "1c0553c47a2288b35bdd4c54a234ffa12642290d4a337d122020d96441615308",+ metric: DECISION_EVAL_METRIC,+ ceiling: 0.05,+ min_counted: 30,+ // The enforced reorder consults no probability floor in+ // questions.ts; the no-regression rule carries the quality burden.+ thresholds: Object.freeze({}),+ }),+ recall_inject: Object.freeze({+ version: DECISION_EVAL_SPEC_VERSION,+ use: "recall_inject",+ fixture: "tests/fixtures/decision-model/recall-inject-take.json",+ seed: "cycle-20261020",+ split: Object.freeze({+ rule: DECISION_EVAL_SPLIT_RULE,+ dev_fraction: DECISION_EVAL_DEV_FRACTION,+ }),+ receipt: Object.freeze({+ dev: Object.freeze([+ "ri-001",+ "ri-003",+ "ri-006",+ "ri-008",+ "ri-011",+ "ri-020",+ "ri-021",+ "ri-024",+ "ri-027",+ ]),+ counted: Object.freeze([+ "ri-002",+ "ri-004",+ "ri-005",+ "ri-007",+ "ri-009",+ "ri-010",+ "ri-012",+ "ri-013",+ "ri-014",+ "ri-015",+ "ri-016",+ "ri-017",+ "ri-018",+ "ri-019",+ "ri-022",+ "ri-023",+ "ri-025",+ "ri-026",+ "ri-028",+ "ri-029",+ ]),+ }),+ fixture_hash: "396e5e459d3a30ab5dd5c0df9d73187c42a6e9348b91f98868a195d66a850e93",+ metric: DECISION_EVAL_METRIC,+ // A dropped useful note is lost context: the target is zero regret,+ // exactly what the extract_prefilter report family demands.+ ceiling: 0,+ min_counted: 20,+ // Pinned to the enforce floors this use actually reads.+ thresholds: Object.freeze({+ any_min: RECALL_INJECT_ANY_MIN,+ note_min: RECALL_INJECT_NOTE_MIN,+ }),+ }),+ });++/** The spec registered for `use`, or null when none is (yet). */+export function decisionEvalSpecFor(use: DecisionModelUse): DecisionEvalSpec | null {+ return DECISION_EVAL_SPECS[use] ?? null;+}diff --git a/src/core/decision-model/eval/grade.ts b/src/core/decision-model/eval/grade.tsnew file mode 100644index 00000000..dfbc2741--- /dev/null+++ b/src/core/decision-model/eval/grade.ts@@ -0,0 +1,536 @@+/**+ * The graded eval runner behind the preregistered decision-model specs+ * (cycle 20261020, card t_4e1681b3, task C2) - in the+ * `runRerankEvalGate` mold.+ *+ * Before anything is sent, the runner verifies the preregistration: the+ * spec's fixture must still hash to the frozen fixture hash and derive+ * exactly the frozen dev/counted membership (`verifyEvalTake`). It then+ * runs one decision request per take item - one `runDecision` per item,+ * with `recordOrigin: "eval"` so the calls count toward the daily cost+ * gate but stay out of the rerank shadow agreement - scores each answer+ * with the deterministic canonical scorer (an external judge, when one+ * exists, is advisory and never moves the metric), and caches the+ * verdicts as `decision_model_eval_grade` records stamped with the spec+ * hash and the correlated per-item call ids.+ *+ * Scoring, frozen with the spec grammar:+ * - `rerank`: the enforced reorder's own semantics (movable slots+ * filled by relevance probability, ties by index, unanswered+ * candidates pinned at their heuristic index). The verdict per item+ * is top-1 relevance. Baseline: the input order's top-1.+ * - `recall_inject`: regret - a gold-useful note whose `helps`+ * probability falls below the pinned `note_min` floor would be+ * dropped in `enforce`, and an `inject_any` answer below the pinned+ * `any_min` would withhold the whole brief - a regret only when the+ * item carries at least one gold-useful note, since withholding a+ * brief over notes none of which is useful loses nothing. The+ * verdict per item is the enforced filter's own outcome+ * (`recallInjectFilterOutcome`). Baseline: the deterministic path+ * drops nothing, so regret 0.+ *+ * The verdict is the preregistered three-arm rule: promote only when the+ * counted error meets the spec's ceiling, does not regress against the+ * baseline, and the counted n is met; a short counted n is its own arm+ * (`not_enough_evidence`), never a pass.+ *+ * On a `promote` verdict - and only then, and only for a named threshold+ * profile, only when a grade record exists to review the mark against,+ * and only when the day's recorded spend stayed under the daily cost+ * gate - the runner writes the machine-side tuning mark+ * (`eval/mark.ts`) under the caller-supplied state root, making it the+ * one code path that can mark a profile tuned. The vault's grade record+ * is the review evidence; the mark is the gate input.+ *+ * The gate also lets go: a COMPLETED run whose verdict is not `promote`+ * (a `hold`, or `not_enough_evidence`) retracts the mark that the same+ * profile, use and spec earned earlier, so a later failing measurement+ * never leaves an older promote armed. A refused or errored run - the+ * throws above - retracts nothing: it measured nothing.+ */++import { randomUUID } from "node:crypto";++import type { DecisionModelUse, DecisionProvider } from "../contract.ts";+import type { ResolvedDecisionModelConfig } from "../config-types.ts";+import {+ decisionEvalSpecFor,+ decisionEvalSpecHash,+ type DecisionEvalSpec,+ type DecisionEvalVerdict,+} from "../eval-spec.ts";+import { RECALL_INJECT_QUESTIONS, RERANK_QUESTIONS } from "../questions.ts";+import { recallInjectFilterOutcome } from "../../brain/recall-inject.ts";+import { emitDecisionModelEvalGrade, listDecisionModelCalls, todaySpendUsd } from "../record.ts";+import { runDecision } from "../run.ts";+import { clip } from "../state.ts";+import type { PlatformDirsEnv } from "../../platform-dirs.ts";+import {+ decisionModelBaseUrlHash,+ decisionModelTuningMarkPath,+ retractTuningMark,+ writeTuningMark,+ type DecisionTuningMark,+} from "./mark.ts";+import { loadDecisionEvalFixture, verifyEvalTake, type DecisionEvalItem } from "./take.ts";++type ItemAnswers = Readonly<+ Record<string, { readonly valid: boolean; readonly value: number | string }>+>;++/** One take item's scoring outcome. */+interface ItemOutcome {+ readonly id: string;+ readonly split: "dev" | "counted";+ /** No usable answer arrived: the item shrinks n instead of counting as a miss. */+ readonly degraded: boolean;+ /** Scorer verdict (top-1 relevance / regret-freeness); false when degraded. */+ readonly verdict: boolean;+ /** The deterministic baseline's verdict on the same item. */+ readonly baseline: boolean;+}++export interface DecisionEvalRunResult {+ readonly use: DecisionModelUse;+ readonly profile: string | null;+ readonly seed: string;+ readonly spec_hash: string;+ readonly fixture_hash: string;+ readonly metric: string;+ readonly ceiling: number;+ readonly min_counted: number;+ readonly dev: { readonly n: number; readonly error: number | null };+ readonly counted: { readonly n: number; readonly error: number | null };+ readonly degraded_n: number;+ readonly baseline_error: number | null;+ readonly verdict: DecisionEvalVerdict;+ readonly counted_ids: ReadonlyArray<string>;+ readonly verdicts: Readonly<Record<string, boolean>>;+ readonly call_ids: ReadonlyArray<string>;+ readonly grade_record_id: string | null;+ /** True exactly when a `promote` verdict wrote the machine-side mark. */+ readonly mark_written: boolean;+ /**+ * True exactly when a completed non-promote verdict deleted the+ * matching earlier mark for this (profile, use, spec) - the gate has+ * gone back to shadow.+ */+ readonly mark_retracted: boolean;+ /** Why no mark was written, when one was not; null on a written mark. */+ readonly mark_note: string | null;+}++export interface DecisionEvalRunOptions {+ /** The resolved decision-model config; must be `active` to send anything. */+ readonly config: ResolvedDecisionModelConfig;+ /** Injected provider (tests). Defaults to the configured adapter. */+ readonly provider?: DecisionProvider;+ readonly env?: Readonly<Record<string, string | undefined>>;+ readonly now?: Date;+ /**+ * The spec to run. Defaults to the registry entry for the use; an+ * explicit spec must still verify against the same fixture.+ */+ readonly spec?: DecisionEvalSpec;+ /**+ * Where a `promote` verdict writes the machine-side tuning mark - and+ * a completed non-promote verdict retracts one: the eval CLI passes+ * the running process's platform dirs. Absent or null (every test, and+ * any caller measuring without deciding) disables mark writing and+ * retraction alike - a run that only measures leaves no gate input+ * behind and changes none.+ */+ readonly markSource?: PlatformDirsEnv | null;+}++function errorRate(fails: number, n: number): number | null {+ return n === 0 ? null : fails / n;+}++/**+ * Whether the vault's recorded spend for `now`'s UTC day - the whole+ * day's total, this run's records included - has reached `gate`. A day+ * total that cannot be read counts as over the gate (the gate's own+ * stance on an unreadable log), so a broken call log refuses the mark+ * by name instead of throwing past the measurement and the grade record+ * the run has already written.+ */+function spendAtOrOverGate(vault: string, now: Date, gate: number): boolean {+ try {+ return todaySpendUsd(vault, now) >= gate;+ } catch {+ return true;+ }+}++/**+ * The enforced rerank order's top index - `decisionRerankOrder` at floor+ * 0: movable slots fill from the score-sorted candidates (ties by+ * index), an unanswered candidate at index 0 is pinned there. Null only+ * when no usable answer arrived at all, so the item degrades instead of+ * silently matching the input-order baseline.+ */+function rerankTopIndex(probs: ReadonlyArray<number | null>): number | null {+ if (probs.every((p) => p === null)) return null;+ if (probs[0] === null) return 0;+ let best = -1;+ let bestP = -1;+ probs.forEach((p, i) => {+ if (p !== null && p > bestP) {+ best = i;+ bestP = p;+ }+ });+ return best < 0 ? null : best;+}++/** Score one rerank item: top-1 relevance after the enforced reorder. */+function scoreRerank(+ item: Extract<DecisionEvalItem, { kind: "rerank" }>,+ answers: ItemAnswers,+): { verdict: boolean; baseline: boolean; degraded: boolean } {+ const probs = item.candidates.map((_, k) => {+ const a = answers[RERANK_QUESTIONS.relevanceId(k)];+ return a?.valid === true && typeof a.value === "number" ? a.value : null;+ });+ const top = rerankTopIndex(probs);+ if (top === null) {+ return { verdict: false, baseline: item.candidates[0]!.relevant, degraded: true };+ }+ return {+ verdict: item.candidates[top]!.relevant,+ baseline: item.candidates[0]!.relevant,+ degraded: false,+ };+}++/**+ * Score one recall_inject item: regret-freeness against the pinned floor.+ * Exported for the regret-rule pins: the committed fixture grammar+ * requires every item to carry a useful note, so the no-useful-note+ * half of the rule is only reachable through a direct call.+ */+export function scoreRecall(+ item: Extract<DecisionEvalItem, { kind: "recall_inject" }>,+ answers: ItemAnswers,+): { verdict: boolean; baseline: boolean; degraded: boolean } {+ // The deterministic baseline drops nothing: its regret is zero by+ // construction, which is exactly the bar the decision arm must meet.+ // Canonical scoring: every answer is collected before anything is+ // decided, so an early slot without a usable answer cannot mask a+ // later slot's valid below-floor answer - the note enforce really+ // would drop. The verdict itself is the enforced filter's own outcome+ // (`recallInjectFilterOutcome`), including its inject_any abstain arm:+ // the eval sends every note, the only situation where that arm fires.+ const helps = item.notes.map((_, k) => {+ const a = answers[RECALL_INJECT_QUESTIONS.helpsId(k)];+ return a?.valid === true && typeof a.value === "number" ? a.value : null;+ });+ const any = answers[RECALL_INJECT_QUESTIONS.injectAnyId];+ const injectAny = any?.valid === true && typeof any.value === "number" ? any.value : null;+ const { abstain, keep } = recallInjectFilterOutcome(+ helps,+ item.notes.map(() => true),+ injectAny,+ );+ const droppedUseful = item.notes.some((n, k) => n.useful && keep[k] === false);+ // Abstaining loses nothing on an item none of whose notes is+ // gold-useful - the brief it withholds carries no note worth having -+ // so only an abstain over a gold-useful note is a counted failure+ // (regret is losing a gold-useful note, nothing else).+ const hasUseful = item.notes.some((n) => n.useful);+ if (droppedUseful || (abstain && hasUseful)) {+ return { verdict: false, baseline: true, degraded: false };+ }+ const unansweredUseful = item.notes.some((n, k) => n.useful && helps[k] === null);+ if (unansweredUseful) return { verdict: false, baseline: true, degraded: true };+ return { verdict: true, baseline: true, degraded: false };+}++/**+ * Run the preregistered eval for `use`. Sends exactly one request per+ * take item, after verifying the preregistration, and caches the verdict+ * set as a grade record. Never throws on model failures - degraded items+ * shrink the counted n; throws on a broken preregistration or an+ * inactive config.+ */+export async function runDecisionModelEval(+ use: DecisionModelUse,+ opts: DecisionEvalRunOptions,+): Promise<DecisionEvalRunResult> {+ const spec = opts.spec ?? decisionEvalSpecFor(use);+ if (spec === null || spec === undefined) {+ throw new Error(`decision-model eval: no preregistered spec for use '${use}'`);+ }+ if (spec.use !== use) {+ throw new Error(`decision-model eval: spec names use '${spec.use}', not '${use}'`);+ }+ const cfg = opts.config;+ if (cfg.status !== "active") {+ throw new Error(+ `decision-model eval: the config is '${cfg.status}', not active; ` ++ "run `o2b decision-model check` for what is missing",+ );+ }+ const { fixture, contentHash } = loadDecisionEvalFixture(spec.fixture, spec.use);+ verifyEvalTake(spec, fixture, contentHash);+ const countedSet = new Set(spec.receipt.counted);++ // Eval requests are real spend but not shadow data: the rerank eval+ // gate's own stance, kept here.+ const evalCfg: ResolvedDecisionModelConfig = { ...cfg, recordOrigin: "eval" };+ // Run-scoped correlation token, stamped into every call record this+ // run writes: a vault that has seen earlier eval runs holds eval-origin+ // records with the same item ids, and the grade's call_ids must list+ // only this grading run's requests.+ const evalRunToken = randomUUID();+ const outcomes: ItemOutcome[] = [];++ for (const item of fixture.items) {+ const built =+ item.kind === "rerank"+ ? {+ kind: "ok" as const,+ state: {+ query: item.query,+ passages: Object.fromEntries(+ item.candidates.map((c, k) => [+ `${RERANK_QUESTIONS.prefix}${k}`,+ clip(`${c.title}\n${c.text}`, RERANK_QUESTIONS.clipChars),+ ]),+ ),+ },+ candidateCount: item.candidates.length,+ context: null,+ }+ : {+ kind: "ok" as const,+ state: {+ prompt: item.prompt,+ notes: Object.fromEntries(+ item.notes.map((n, k) => [+ `${RECALL_INJECT_QUESTIONS.prefix}${k}`,+ clip(`${n.title}\n${n.text}`, RECALL_INJECT_QUESTIONS.clipChars),+ ]),+ ),+ },+ candidateCount: item.notes.length,+ context: null,+ };+ const questions =+ item.kind === "rerank"+ ? Object.fromEntries(+ item.candidates.map((_, k) => [+ RERANK_QUESTIONS.relevanceId(k),+ RERANK_QUESTIONS.relevance(k),+ ]),+ )+ : Object.fromEntries([+ ...item.notes.map((_, k) => [+ RECALL_INJECT_QUESTIONS.helpsId(k),+ RECALL_INJECT_QUESTIONS.helps(k),+ ]),+ // The one question over all notes the enforce path asks too;+ // its answer drives the abstain arm the metric grades.+ [RECALL_INJECT_QUESTIONS.injectAnyId, RECALL_INJECT_QUESTIONS.injectAny()],+ ]);+ const result = await runDecision<null>(+ use,+ () => built,+ () => questions,+ {+ config: evalCfg,+ ...(opts.provider !== undefined ? { provider: opts.provider } : {}),+ ...(opts.env !== undefined ? { env: opts.env } : {}),+ // The eval measures what `enforce` would do, whatever the operator+ // configured: a shadow arm would measure nothing.+ modeOverride: "enforce",+ ...(opts.now !== undefined ? { now: () => opts.now! } : {}),+ recordDetails: () => ({ item_id: item.id, eval_run: evalRunToken }),+ },+ );+ const scored =+ result.status === "ok"+ ? item.kind === "rerank"+ ? scoreRerank(item, result.response.answers)+ : scoreRecall(item, result.response.answers)+ : {+ verdict: false,+ baseline: item.kind === "rerank" ? item.candidates[0]!.relevant : true,+ degraded: true,+ };+ outcomes.push({+ id: item.id,+ split: countedSet.has(item.id) ? "counted" : "dev",+ degraded: scored.degraded,+ verdict: scored.verdict,+ baseline: scored.baseline,+ });+ }++ const aggregate = (+ split: "dev" | "counted",+ ): { n: number; error: number | null; baselineFails: number } => {+ const items = outcomes.filter((o) => o.split === split && !o.degraded);+ const fails = items.filter((o) => !o.verdict).length;+ const baselineFails = items.filter((o) => !o.baseline).length;+ return { n: items.length, error: errorRate(fails, items.length), baselineFails };+ };+ const countedAgg = aggregate("counted");+ const devAgg = aggregate("dev");+ const countedError = countedAgg.error;+ const baselineError = errorRate(countedAgg.baselineFails, countedAgg.n);+ const verdict: DecisionEvalVerdict =+ countedAgg.n < spec.min_counted+ ? "not_enough_evidence"+ : countedError !== null &&+ baselineError !== null &&+ countedError <= spec.ceiling &&+ countedError <= baselineError+ ? "promote"+ : "hold";+ const degradedN = outcomes.filter((o) => o.degraded).length;+ const verdictsById = Object.fromEntries(+ outcomes.filter((o) => o.split === "counted").map((o) => [o.id, o.verdict]),+ );+ // Correlate the grade with the real recorded requests: only this run's+ // eval-origin calls, matched by the run token they carry (item ids+ // alone would also match every earlier run on the same vault).+ const callIds =+ cfg.vault === null+ ? []+ : listDecisionModelCalls(cfg.vault)+ .filter(+ (r) =>+ r.payload["origin"] === "eval" &&+ r.payload["eval_run"] === evalRunToken &&+ typeof r.payload["item_id"] === "string" &&+ outcomes.some((o) => o.id === r.payload["item_id"]),+ )+ .map((r) => r.id);++ const record = emitDecisionModelEvalGrade(cfg.vault, {+ profile: cfg.thresholdProfile ?? null,+ use,+ specHash: decisionEvalSpecHash(spec),+ fixtureHash: spec.fixture_hash,+ seed: spec.seed,+ metric: spec.metric,+ ceiling: spec.ceiling,+ minCounted: spec.min_counted,+ countedN: countedAgg.n,+ countedError,+ baselineError,+ devError: devAgg.error,+ verdict,+ devIds: [...spec.receipt.dev],+ countedIds: [...spec.receipt.counted],+ verdicts: verdictsById,+ callIds,+ ...(opts.now !== undefined ? { createdAt: opts.now.toISOString() } : {}),+ });++ // The mark is the gate input and this is its only writer: a promote+ // verdict, a named profile, a state root to write under, a grade+ // record to review it against, and a day's recorded spend that stayed+ // under the daily cost gate. A failed write - or a day total that+ // cannot be read - is reported, never thrown: the measurement already+ // happened and the spend is already counted. The gate also lets go: a+ // completed non-promote measurement retracts the matching earlier+ // mark, so a use that missed its bar never keeps an older promote+ // armed while the CLI text suggests the gate is off.+ const profile = cfg.thresholdProfile ?? null;+ let markWritten = false;+ let markRetracted = false;+ let markNote: string | null = null;+ const now = opts.now ?? new Date();+ if (verdict !== "promote") {+ // A completed run - the refusals above throw, so reaching this line+ // is completing - whose verdict is not promote withdraws the mark+ // this (profile, use, spec) earned earlier. The same guard rails as+ // the write apply as far as they can: without a profile or a state+ // root there is nothing to retract, and a mark earned by another+ // spec is not this run's to delete.+ try {+ markRetracted = retractTuningMark(opts.markSource, profile, use, decisionEvalSpecHash(spec));+ } catch (err) {+ markNote = `the previous tuning mark could not be retracted: ${(err as Error).message}`;+ }+ if (markNote === null) {+ markNote = markRetracted+ ? `verdict is '${verdict}'; the earlier tuning mark was retracted, ` ++ "so the use runs shadow until a promote measures it again"+ : `verdict is '${verdict}'; only a promote writes a tuning mark`;+ }+ } else if (profile === null) {+ markNote =+ "the config carries no threshold profile, so there is no (profile, use) pair to mark";+ } else if (opts.markSource === null || opts.markSource === undefined) {+ markNote = "no state root was provided, so the run measured without marking";+ } else if (record === null) {+ // The vault's grade records are the review evidence a reviewer+ // audits the mark against; without one the promote is refused by+ // name instead of arming enforce on nothing.+ markNote =+ "no grade record was written (no vault configured, or the record write failed), " ++ "so the promote has no review evidence to mark";+ } else if (+ cfg.vault !== null &&+ cfg.dailyCostGateUsd > 0 &&+ spendAtOrOverGate(cfg.vault, now, cfg.dailyCostGateUsd)+ ) {+ markNote =+ `today's recorded spend reached the daily cost gate (${cfg.dailyCostGateUsd} USD) ` ++ `or could not be read; the mark waits for a run that stays under it`;+ } else {+ const mark: DecisionTuningMark = {+ profile,+ use,+ spec_hash: decisionEvalSpecHash(spec),+ fixture_hash: spec.fixture_hash,+ thresholds: spec.thresholds,+ metric: spec.metric,+ counted_n: countedAgg.n,+ counted_error: countedError,+ baseline_error: baselineError,+ verdict: "promote",+ created_at: now.toISOString(),+ // The endpoint binding: this config - and only this config, until+ // the operator changes it - may arm enforce off the mark. A null+ // provider or model cannot occur on an active config, but an empty+ // string recorded here would simply never match a later resolution.+ provider: cfg.provider ?? "",+ model: cfg.model ?? "",+ base_url_hash: decisionModelBaseUrlHash(cfg.baseUrl),+ };+ try {+ writeTuningMark(decisionModelTuningMarkPath(opts.markSource, profile, use), mark);+ markWritten = true;+ } catch (err) {+ markNote = `the tuning mark could not be written: ${(err as Error).message}`;+ }+ }++ return {+ use,+ profile: cfg.thresholdProfile ?? null,+ seed: spec.seed,+ spec_hash: decisionEvalSpecHash(spec),+ fixture_hash: spec.fixture_hash,+ metric: spec.metric,+ ceiling: spec.ceiling,+ min_counted: spec.min_counted,+ dev: { n: devAgg.n, error: devAgg.error },+ counted: { n: countedAgg.n, error: countedError },+ degraded_n: degradedN,+ baseline_error: baselineError,+ verdict,+ counted_ids: [...spec.receipt.counted],+ verdicts: verdictsById,+ call_ids: callIds,+ grade_record_id: record?.id ?? null,+ mark_written: markWritten,+ mark_retracted: markRetracted,+ mark_note: markNote,+ };+}diff --git a/src/core/decision-model/eval/mark.ts b/src/core/decision-model/eval/mark.tsnew file mode 100644index 00000000..d8b21e64--- /dev/null+++ b/src/core/decision-model/eval/mark.ts@@ -0,0 +1,277 @@+/**+ * The machine-side tuning mark (cycle 20261020, card t_4e1681b3).+ *+ * One small file per (threshold profile, use) under the platform state+ * root - outside every vault - recording that the preregistered eval+ * met its bar for that pair. The config resolver consults it ONLY when+ * the source table in `questions.ts` says the use is untuned, so a+ * hand-registered tune always wins and the hot-path cost is one TTL+ * cached file read per pair per minute (the `SPEND_CACHE_TTL_MS`+ * precedent).+ *+ * The mark is the GATE INPUT; the vault's `decision_model_eval_grade`+ * records are the review evidence a reviewer audits it against. The+ * runner (`eval/grade.ts`) is the only writer: a `promote` verdict+ * writes the mark, and a completed non-promote measurement retracts a+ * matching one - a use that missed its bar must not keep an earlier+ * mark armed. Acceptance is fail-closed: the mark is honored only+ * when its spec hash, fixture hash and pinned threshold values all match+ * the installed spec - a spec edited after the mark was written, a+ * fixture that moved, or thresholds that drifted each put the use back+ * in shadow. No mark file is exactly today's behavior.+ *+ * The mark is also bound to the endpoint that earned it. It records the+ * decision provider id, the pinned model id and a hash of the base URL+ * of the config whose measurement promoted, and the gate reader+ * (`machineTunedMarkReader`) refuses a mark whose recorded endpoint+ * differs from the config being resolved - a promote measured on one+ * model never arms enforce for another, at another URL, or under+ * another provider. Marks written before the binding existed carry no+ * endpoint fields and parse as no mark: fail closed, shadow.+ */++import { mkdirSync, readFileSync } from "node:fs";+import { dirname, join } from "node:path";++import { atomicWriteFileSync, unlinkWithRetry } from "../../fs-atomic.ts";+import { sha256Hex } from "../../integrity/digest.ts";+import {+ decisionModelStateDir,+ processDirsEnv,+ type PlatformDirsEnv,+} from "../../platform-dirs.ts";+import type { DecisionModelUse } from "../contract.ts";+import { decisionEvalSpecFor, decisionEvalSpecHash, type DecisionEvalSpec } from "../eval-spec.ts";++/** The only verdict a mark may carry, by construction of the writer. */+const PROMOTE = "promote";++/** sha-256 hex digest length, for the recorded base-URL hash. */+const HASH_HEX_RE = /^[0-9a-f]{64}$/;++export interface DecisionTuningMark {+ readonly profile: string;+ readonly use: DecisionModelUse;+ readonly spec_hash: string;+ readonly fixture_hash: string;+ /** The pinned threshold values the use was measured against. */+ readonly thresholds: Readonly<Record<string, number>>;+ readonly metric: string;+ readonly counted_n: number;+ readonly counted_error: number | null;+ readonly baseline_error: number | null;+ readonly verdict: typeof PROMOTE;+ readonly created_at: string;+ /** The decision provider id whose measurement earned the mark. */+ readonly provider: string;+ /** The pinned model id that was measured. */+ readonly model: string;+ /**+ * sha-256 of the measured base URL - a hash, never the URL itself.+ * Marks written before these three fields existed are refused at+ * parse time: an endpoint no one can prove is a mark no one arms.+ */+ readonly base_url_hash: string;+}++/**+ * The decision endpoint a mark is checked against: the resolved+ * config's provider id, pinned model id and base URL. A `null` field+ * never matches a recorded one.+ */+export interface DecisionMarkEndpoint {+ readonly provider: string | null;+ readonly model: string | null;+ readonly baseUrl: string | null;+}++/** The base-URL binding recorded in a mark: a digest, never the URL. */+export function decisionModelBaseUrlHash(baseUrl: string | null | undefined): string {+ return sha256Hex(baseUrl ?? "");+}++/** The mark file for one (profile, use) pair. */+export function decisionModelTuningMarkPath(+ source: PlatformDirsEnv,+ profile: string,+ use: DecisionModelUse,+): string {+ return join(decisionModelStateDir(source), "tuning-marks", profile, `${use}.json`);+}++/** Write one mark atomically; the next read sees it immediately. */+export function writeTuningMark(path: string, mark: DecisionTuningMark): void {+ mkdirSync(dirname(path), { recursive: true });+ atomicWriteFileSync(path, `${JSON.stringify(mark, null, 2)}\n`);+ MARK_CACHE.delete(path);+}++/**+ * Delete the tuning mark for (profile, use) - but only one whose spec+ * hash matches `specHash`, i.e. a mark this exact spec earned; a+ * measurement under another spec does not speak for it. Reports whether+ * a matching mark was deleted: false when there is no state root, no+ * profile (no pair to retract), no mark, or a foreign-spec mark. The+ * deletion is immediately visible to the next read, cached or not.+ */+export function retractTuningMark(+ source: PlatformDirsEnv | null | undefined,+ profile: string | null,+ use: DecisionModelUse,+ specHash: string,+ nowMs: number = Date.now(),+): boolean {+ if (source === null || source === undefined || profile === null) return false;+ const path = decisionModelTuningMarkPath(source, profile, use);+ const mark = readTuningMark(path, nowMs);+ if (mark === null || mark.spec_hash !== specHash) return false;+ unlinkWithRetry(path);+ MARK_CACHE.delete(path);+ return true;+}++/** Parse one mark document. Anything malformed parses as no mark (fail closed). */+function parseTuningMark(text: string): DecisionTuningMark | null {+ let raw: unknown;+ try {+ raw = JSON.parse(text);+ } catch {+ return null;+ }+ if (raw === null || typeof raw !== "object" || Array.isArray(raw)) return null;+ const m = raw as Record<string, unknown>;+ if (+ typeof m["profile"] !== "string" ||+ typeof m["use"] !== "string" ||+ typeof m["spec_hash"] !== "string" ||+ typeof m["fixture_hash"] !== "string" ||+ typeof m["metric"] !== "string" ||+ typeof m["created_at"] !== "string" ||+ m["verdict"] !== PROMOTE ||+ typeof m["counted_n"] !== "number" ||+ // The endpoint binding: a mark that cannot name the provider, the+ // pinned model and the base-URL hash it was measured on is refused+ // here, so pre-binding marks fail closed to shadow.+ typeof m["provider"] !== "string" ||+ m["provider"].trim() === "" ||+ typeof m["model"] !== "string" ||+ m["model"].trim() === "" ||+ typeof m["base_url_hash"] !== "string" ||+ !HASH_HEX_RE.test(m["base_url_hash"]) ||+ m["thresholds"] === null ||+ typeof m["thresholds"] !== "object" ||+ Array.isArray(m["thresholds"]) ||+ !Object.values(m["thresholds"]).every((v) => typeof v === "number" && Number.isFinite(v))+ ) {+ return null;+ }+ for (const key of ["counted_error", "baseline_error"] as const) {+ const v = m[key];+ if (v !== null && typeof v !== "number") return null;+ }+ return {+ profile: m["profile"],+ use: m["use"] as DecisionModelUse,+ spec_hash: m["spec_hash"],+ fixture_hash: m["fixture_hash"],+ thresholds: m["thresholds"] as Readonly<Record<string, number>>,+ metric: m["metric"],+ counted_n: m["counted_n"],+ counted_error: m["counted_error"] as number | null,+ baseline_error: m["baseline_error"] as number | null,+ verdict: PROMOTE,+ created_at: m["created_at"],+ provider: m["provider"],+ model: m["model"],+ base_url_hash: m["base_url_hash"],+ };+}++/**+ * Read one mark file through the TTL cache. Anything unreadable or+ * malformed reads as no mark (fail closed) - and that absence is cached+ * too, so a missing file costs one stat-and-read per {@link+ * TUNING_MARK_CACHE_TTL_MS}, not one per request. {@link writeTuningMark}+ * drops the cache entry it wrote so the next read sees it immediately.+ */+export function readTuningMark(+ path: string,+ nowMs: number = Date.now(),+): DecisionTuningMark | null {+ const hit = MARK_CACHE.get(path);+ if (hit !== undefined && nowMs - hit.loadedAtMs < TUNING_MARK_CACHE_TTL_MS) return hit.mark;+ let mark: DecisionTuningMark | null = null;+ try {+ mark = parseTuningMark(readFileSync(path, "utf8"));+ } catch {+ mark = null;+ }+ MARK_CACHE.set(path, { mark, loadedAtMs: nowMs });+ return mark;+}++/**+ * How long a loaded mark is trusted before its file is read again. A+ * deleted mark takes effect within this window - failing closed shortly+ * after deletion, never failing open.+ */+export const TUNING_MARK_CACHE_TTL_MS = 60_000;++const MARK_CACHE = new Map<string, { mark: DecisionTuningMark | null; loadedAtMs: number }>();++/** Tests only: forget every loaded mark. */+export function resetTuningMarkCache(): void {+ MARK_CACHE.clear();+}++/**+ * The validated mark for (profile, use), or null. Every axis must match+ * the installed spec - spec hash, fixture hash, pinned threshold values,+ * the pair itself - and the verdict must be promote; when an `endpoint`+ * is supplied, its provider, model and base-URL hash must match the ones+ * recorded in the mark too. Anything else is no mark, and the use stays+ * in shadow.+ */+export function validatedTuningMark(+ profile: string | null,+ use: DecisionModelUse,+ source: PlatformDirsEnv = processDirsEnv(),+ spec: DecisionEvalSpec | null = decisionEvalSpecFor(use),+ nowMs: number = Date.now(),+ endpoint?: DecisionMarkEndpoint,+): DecisionTuningMark | null {+ if (profile === null || spec === null) return null;+ const mark = readTuningMark(decisionModelTuningMarkPath(source, profile, use), nowMs);+ if (mark === null) return null;+ if (mark.profile !== profile || mark.use !== use) return null;+ if (mark.spec_hash !== decisionEvalSpecHash(spec)) return null;+ if (mark.fixture_hash !== spec.fixture_hash) return null;+ if (JSON.stringify(mark.thresholds) !== JSON.stringify(spec.thresholds)) return null;+ if (mark.verdict !== PROMOTE) return null;+ if (+ endpoint !== undefined &&+ (mark.provider !== endpoint.provider ||+ mark.model !== endpoint.model ||+ mark.base_url_hash !== decisionModelBaseUrlHash(endpoint.baseUrl))+ ) {+ return null;+ }+ return mark;+}++/**+ * The reader shape `resolveDecisionModelConfig` threads to+ * `thresholdsTunedFor`: true only when a mark that matches the installed+ * spec AND the `endpoint` being resolved exists for the pair. Consulted+ * only when the source table says untuned, so a hand-registered tune+ * never pays the read. The endpoint binding is what keeps a promote+ * earned by one provider/model/base URL from arming enforce for+ * another.+ */+export function machineTunedMarkReader(+ endpoint: DecisionMarkEndpoint,+ source: PlatformDirsEnv = processDirsEnv(),+): (profile: string | null, use: DecisionModelUse) => boolean {+ return (profile, use) =>+ validatedTuningMark(profile, use, source, undefined, undefined, endpoint) !== null;+}diff --git a/src/core/decision-model/eval/take.ts b/src/core/decision-model/eval/take.tsnew file mode 100644index 00000000..06ba06d5--- /dev/null+++ b/src/core/decision-model/eval/take.ts@@ -0,0 +1,278 @@+/**+ * The seeded take and the hash-order dev/counted split behind the+ * preregistered decision-model evaluation (cycle 20261020, card t_4e1681b3).+ *+ * A take is a committed fixture of labeled items whose ids the spec+ * freezes into a membership receipt at preregistration time. The split+ * rule is fixed and pure: rank the ids by `sha256Hex(seed + ":" + id)`+ * (ties by id), the first `ceil(devFraction * n)` are dev, the rest+ * counted. Dev is the only split threshold selection may look at; the+ * counted split alone produces the promotion number.+ *+ * `verifyEvalTake` is the runner-side guard: the fixture the spec names+ * must still hold exactly the receipted ids in exactly the receipted+ * split and hash to exactly the receipted content hash, or the run is a+ * named preregistration error rather than a quietly re-scoped claim.+ *+ * The committed fixtures live under `tests/fixtures/decision-model/` in+ * the bench-fixture spirit: repo-local JSON, gold labels from a closed+ * vocabulary (`relevant` / `useful` booleans), validated fail-fast.+ */++import { readFileSync } from "node:fs";+import { isAbsolute, join } from "node:path";+import { fileURLToPath } from "node:url";++import { canonicalJson, sha256Hex } from "../../integrity/digest.ts";+import type { DecisionModelUse } from "../contract.ts";+import { DECISION_EVAL_DEV_FRACTION, type DecisionEvalSpec } from "../eval-spec.ts";++/** Repo root, for resolving the spec's repo-relative fixture references. */+const PACKAGE_ROOT = fileURLToPath(new URL("../../../..", import.meta.url));++// ----- fixture documents ------------------------------------------------------++export interface EvalRerankItem {+ readonly id: string;+ /** Exactly one candidate is relevant: the top-1 verdict is crisp. */+ readonly kind: "rerank";+ readonly query: string;+ readonly candidates: ReadonlyArray<{+ readonly title: string;+ readonly text: string;+ readonly relevant: boolean;+ }>;+}++export interface EvalRecallItem {+ readonly id: string;+ readonly kind: "recall_inject";+ readonly prompt: string;+ /** At least one note is useful: regret (a useful note dropped) is measurable. */+ readonly notes: ReadonlyArray<{+ readonly title: string;+ readonly text: string;+ readonly useful: boolean;+ }>;+}++export type DecisionEvalItem = EvalRerankItem | EvalRecallItem;++export interface DecisionEvalFixture {+ readonly use: DecisionModelUse;+ readonly description?: string;+ readonly items: ReadonlyArray<DecisionEvalItem>;+}++export interface LoadedEvalFixture {+ readonly fixture: DecisionEvalFixture;+ /** sha256 of the canonical fixture document - the spec's fixture_hash. */+ readonly contentHash: string;+}++interface ParsedRerankCandidate {+ title: string;+ text: string;+ relevant: boolean;+}++interface ParsedRecallNote {+ title: string;+ text: string;+ useful: boolean;+}++function asObject(value: unknown): Record<string, unknown> {+ if (value === null || typeof value !== "object" || Array.isArray(value)) {+ throw new Error("eval fixture: expected a JSON object");+ }+ return value as Record<string, unknown>;+}++function nonEmpty(value: unknown, what: string): string {+ if (typeof value !== "string" || value.trim() === "") {+ throw new Error(`eval fixture: ${what} must be a non-empty string`);+ }+ return value;+}++function bool(value: unknown, what: string): boolean {+ if (typeof value !== "boolean") throw new Error(`eval fixture: ${what} must be a boolean`);+ return value;+}++function parseRerankItem(raw: unknown): EvalRerankItem {+ const record = asObject(raw);+ const id = nonEmpty(record["id"], "item id");+ const query = nonEmpty(record["query"], `item ${id} query`);+ const candidatesRaw = record["candidates"];+ if (!Array.isArray(candidatesRaw) || candidatesRaw.length === 0) {+ throw new Error(`eval fixture: item ${id} needs a non-empty candidates array`);+ }+ const candidates: ParsedRerankCandidate[] = candidatesRaw.map((c) => {+ const cand = asObject(c);+ return {+ title: nonEmpty(cand["title"], `candidate title in ${id}`),+ text: nonEmpty(cand["text"], `candidate text in ${id}`),+ relevant: bool(cand["relevant"], `candidate relevant in ${id}`),+ };+ });+ if (!candidates.some((c) => c.relevant === true)) {+ throw new Error(+ `eval fixture: item ${id} has no relevant candidate; the top-1 verdict needs one`,+ );+ }+ return { id, kind: "rerank", query, candidates: Object.freeze(candidates) };+}++function parseRecallItem(raw: unknown): EvalRecallItem {+ const record = asObject(raw);+ const id = nonEmpty(record["id"], "item id");+ const prompt = nonEmpty(record["prompt"], `item ${id} prompt`);+ const notesRaw = record["notes"];+ if (!Array.isArray(notesRaw) || notesRaw.length === 0) {+ throw new Error(`eval fixture: item ${id} needs a non-empty notes array`);+ }+ const notes: ParsedRecallNote[] = notesRaw.map((n) => {+ const note = asObject(n);+ return {+ title: nonEmpty(note["title"], `note title in ${id}`),+ text: nonEmpty(note["text"], `note text in ${id}`),+ useful: bool(note["useful"], `note useful in ${id}`),+ };+ });+ if (!notes.some((n) => n.useful === true)) {+ throw new Error(`eval fixture: item ${id} has no useful note; the regret verdict needs one`);+ }+ return { id, kind: "recall_inject", prompt, notes: Object.freeze(notes) };+}++/** Parse and validate a fixture document. Throws named errors. */+export function parseDecisionEvalFixture(+ raw: unknown,+ expectedUse: DecisionModelUse,+): DecisionEvalFixture {+ const record = asObject(raw);+ const use = nonEmpty(record["use"], "use");+ if (use !== expectedUse) {+ throw new Error(`eval fixture: use '${use}' does not match the spec's use '${expectedUse}'`);+ }+ const itemsRaw = record["items"];+ if (!Array.isArray(itemsRaw) || itemsRaw.length === 0) {+ throw new Error("eval fixture: items must be a non-empty array");+ }+ const seen = new Set<string>();+ const items = itemsRaw.map((item) => {+ const parsed =+ expectedUse === "rerank"+ ? parseRerankItem(item)+ : expectedUse === "recall_inject"+ ? parseRecallItem(item)+ : null;+ if (parsed === null) {+ throw new Error(`eval fixture: no committed fixture grammar for use '${expectedUse}'`);+ }+ if (seen.has(parsed.id)) {+ throw new Error(`eval fixture: item id '${parsed.id}' appears more than once`);+ }+ seen.add(parsed.id);+ return parsed;+ });+ const description = record["description"];+ return Object.freeze({+ use: expectedUse,+ ...(typeof description === "string" && description.trim() !== "" ? { description } : {}),+ items: Object.freeze(items),+ });+}++/**+ * Resolve the spec's fixture reference: absolute paths as is, everything+ * else against the package root - the only relative spelling the+ * registry uses, and the one the installed package ships. There is no+ * working-directory fallback: a look-alike file at ./tests/fixtures/...+ * must never be hashed into a preregistration claim, and a fixture the+ * package does not carry is a named read error.+ */+export function resolveEvalFixturePath(ref: string): string {+ if (isAbsolute(ref)) return ref;+ return join(PACKAGE_ROOT, ref);+}++/** Load the spec's fixture file and hash its canonical document. */+export function loadDecisionEvalFixture(ref: string, use: DecisionModelUse): LoadedEvalFixture {+ let raw: unknown;+ try {+ raw = JSON.parse(readFileSync(resolveEvalFixturePath(ref), "utf8"));+ } catch (err) {+ throw new Error(`eval fixture: cannot read '${ref}': ${(err as Error).message}`);+ }+ return {+ fixture: parseDecisionEvalFixture(raw, use),+ contentHash: sha256Hex(canonicalJson(raw)),+ };+}++// ----- the hash-order split -----------------------------------------------------++export interface EvalTakeSplit {+ /** Dev ids, sorted lexicographically. Threshold selection may see these only. */+ readonly dev: ReadonlyArray<string>;+ /** Counted ids, sorted lexicographically. These alone produce the metric. */+ readonly counted: ReadonlyArray<string>;+}++/**+ * The preregistered split: rank ids by `sha256Hex(seed + ":" + id)` (ties+ * by id), the first `ceil(0.3 n)` are dev, the rest counted. Pure and+ * reorder-stable; both lists come back sorted lexicographically so a+ * receipt compares equal regardless of derivation order.+ */+export function hashOrderSplit(seed: string, ids: ReadonlyArray<string>): EvalTakeSplit {+ const ranked = ids+ .map((id) => ({ id, h: sha256Hex(`${seed}:${id}`) }))+ .toSorted((a, b) => (a.h < b.h ? -1 : a.h > b.h ? 1 : a.id.localeCompare(b.id)));+ const devCount = Math.ceil(ids.length * DECISION_EVAL_DEV_FRACTION);+ return {+ dev: ranked+ .slice(0, devCount)+ .map((e) => e.id)+ .toSorted(),+ counted: ranked+ .slice(devCount)+ .map((e) => e.id)+ .toSorted(),+ };+}++/**+ * The runner-side preregistration guard: the loaded fixture must hold+ * exactly the receipted ids in exactly the receipted split, and its+ * content must still hash to the spec's frozen fixture hash. Any+ * mismatch is a named error - the spec was edited after grades were+ * seen, or the fixture moved under it, and neither may quietly re-scope+ * the claim.+ */+export function verifyEvalTake(+ spec: Pick<DecisionEvalSpec, "seed" | "receipt" | "fixture_hash">,+ fixture: DecisionEvalFixture,+ contentHash: string,+): void {+ if (contentHash !== spec.fixture_hash) {+ throw new Error(+ `eval preregistration mismatch: fixture content hash ${contentHash.slice(0, 12)}… ` ++ `does not match the spec's frozen ${spec.fixture_hash.slice(0, 12)}…; ` ++ "the fixture changed after the spec was committed",+ );+ }+ const ids = fixture.items.map((item) => item.id);+ const derived = hashOrderSplit(spec.seed, ids);+ const same = (a: ReadonlyArray<string>, b: ReadonlyArray<string>): boolean =>+ a.length === b.length && a.every((id, i) => id === b[i]);+ if (!same(derived.dev, spec.receipt.dev) || !same(derived.counted, spec.receipt.counted)) {+ throw new Error(+ "eval preregistration mismatch: the fixture's take membership does not match the " ++ "spec's frozen receipt; the take changed after the spec was committed",+ );+ }+}diff --git a/src/core/decision-model/questions.ts b/src/core/decision-model/questions.tsindex 70dd0350..62686b4e 100644--- a/src/core/decision-model/questions.ts+++ b/src/core/decision-model/questions.ts@@ -131,11 +131,25 @@ export function isDecisionThresholdProfile(name: string): boolean {return Object.hasOwn(DECISION_THRESHOLD_PROFILES, name);}-/** Whether `use` has tuned thresholds on `profile`; false for an unknown or absent profile. */-export function thresholdsTunedFor(profile: string | null, use: DecisionModelUse): boolean {+/**+ * Whether `use` has tuned thresholds on `profile`; false for an unknown or absent profile.+ *+ * The source table decides first. Only when it says untuned is the+ * optional {@link measuredTuned} reader consulted - the machine-side+ * tuning mark of the preregistered evaluation (`eval/mark.ts`), whose read is+ * therefore never paid for a hand-registered or baseline use, and never+ * paid at all when no reader is injected (today's behavior, which the+ * hand-edit tests pin).+ */+export function thresholdsTunedFor(+ profile: string | null,+ use: DecisionModelUse,+ measuredTuned?: (() => boolean) | null,+): boolean {if (profile === null || !isDecisionThresholdProfile(profile)) return false;const tuned = DECISION_THRESHOLD_PROFILES[profile]!.tuned;- return tuned === "baseline" || tuned.includes(use);+ if (tuned === "baseline" || tuned.includes(use)) return true;+ return measuredTuned !== null && measuredTuned !== undefined && measuredTuned();}// ----- answerable (advisory, carried by the rerank request) -----------------diff --git a/src/core/decision-model/record.ts b/src/core/decision-model/record.tsindex 66b3905b..6dec408e 100644--- a/src/core/decision-model/record.ts+++ b/src/core/decision-model/record.ts@@ -32,6 +32,8 @@ import type {DecisionModelUse,DecisionUsage,} from "./contract.ts";+import { isDecisionModelUse } from "./contract.ts";+import { DECISION_EVAL_VERDICTS, type DecisionEvalVerdict } from "./eval-spec.ts";export const DECISION_MODEL_CALL_KIND = "decision_model_call";@@ -152,6 +154,241 @@ export function listDecisionModelExtractCommits(});}+// ----- eval grade records (preregistered eval, cycle 20261020) ---------------++/**+ * One cached verdict set of the preregistered evaluation (`eval/grade.ts`):+ * what the graded run measured, under which spec, for which profile and+ * use. These records are REVIEW EVIDENCE only - the authoritative+ * machine-consumed tuning mark lives outside the vault+ * (`eval/mark.ts`), and a hand-written grade record can never promote a+ * use on its own. Identifiers, numbers and booleans only.+ */+export const DECISION_MODEL_EVAL_GRADE_KIND = "decision_model_eval_grade";++/** Input for one grade record, as the eval runner produced it. */+export interface DecisionEvalGradeRecordInput {+ readonly profile: string | null;+ readonly use: DecisionModelUse;+ readonly specHash: string;+ readonly fixtureHash: string;+ readonly seed: string;+ readonly metric: string;+ readonly ceiling: number;+ readonly minCounted: number;+ readonly countedN: number;+ readonly countedError: number | null;+ readonly baselineError: number | null;+ readonly devError: number | null;+ readonly verdict: DecisionEvalVerdict;+ readonly devIds: ReadonlyArray<string>;+ readonly countedIds: ReadonlyArray<string>;+ /** Boolean scorer verdict per counted item id. */+ readonly verdicts: Readonly<Record<string, boolean>>;+ /** The correlated `decision_model_call` record ids, in run order. */+ readonly callIds: ReadonlyArray<string>;+ readonly createdAt?: string;+}++/** Emit one grade record; returns null when there is no vault or the write failed. */+export function emitDecisionModelEvalGrade(+ vault: string | null,+ input: DecisionEvalGradeRecordInput,+): ContinuityRecord | null {+ return emitGatedTelemetry(vault, (v) =>+ appendContinuityRecord(v, {+ kind: DECISION_MODEL_EVAL_GRADE_KIND,+ createdAt: input.createdAt ?? new Date().toISOString(),+ sourceRefs: [],+ payload: {+ use: input.use,+ ...(input.profile !== null ? { profile: input.profile } : {}),+ spec_hash: input.specHash,+ fixture_hash: input.fixtureHash,+ seed: input.seed,+ metric: input.metric,+ ceiling: input.ceiling,+ min_counted: input.minCounted,+ counted_n: input.countedN,+ counted_error: input.countedError,+ baseline_error: input.baselineError,+ dev_error: input.devError,+ verdict: input.verdict,+ dev_ids: [...input.devIds],+ counted_ids: [...input.countedIds],+ verdicts: { ...input.verdicts },+ call_ids: [...input.callIds],+ },+ }),+ );+}++/** The typed grade a well-formed record parses into. */+export interface DecisionEvalGrade {+ readonly recordId: string;+ readonly createdAt: string;+ readonly use: DecisionModelUse;+ readonly profile: string | null;+ readonly specHash: string;+ readonly fixtureHash: string;+ readonly seed: string;+ readonly metric: string;+ readonly ceiling: number;+ readonly minCounted: number;+ readonly countedN: number;+ readonly countedError: number | null;+ readonly baselineError: number | null;+ readonly devError: number | null;+ readonly verdict: DecisionEvalVerdict;+ readonly devIds: ReadonlyArray<string>;+ readonly countedIds: ReadonlyArray<string>;+ readonly verdicts: Readonly<Record<string, boolean>>;+ readonly callIds: ReadonlyArray<string>;+}++export type DecisionEvalGradeParse =+ | { readonly ok: true; readonly grade: DecisionEvalGrade }+ | { readonly ok: false; readonly note: string };++function stringAt(payload: Readonly<Record<string, unknown>>, key: string): string | null {+ const value = payload[key];+ return typeof value === "string" && value !== "" ? value : null;+}++function numberAt(payload: Readonly<Record<string, unknown>>, key: string): number | null {+ const value = payload[key];+ return typeof value === "number" && Number.isFinite(value) ? value : null;+}++function stringListAt(payload: Readonly<Record<string, unknown>>, key: string): string[] | null {+ const value = payload[key];+ return Array.isArray(value) && value.every((v) => typeof v === "string")+ ? (value as string[])+ : null;+}++/**+ * Parse one continuity record into a typed grade, or return a note that+ * names why it is malformed. A hand-written record missing any required+ * field never masquerades as a measurement.+ */+export function parseDecisionModelEvalGrade(record: ContinuityRecord): DecisionEvalGradeParse {+ const skip = (why: string): DecisionEvalGradeParse => ({+ ok: false,+ note: `${DECISION_MODEL_EVAL_GRADE_KIND} record ${record.id} skipped: ${why}`,+ });+ if (record.kind !== DECISION_MODEL_EVAL_GRADE_KIND) {+ return skip(`kind is '${record.kind}'`);+ }+ const p = record.payload;+ const use = p["use"];+ if (!isDecisionModelUse(use))+ return skip(`use ${JSON.stringify(use)} is not a decision-model use`);+ const specHash = stringAt(p, "spec_hash");+ if (specHash === null) return skip("spec_hash is missing or not a string");+ const fixtureHash = stringAt(p, "fixture_hash");+ if (fixtureHash === null) return skip("fixture_hash is missing or not a string");+ const seed = stringAt(p, "seed");+ if (seed === null) return skip("seed is missing or not a string");+ const metric = stringAt(p, "metric");+ if (metric === null) return skip("metric is missing or not a string");+ const ceiling = numberAt(p, "ceiling");+ if (ceiling === null) return skip("ceiling is missing or not a number");+ const minCounted = numberAt(p, "min_counted");+ if (minCounted === null) return skip("min_counted is missing or not a number");+ const countedN = numberAt(p, "counted_n");+ if (countedN === null) return skip("counted_n is missing or not a number");+ const countedError = p["counted_error"];+ if (countedError !== null && typeof countedError !== "number") {+ return skip("counted_error must be a number or null");+ }+ const baselineError = p["baseline_error"];+ if (baselineError !== null && typeof baselineError !== "number") {+ return skip("baseline_error must be a number or null");+ }+ const devError = p["dev_error"];+ if (devError !== null && typeof devError !== "number") {+ return skip("dev_error must be a number or null");+ }+ const verdictRaw = stringAt(p, "verdict");+ if (+ verdictRaw === null ||+ !(DECISION_EVAL_VERDICTS as ReadonlyArray<string>).includes(verdictRaw)+ ) {+ return skip(`verdict must be one of ${DECISION_EVAL_VERDICTS.join(", ")}`);+ }+ const devIds = stringListAt(p, "dev_ids");+ if (devIds === null) return skip("dev_ids is missing or not a string array");+ const countedIds = stringListAt(p, "counted_ids");+ if (countedIds === null) return skip("counted_ids is missing or not a string array");+ const verdictsRaw = p["verdicts"];+ if (+ verdictsRaw === null ||+ typeof verdictsRaw !== "object" ||+ Array.isArray(verdictsRaw) ||+ !Object.values(verdictsRaw).every((v) => typeof v === "boolean")+ ) {+ return skip("verdicts must be an object of booleans");+ }+ const callIds = stringListAt(p, "call_ids");+ if (callIds === null) return skip("call_ids is missing or not a string array");+ const profileRaw = p["profile"];+ const profile =+ profileRaw === undefined || profileRaw === null+ ? null+ : typeof profileRaw === "string"+ ? profileRaw+ : null;+ if (profileRaw !== undefined && profileRaw !== null && profile === null) {+ return skip("profile must be a string or null");+ }+ return {+ ok: true,+ grade: {+ recordId: record.id,+ createdAt: record.createdAt,+ use,+ profile,+ specHash,+ fixtureHash,+ seed,+ metric,+ ceiling,+ minCounted,+ countedN,+ countedError,+ baselineError,+ devError,+ verdict: verdictRaw as DecisionEvalVerdict,+ devIds,+ countedIds,+ verdicts: verdictsRaw as Readonly<Record<string, boolean>>,+ callIds,+ },+ };+}++/**+ * Cached grade records, oldest first, each parsed; a malformed record is+ * skipped with a named note instead of poisoning the list.+ */+export function listDecisionModelEvalGrades(+ vault: string,+ since?: string,+): { readonly grades: ReadonlyArray<DecisionEvalGrade>; readonly skipped: ReadonlyArray<string> } {+ const grades: DecisionEvalGrade[] = [];+ const skipped: string[] = [];+ for (const record of listContinuityRecords(vault, {+ kind: DECISION_MODEL_EVAL_GRADE_KIND,+ ...(since !== undefined ? { since } : {}),+ })) {+ const parsed = parseDecisionModelEvalGrade(record);+ if (parsed.ok) grades.push(parsed.grade);+ else skipped.push(parsed.note);+ }+ return { grades, skipped };+}+/** Start of the current UTC day, canonical ISO form. */export function utcDayStart(now: Date = new Date()): string {return `${now.toISOString().slice(0, 10)}T00:00:00.000Z`;diff --git a/src/core/doctor-readiness.ts b/src/core/doctor-readiness.tsindex dfe21d23..58bc9d43 100644--- a/src/core/doctor-readiness.ts+++ b/src/core/doctor-readiness.ts@@ -77,8 +77,14 @@import { readFileSync } from "node:fs";import { discoverConfig } from "./config.ts";+import { homedir } from "node:os";import { resolveDecisionModelConfig } from "./decision-model/config.ts";-import { vaultDecisionModelWarnings } from "./decision-model/diagnostics.ts";+import {+ measuredTuning,+ measuredTuningSummary,+ vaultDecisionModelWarnings,+} from "./decision-model/diagnostics.ts";+import { processDirsEnv } from "./platform-dirs.ts";import {resolveSemanticCapability,SEMANTIC_CAPABILITY_CODE,@@ -435,14 +441,28 @@ async function decisionModelVerdict(opts: ReadinessOptions): Promise<ReadinessVereturn { status: READINESS_STATUS.skipped, detail: "opted out by this vault's _brain.yaml" };case "invalid":return { status: READINESS_STATUS.fail, detail: cfg.errors.join("; ") };- case "active":+ case "active": {+ // The tuning marks live under the state root the OPTIONS env+ // resolves to, not the probe process's ambient one - the same env+ // the config above was resolved from.+ const dirsEnv =+ opts.env === undefined+ ? processDirsEnv()+ : {+ platform: process.platform,+ home: opts.env["HOME"] ?? homedir(),+ env: opts.env as Readonly<Record<string, string | undefined>>,+ };+ const tuning = measuredTuningSummary(measuredTuning(cfg, dirsEnv));return {status: READINESS_STATUS.pass,detail:- cfg.keyPresent || cfg.keyRequired !== false+ (cfg.keyPresent || cfg.keyRequired !== false? `key present in ${cfg.envKey ?? "?"}, endpoint accepted (${cfg.provider ?? "?"} ${cfg.baseUrl ?? ""})`- : `no key needed for this loopback server, endpoint accepted (${cfg.provider ?? "?"} ${cfg.baseUrl ?? ""})`,+ : `no key needed for this loopback server, endpoint accepted (${cfg.provider ?? "?"} ${cfg.baseUrl ?? ""})`) ++ `; tuning: ${tuning}`,};+ }}}diff --git a/src/core/install/ownership.ts b/src/core/install/ownership.tsindex 383f0f59..62e7e2b7 100644--- a/src/core/install/ownership.ts+++ b/src/core/install/ownership.ts@@ -355,6 +355,23 @@ export const OUT_OF_VAULT_STATE: ReadonlyArray<OutOfVaultState> = Object.freeze("command was run from anywhere else.",sources: ["src/cli/brain/verbs/bench.ts"],},+ {+ id: "decision_model_tuning_marks",+ label: "decision-model tuning marks",+ location: WINDOWS+ ? `(${describeBaseDir("state", "win32")})\\open-second-brain\\decision-model\\tuning-marks\\<profile>\\<use>.json`+ : "${XDG_STATE_HOME:-~/.local/state}/open-second-brain/decision-model/tuning-marks/<profile>/<use>.json",+ carries_memory: false,+ created_by: "`o2b decision-model eval run`, when a preregistered eval's verdict is promote",+ removed_by:+ "deleting that directory yourself; the machine re-marks a pair only when the eval runs and promotes again",+ note:+ "The machine-side gate input that lets an untuned use run enforce, keyed by threshold profile " ++ "and decision use. It carries hashes, counts and error rates under the eval spec's hash - never " ++ "vault text - and it is validated against the installed spec on every read, so deleting one " ++ "merely puts that use back in shadow until the eval promotes it again.",+ sources: ["src/core/decision-model/eval/mark.ts", "src/core/platform-dirs.ts"],+ },]);/**@@ -630,6 +647,13 @@ export const SOURCES_INVISIBLE_TO_THE_SWEEP: ReadonlyMap<string, string> = new M"the script path it recommends is built by src/cli/cron-recipe.ts, which is swept; this " +"module only supplies the job name and body, so it names no root of its own",],+ [+ "src/core/decision-model/eval/mark.ts",+ "the tuning-mark root arrives from `decisionModelStateDir()` in `src/core/platform-dirs.ts`, " ++ "which the sweep already enrols and the machine_config row already attributes, so no home or " ++ "XDG token appears in this file's own source; the location it writes is the " ++ "decision_model_tuning_marks row",+ ],]);// ----- The measured half ----------------------------------------------------diff --git a/src/core/platform-dirs.ts b/src/core/platform-dirs.tsindex c1dd067d..5cbd9f93 100644--- a/src/core/platform-dirs.ts+++ b/src/core/platform-dirs.ts@@ -8,7 +8,8 @@* recipe (`cli/partner-codegraph-cron.ts`) emits a bash script that expands* `${XDG_STATE_HOME:-$HOME/.local/state}` itself, at cron time on a POSIX* host, where it agrees with the POSIX layout below by construction. The- * state and cache roots have no production caller yet.+ * cache root and the data root have no production caller yet; the state+ * root's first is the decision-model tuning mark (`eval/mark.ts`).** POSIX (Linux, macOS, the BSDs): the XDG Base Directory layout, with the* `XDG_*_HOME` variables honoured and `$HOME/.config`, `$HOME/.local/share`,@@ -125,6 +126,26 @@ export function cacheBaseDir(source: PlatformDirsEnv = processDirsEnv()): stringreturn baseDir("cache", source);}+/**+ * This tool's own root under the state base directory:+ * `<stateBaseDir>/open-second-brain`. Machine-side state lives here -+ * files the tool itself consumes and that must never sync with the+ * vault. The decision-model tuning marks (`eval/mark.ts`) are the first+ * production caller.+ */+export function stateRootDir(source: PlatformDirsEnv = processDirsEnv()): string {+ return join(baseDir("state", source), APP_DIR_NAME);+}++/**+ * Machine-side state directory for the decision-model feature: the+ * tuning marks the config resolver consults sit under it, keyed by+ * threshold profile and use. Outside every vault by construction.+ */+export function decisionModelStateDir(source: PlatformDirsEnv = processDirsEnv()): string {+ return join(stateRootDir(source), "decision-model");+}+/*** Directory `o2b install-cli` publishes launchers into: `~/.local/bin` on* every platform (`%USERPROFILE%\.local\bin` on Windows).diff --git a/src/core/search/freshen.ts b/src/core/search/freshen.tsindex 75ceafb5..195c2d06 100644--- a/src/core/search/freshen.ts+++ b/src/core/search/freshen.ts@@ -727,12 +727,22 @@ export interface FreshenStatus {readonly state: FreshenState;/** The backoff end, only while it is still in the future. */readonly activeBackoffUntil: string | null;+ /**+ * The live measured index-behind total (t_e4438152): documents the+ * next incremental run would add, update or delete, measured NOW.+ * Passed in by the caller that chose to pay the walk - this stays a+ * pure state-file reader, so the doctor's freshen check (which reads+ * the state file on its own) picks up no walk cost. Null means not+ * measured - a failed measurement is not a measurement, never zero.+ */+ readonly indexBehind: number | null;}export function freshenStatus(config: ResolvedSearchConfig,lastIndexedAt: string | null,nowMs: number = Date.now(),+ indexBehind: number | null = null,): FreshenStatus {const state = readFreshenState(dirname(config.dbPath));const backoffMs = state.backoffUntil === null ? Number.NaN : Date.parse(state.backoffUntil);@@ -741,6 +751,7 @@ export function freshenStatus(indexAgeSeconds: indexAgeSeconds(lastIndexedAt, nowMs),state,activeBackoffUntil: Number.isFinite(backoffMs) && backoffMs > nowMs ? state.backoffUntil : null,+ indexBehind,});}@@ -749,6 +760,12 @@ export function renderFreshenStatus(s: FreshenStatus): string[] {const lines = [`freshen: ${s.intervalSeconds > 0 ? `every ${s.intervalSeconds}s` : "off"}`,`index_age: ${s.indexAgeSeconds === null ? "(unknown)" : `${s.indexAgeSeconds}s`}`,+ // The label stays within the 19 columns every status label fits in.+ `index_behind: ${+ s.indexBehind === null+ ? "(not measured)"+ : `${s.indexBehind} doc${s.indexBehind === 1 ? "" : "s"}`+ }`,];const st = s.state;if (st.lastOutcome === "completed") {@@ -772,6 +789,7 @@ export function serializeFreshenStatus(s: FreshenStatus): Record<string, unknownreturn {interval_s: s.intervalSeconds,index_age_s: s.indexAgeSeconds,+ index_behind: s.indexBehind,last_outcome: s.state.lastOutcome,last_run_at: s.state.lastRunAt,last_changed: s.state.lastChanged,diff --git a/src/core/search/index.ts b/src/core/search/index.tsindex 216ba71e..173453bc 100644--- a/src/core/search/index.ts+++ b/src/core/search/index.ts@@ -192,6 +192,8 @@ export {indexStatus,indexCheck,indexRootCoverage,+ indexBehindCount,+ type IndexBehind,type IndexRootCoverage,type IndexVaultOptions,type IndexProgressEvent,diff --git a/src/core/search/indexer.ts b/src/core/search/indexer.tsindex a7691022..f0075e0c 100644--- a/src/core/search/indexer.ts+++ b/src/core/search/indexer.ts@@ -6,9 +6,10 @@* rebuild: write to `brain.sqlite.new`, then a same-file rename swap* with `.bak` retention.*- * `indexStatus`, `indexCheck` and `indexRootCoverage` are the read-side- * diagnostics that power `o2b search status|check`, the MCP status- * enrichment and the recall gate's coverage receipt.+ * `indexStatus`, `indexCheck`, `indexRootCoverage` and+ * `indexBehindCount` are the read-side diagnostics that power+ * `o2b search status|check`, the MCP status enrichment and the recall+ * gate's coverage receipt.** Anchored in docs/plans/2026-05-16-brain-search-design.md §6, §8,* §13, §15.@@ -1812,6 +1813,100 @@ export async function indexStatus(config: ResolvedSearchConfig): Promise<IndexSt}}+// ─────────────────────────────────────────────────────────────────────────────+// indexBehindCount+// ─────────────────────────────────────────────────────────────────────────────++/**+ * What the next incremental run would do, measured live (t_e4438152).+ */+export interface IndexBehind {+ /** `unindexed + changed + deleted`: the run's whole to-do list. */+ readonly behind: number;+ /** Walked files with no stored row: the run would add them. */+ readonly unindexed: number;+ /** Stored mtime or size differs: the run would re-read and hash them. */+ readonly changed: number;+ /** Stored paths the walk never saw: the run would delete them. */+ readonly deleted: number;+}++/**+ * The live index-behind census: how many documents the next incremental+ * run would add, update or delete, measured now rather than read back+ * from the last completed run's count.+ *+ * Exactly the incremental fastpath's comparison, without the reads:+ * `walkVault` yields the in-scope `.md` tree stat-only (no content read,+ * no hash - the cost is one `readdir` plus one `stat` per entry), and+ * every walked file is classified against the stored row:+ *+ * - `unindexed`: walked, no stored row;+ * - `changed`: stored mtime (seconds) or size differs - the fastpath+ * miss the next run must read and hash;+ * - `deleted`: a stored path the walk never saw.+ *+ * Two deliberate semantics, shared with the fastpath this replicates:+ *+ * 1. Upper bound. A touch-only file (identical bytes, bumped mtime)+ * counts as changed: the walk never hashes, so "behind" means+ * "what the next run would re-read", not "notes missing from+ * answers".+ * 2. Second granularity. Stored mtimes are seconds, so an edit that+ * lands twice within its indexed second at the same size reads as+ * unchanged. The run after it catches it; do not "fix" that here.+ *+ * Read-only and self-contained: one read-mode store open, no writes, no+ * freshen claim, no state file - nothing registers anywhere. On ANY+ * failure - a missing or unreadable index, a walk that throws - the+ * answer is `null`: a failed measurement is not a measurement, and+ * `null` is never a zero.+ */+export async function indexBehindCount(config: ResolvedSearchConfig): Promise<IndexBehind | null> {+ let store: Store;+ try {+ store = await Store.open(config, { mode: "read" });+ } catch {+ return null; // No index, or one that would not open: not measured.+ }+ try {+ const existing = store.listDocuments();+ const seen = new Set<string>();+ let unindexed = 0;+ let changed = 0;+ for (const file of walkVault(config)) {+ seen.add(file.relPath);+ const prev = existing.get(file.relPath);+ if (prev === undefined) {+ unindexed++;+ } else if (+ prev.mtime !== Math.floor(file.stat.mtimeMs / 1000) ||+ prev.size !== file.stat.size+ ) {+ changed++;+ }+ }+ let deleted = 0;+ for (const path of existing.keys()) {+ if (!seen.has(path)) deleted++;+ }+ return Object.freeze({+ behind: unindexed + changed + deleted,+ unindexed,+ changed,+ deleted,+ });+ } catch {+ return null;+ } finally {+ try {+ await store.close();+ } catch {+ // A close failure must not unseat the measurement (or the null).+ }+ }+}+// ─────────────────────────────────────────────────────────────────────────────// indexRootCoverage// ─────────────────────────────────────────────────────────────────────────────diff --git a/src/core/search/pipeline/outcome.ts b/src/core/search/pipeline/outcome.tsindex 6c452715..87f86921 100644--- a/src/core/search/pipeline/outcome.ts+++ b/src/core/search/pipeline/outcome.ts@@ -26,6 +26,7 @@ import {RETRIEVAL_DEGRADATION,RETRIEVAL_RELATIONAL_PATH_CODE,type RelationalPathTrailEntry,+ type RetrievalDegradationDetail,} from "../retrieval-trail.ts";import { buildEvidenceVerification, coverageOverResults } from "../evidence-verification.ts";import { fnv1aHex } from "../feedback.ts";@@ -320,12 +321,30 @@ export function buildSearchOutcome(input: OutcomeInput): SearchOutcome {* hit or miss, gains it here from the index age it is served at. The* result is the trail the pipeline would have built with the code in its* sink: the code leads, and a corpus statement gives way to it.+ *+ * `behindCount` is the measured index-behind census the caller computed+ * under the same gate (t_e4438152). Measured - including a measured+ * zero - it rides the detail beside the age; `null` or absent means not+ * measured, and the detail then names the age alone. A count is a plain+ * integer, so the open degradation-detail object needs no schema change+ * and no new code appears.*/-export function withIndexStale(outcome: SearchOutcome, ageSeconds: number | null): SearchOutcome {+export function withIndexStale(+ outcome: SearchOutcome,+ ageSeconds: number | null,+ behindCount?: number | null,+): SearchOutcome {if (ageSeconds === null || ageSeconds <= INDEX_STALE_SECONDS) return outcome;+ // Spread, not a ternary of literals: a ternary union synthesizes a+ // `behindCount?: undefined` arm, and undefined is not a detail value.+ // Absent stays absent, exactly like the null-measured case.+ const detail: RetrievalDegradationDetail = Object.freeze({+ ageSeconds,+ ...(behindCount === null || behindCount === undefined ? {} : { behindCount }),+ });const stale = Object.freeze({code: RETRIEVAL_DEGRADATION.indexStale,- detail: Object.freeze({ ageSeconds }),+ detail,});const trail = outcome.retrievalTrail;const retrievalTrail = Object.freeze({diff --git a/src/core/search/search-options-descriptor.ts b/src/core/search/search-options-descriptor.tsnew file mode 100644index 00000000..aa3a614d--- /dev/null+++ b/src/core/search/search-options-descriptor.ts@@ -0,0 +1,703 @@+/**+ * The search-options descriptor (t_50c81d5c substrate): one typed row per+ * caller-facing field of the search language, declared once.+ *+ * The repo used to carry four hand-parallel copies of the brain_search+ * input contract - the served MCP schema (`SEARCH_INPUT_SCHEMA` in+ * `src/mcp/search-tools.ts`), the CLI `parseFlags` table+ * (`src/cli/search/verbs/query.ts`), the `SearchOptions` type+ * (`./types.ts`), and a vendored Python projection+ * (`plugins/hermes/_schemas.py`). Nothing connected them, so schema and+ * enforcement (and flag table and type) could drift independently. This+ * table is the single source of truth the copies now derive from:+ *+ * - the MCP schema is the mcp-visible projection+ * ({@link deriveSearchInputSchema}), pinned byte-identical to the+ * pre-derivation literal by+ * `tests/core/search/search-query-schema-artifact.test.ts`;+ * - the CLI flag table derives from the cli-visible rows (snake_case+ * name to kebab-case flag, mechanically) - the verb-local flags+ * (`json`, `verbose`, `auto-refresh`) stay local to the verb;+ * - the vendored projection stays untouched because day-one identity+ * is byte-identity.+ *+ * ## Compile-time parity+ *+ * {@link SearchOptionRow.option} is typed `keyof SearchOptions | null`, so+ * a row that names a phantom option is a `tsc` error, not a runtime+ * surprise - the `satisfies`-style assertion the card asked for, made+ * structural by the row type itself. `null` is honest, not a loophole: it+ * marks a boundary-only argument (`explain`, `telemetry`, `global`) that+ * drives output or routing at the surface and never enters the core+ * options. The reverse direction - no caller-facing `SearchOptions` field+ * missing a row - is a runtime test in+ * `tests/core/search/search-query-schema-artifact.test.ts`.+ *+ * ## What this table deliberately does NOT reconcile+ *+ * The per-surface asymmetries are recorded, not flattened: the MCP+ * surface keeps `MCP_LIMIT_MAX` where the CLI keeps `SEARCH_LIMIT_MAX`,+ * the CLI query is uncapped where MCP caps at {@link MCP_QUERY_MAX_CHARS},+ * `path_prefix` spells `--path` and `record_access` spells+ * `--no-record-access` (the {@link SearchOptionRow.cliNegates} inverse) on+ * the CLI, and `semantic` is tri-state over MCP but deliberately+ * undefined-passing over the CLI. Flattening any of these would change a+ * frozen public surface; the rows say exactly where the edges are.+ */++import type { SearchOptions } from "./types.ts";+import { DISCLOSURE_MODES } from "./disclosure-mode.ts";+import { FTS_MATCH_MODES } from "./fts-match-mode.ts";+import { RECALL_PROFILE_NAMES } from "./profiles.ts";+import { SEARCH_KINDS } from "./property-pushdown.ts";++/** The longest `query` the served brain_search schema advertises, enforced by its handler. */+export const MCP_QUERY_MAX_CHARS = 2000;++/** The largest `limit` the served brain_search schema advertises; the CLI keeps `SEARCH_LIMIT_MAX`. */+export const MCP_LIMIT_MAX = 50;++/** The wire surface a row reaches. A row on neither is internal documentation. */+export type SearchOptionSurface = "mcp" | "cli";++/** How the CLI flag parses. `string-array` is a repeatable flag. */+export type SearchOptionCliKind = "boolean" | "string" | "string-array";++/**+ * The JSON Schema fragment one argument serves. Only the shapes the+ * brain_search language actually uses are expressible - a new shape is a+ * decision to extend this type, not a place to smuggle in an unchecked+ * keyword.+ */+export interface SearchOptionSchemaFragment {+ readonly type: "string" | "boolean" | "integer" | "number" | "array" | "object";+ readonly enum?: ReadonlyArray<string>;+ readonly minimum?: number;+ readonly maximum?: number;+ readonly minLength?: number;+ readonly maxLength?: number;+ readonly maxItems?: number;+ readonly items?: Readonly<Record<string, unknown>>;+ readonly additionalProperties?: Readonly<Record<string, unknown>>;+ readonly description: string;+}++/** One caller-facing field of the search language. */+export interface SearchOptionRow {+ /** Canonical snake_case name - the MCP argument spelling. */+ readonly name: string;+ /**+ * The `SearchOptions` key this row feeds, or `null` for a+ * boundary-only argument. THE compile-time parity assertion: any other+ * spelling is refused by `tsc`.+ */+ readonly option: keyof SearchOptions | null;+ /** Present exactly on the one required argument. */+ readonly required?: true;+ /** The fragment the MCP surface serves for the argument. */+ readonly schema: SearchOptionSchemaFragment;+ /** CLI flag spelling, dashes omitted, or `null` when the CLI cannot reach it. */+ readonly cliFlag: string | null;+ /** How {@link cliFlag} parses. */+ readonly cliKind: SearchOptionCliKind;+ /** True when the CLI flag is the INVERSE sense of the option (`--no-record-access`). */+ readonly cliNegates?: true;+ /** The surfaces the argument is visible on. */+ readonly surfaces: ReadonlyArray<SearchOptionSurface>;+ /** The documented default, as the served description states it. */+ readonly default: string;+}++/**+ * Every caller-facing field of the search language, in the order the+ * served schema declares them. The three cli-only rows close the table:+ * they back `SearchOptions` fields the served MCP schema omits, and their+ * fragments are documentation (they never reach the mcp projection).+ */+export const SEARCH_OPTION_ROWS: ReadonlyArray<SearchOptionRow> = Object.freeze([+ {+ name: "query",+ option: "query",+ required: true,+ schema: {+ type: "string",+ minLength: 1,+ maxLength: MCP_QUERY_MAX_CHARS,+ description:+ "What to recall from the vault. Matched against the index by keyword, semantics, or both.",+ },+ cliFlag: null,+ cliKind: "string",+ surfaces: ["mcp"],+ default: "required; the CLI takes it positionally",+ },+ {+ name: "query_document",+ option: "structuredQuery",+ schema: {+ type: "string",+ minLength: 1,+ maxLength: 4000,+ description:+ "Line-oriented query program with intent:, lex:, vec: and hyde: lanes, steering each retrieval layer separately. Absent means 'query' drives every lane.",+ },+ cliFlag: "query-doc",+ cliKind: "string",+ surfaces: ["mcp", "cli"],+ default: "absent: 'query' drives every lane",+ },+ {+ name: "focus_query",+ option: "sessionFocus",+ schema: {+ type: "string",+ minLength: 1,+ maxLength: 1000,+ description:+ "Steer this one call towards a working-set topic without persisting a session focus.",+ },+ cliFlag: null,+ cliKind: "string",+ surfaces: ["mcp"],+ default: "absent: the persisted focus applies",+ },+ {+ name: "focus_path_prefix",+ option: "sessionFocus",+ schema: {+ type: "string",+ minLength: 1,+ maxLength: 256,+ description:+ "Steer this one call towards a vault subtree, paired with focus_query as a transient focus.",+ },+ cliFlag: null,+ cliKind: "string",+ surfaces: ["mcp"],+ default: "absent",+ },+ {+ name: "focus_session",+ option: "focusSession",+ schema: {+ type: "string",+ minLength: 1,+ maxLength: 128,+ description: "Session id whose bound focus applies (falls back to the global focus).",+ },+ cliFlag: null,+ cliKind: "string",+ surfaces: ["mcp"],+ default: "absent: the global focus",+ },+ {+ name: "evidence_pack",+ option: "evidencePack",+ schema: {+ type: "boolean",+ description:+ "Return the evidence pack: matched/missing terms, coverage, abstention text and the false-absence guard. Default false.",+ },+ cliFlag: "evidence-pack",+ cliKind: "boolean",+ surfaces: ["mcp", "cli"],+ default: "false",+ },+ {+ name: "include_superseded",+ option: "includeSuperseded",+ schema: {+ type: "boolean",+ description:+ "History mode for relation polarity: keep matched superseded predecessors undemoted and skip successor pull-in. Default false.",+ },+ cliFlag: "include-superseded",+ cliKind: "boolean",+ surfaces: ["mcp", "cli"],+ default: "false",+ },+ {+ name: "since",+ option: "since",+ schema: {+ type: "string",+ maxLength: 64,+ description:+ "Hard filter on event time (validity, body anchor, mtime last): at/after this point. ISO date/datetime, today, yesterday, last week, last month, <n>h/<n>d/<n>w.",+ },+ cliFlag: "since",+ cliKind: "string",+ surfaces: ["mcp", "cli"],+ default: "absent: no time filter",+ },+ {+ name: "until",+ option: "until",+ schema: {+ type: "string",+ maxLength: 64,+ description:+ "Hard filter on event time (validity, body anchor, mtime last): at/before this point. Same forms as 'since'.",+ },+ cliFlag: "until",+ cliKind: "string",+ surfaces: ["mcp", "cli"],+ default: "absent: no time filter",+ },+ {+ name: "limit",+ option: "limit",+ schema: {+ type: "integer",+ minimum: 1,+ maximum: MCP_LIMIT_MAX,+ description: "How many ranked results to return. Default 10.",+ },+ cliFlag: "limit",+ cliKind: "string",+ surfaces: ["mcp", "cli"],+ default: "10",+ },+ {+ name: "semantic",+ option: "semantic",+ schema: {+ type: "boolean",+ description:+ "Force the semantic lane on or off. Absent lets the configured hybrid strategy decide.",+ },+ cliFlag: "semantic",+ cliKind: "boolean",+ surfaces: ["mcp", "cli"],+ default: "absent: the configured hybrid strategy decides",+ },+ {+ name: "keyword_only",+ option: "keywordOnly",+ schema: {+ type: "boolean",+ description: "Skip the semantic lane entirely, so no embedding is needed. Default false.",+ },+ cliFlag: "keyword-only",+ cliKind: "boolean",+ surfaces: ["mcp", "cli"],+ default: "false",+ },+ {+ name: "match_mode",+ option: "matchMode",+ schema: {+ type: "string",+ enum: [...FTS_MATCH_MODES],+ description:+ "FTS match breadth: 'all' (default) requires every term; 'any' matches a document carrying any one term. Absent leaves the implicit AND.",+ },+ cliFlag: "match-mode",+ cliKind: "string",+ surfaces: ["mcp", "cli"],+ default: "all",+ },+ {+ name: "disclosure",+ option: "disclosure",+ schema: {+ type: "string",+ enum: [...DISCLOSURE_MODES],+ description:+ "Result depth: 'full' (default) returns full chunk content; 'cards' returns token-cheap layer-1 cards — drill a hit with brain_search_expand.",+ },+ cliFlag: "disclosure",+ cliKind: "string",+ surfaces: ["mcp", "cli"],+ default: "full",+ },+ {+ name: "profile",+ option: "profile",+ schema: {+ type: "string",+ enum: [...RECALL_PROFILE_NAMES],+ description:+ "Named recall profile (fast|balanced|thorough): a fixed knob preset, preferred over persisted self-tuning. Absent leaves ranking unchanged.",+ },+ cliFlag: "profile",+ cliKind: "string",+ surfaces: ["mcp", "cli"],+ default: "absent: ranking unchanged",+ },+ {+ name: "explain",+ option: null,+ schema: {+ type: "boolean",+ description:+ "Add a per-result score_breakdown plus the retrieval_decision_trace and memory_trust_assessment receipts. Default false.",+ },+ cliFlag: "explain",+ cliKind: "boolean",+ surfaces: ["mcp", "cli"],+ default: "false",+ },+ {+ name: "trust",+ option: "trust",+ schema: {+ type: "boolean",+ description:+ "Stamp each result with inline trust metadata (age_days, superseded, conflict), computed at read time. Default false.",+ },+ cliFlag: null,+ cliKind: "boolean",+ surfaces: ["mcp"],+ default: "false",+ },+ {+ name: "threshold",+ option: "threshold",+ schema: {+ type: "number",+ minimum: 0,+ maximum: 1,+ description:+ "Relevance floor in [0,1] on the final score; drops weaker hits so an irrelevant query returns no match. Default 0 (disabled).",+ },+ cliFlag: null,+ cliKind: "string",+ surfaces: ["mcp"],+ default: "0 (disabled)",+ },+ {+ name: "rerank",+ option: "rerank",+ schema: {+ type: "boolean",+ description:+ "Re-order the threshold-qualified results by core textual relevance (keyword + semantic). Default false.",+ },+ cliFlag: null,+ cliKind: "boolean",+ surfaces: ["mcp"],+ default: "false",+ },+ {+ name: "reinforce",+ option: "reinforce",+ schema: {+ type: "array",+ maxItems: 50,+ items: { type: "string", minLength: 1, maxLength: 512 },+ description:+ "Paths proven useful: recorded to the reinforce ledger and lifted (bounded) before the top_k cut. Default absent.",+ },+ cliFlag: null,+ cliKind: "string-array",+ surfaces: ["mcp"],+ default: "absent",+ },+ {+ name: "record_access",+ option: "recordAccess",+ schema: {+ type: "boolean",+ description:+ "Record the surfaced paths as one activation access event (feeds the usage-aware ranking layer). Default true; never recorded for global searches.",+ },+ cliFlag: "no-record-access",+ cliKind: "boolean",+ cliNegates: true,+ surfaces: ["mcp", "cli"],+ default: "true",+ },+ {+ name: "global",+ option: null,+ schema: {+ type: "boolean",+ description:+ "Cross-vault union: search profile vaults and read-only recall sources too, merging results with origin labels. Default false (active vault only).",+ },+ cliFlag: "global",+ cliKind: "boolean",+ surfaces: ["mcp", "cli"],+ default: "false (active vault only)",+ },+ {+ name: "path_prefix",+ option: "pathPrefix",+ schema: {+ type: "string",+ maxLength: 256,+ description: "Restrict results to this vault subtree. Absent searches the whole vault.",+ },+ cliFlag: "path",+ cliKind: "string",+ surfaces: ["mcp", "cli"],+ default: "absent: the whole vault",+ },+ {+ name: "telemetry",+ option: null,+ schema: {+ type: "boolean",+ description: "Emit one recall-telemetry continuity record for this call. Default false.",+ },+ cliFlag: null,+ cliKind: "boolean",+ surfaces: ["mcp"],+ default: "false",+ },+ {+ name: "telemetry_host",+ option: null,+ schema: {+ type: "string",+ maxLength: 200,+ description: "Optional host/client label recorded on the telemetry record.",+ },+ cliFlag: null,+ cliKind: "string",+ surfaces: ["mcp"],+ default: "absent",+ },+ {+ name: "session_id",+ option: null,+ schema: {+ type: "string",+ maxLength: 512,+ description: "Optional session correlation id recorded on the telemetry record.",+ },+ cliFlag: null,+ cliKind: "string",+ surfaces: ["mcp"],+ default: "absent",+ },+ {+ name: "turn_id",+ option: null,+ schema: {+ type: "string",+ maxLength: 512,+ description: "Optional turn correlation id recorded on the telemetry record.",+ },+ cliFlag: null,+ cliKind: "string",+ surfaces: ["mcp"],+ default: "absent",+ },+ {+ name: "properties",+ option: "properties",+ schema: {+ type: "object",+ description:+ "Optional frontmatter filter; values within a key OR, keys AND. type, pinned, visibility as indexed; other keys narrow on the attribute snapshot, judged live.",+ additionalProperties: {+ type: "array",+ items: { type: "string" },+ },+ },+ cliFlag: "property",+ cliKind: "string-array",+ surfaces: ["mcp", "cli"],+ default: "absent: no filter",+ },+ {+ name: "kind",+ option: "kind",+ schema: {+ type: "string",+ enum: [...SEARCH_KINDS],+ description:+ "Restrict candidates by chunk kind: 'page' matches each document's frontmatter/head chunk (chunk 0), 'section' everything after it. Absent searches all chunks.",+ },+ cliFlag: "kind",+ cliKind: "string",+ surfaces: ["mcp", "cli"],+ default: "absent: all chunks",+ },+ {+ name: "degree",+ option: "degreeFilters",+ schema: {+ type: "array",+ description:+ "Graph-degree predicates over backlink/outlink counts, e.g. 'backlinks=0' (orphans) or 'outlinks>=5' (hubs); ANDed. Absent = no filter.",+ items: { type: "string" },+ },+ cliFlag: "degree",+ cliKind: "string-array",+ surfaces: ["mcp", "cli"],+ default: "absent: no filter",+ },+ {+ name: "visibility",+ option: "visibility",+ schema: {+ type: "array",+ description:+ "Optional content-visibility scope; untagged pages always match, tagged pages only when this scope includes one of their values.",+ items: { type: "string" },+ },+ cliFlag: "visibility",+ cliKind: "string-array",+ surfaces: ["mcp", "cli"],+ default: "absent: untagged pages only",+ },+ {+ name: "agent_scope",+ option: "agentScope",+ schema: {+ type: "string",+ description:+ "Optional agent-ownership scope; shared (ownerless) pages always match, owner-tagged pages only their owner. Absent = no ownership filtering.",+ },+ cliFlag: "agent-scope",+ cliKind: "string",+ surfaces: ["mcp", "cli"],+ default: "absent: no ownership filtering",+ },+ {+ name: "session_scope",+ option: "scope",+ schema: {+ type: "string",+ description:+ "Optional session-scope filter; pages with no session always match, session-tagged pages only this session. Absent = no session filtering.",+ },+ cliFlag: null,+ cliKind: "string",+ surfaces: ["mcp"],+ default: "absent: no session filtering",+ },+ {+ name: "project_scope",+ option: "scope",+ schema: {+ type: "string",+ description:+ "Optional project-scope filter; pages with no project always match, project-tagged pages only this project. Absent = no project filtering.",+ },+ cliFlag: null,+ cliKind: "string",+ surfaces: ["mcp"],+ default: "absent: no project filtering",+ },+ {+ name: "iterative",+ option: "iterative",+ schema: {+ type: "boolean",+ description:+ "Opt in to the bounded iterative recall loop (default off). Surviving gaps pause with a plan; resume via iterative_payload. Inert unless the knob is on.",+ },+ cliFlag: null,+ cliKind: "boolean",+ surfaces: ["mcp"],+ default: "false",+ },+ {+ name: "iterative_token",+ option: "iterativeToken",+ schema: {+ type: "string",+ maxLength: 128,+ description:+ "The round token from a plan-phase response, submitted beside iterative_payload. Requires iterative: true; single use - a replayed token is refused by name.",+ },+ cliFlag: null,+ cliKind: "string",+ surfaces: ["mcp"],+ default: "absent",+ },+ {+ name: "iterative_payload",+ option: "iterativePayload",+ schema: {+ type: "object",+ description:+ "Decider payload answering a plan-phase envelope: { evidence: [chunkId, ...], subQueries: [...] }, validated before any pull runs. Requires iterative_token.",+ },+ cliFlag: null,+ cliKind: "string",+ surfaces: ["mcp"],+ default: "absent",+ },+ // ----- Below here: the cli-only rows. Backed by real SearchOptions ----+ // fields the served MCP schema omits, so their fragments are+ // documentation (they never reach the mcp projection above).+ {+ name: "keyword_weight",+ option: "keywordWeight",+ schema: {+ type: "number",+ minimum: 0,+ maximum: 1,+ description:+ "Keyword-lane weight, folded with semantic_weight into ranking. CLI-only: the served MCP schema omits it, so an MCP caller cannot reach the lane weights.",+ },+ cliFlag: "keyword-weight",+ cliKind: "string",+ surfaces: ["cli"],+ default: "the resolved config default",+ },+ {+ name: "semantic_weight",+ option: "semanticWeight",+ schema: {+ type: "number",+ minimum: 0,+ maximum: 1,+ description:+ "Semantic-lane weight, folded with keyword_weight into ranking. CLI-only for the same reason as keyword_weight.",+ },+ cliFlag: "semantic-weight",+ cliKind: "string",+ surfaces: ["cli"],+ default: "the resolved config default",+ },+ {+ name: "expand",+ option: "expand",+ schema: {+ type: "boolean",+ description:+ "Opt-in deterministic query expansion into lex/vec/hyde lanes when no query document was supplied. CLI-only: the served MCP schema omits it.",+ },+ cliFlag: "expand",+ cliKind: "boolean",+ surfaces: ["cli"],+ default: "false",+ },+] satisfies readonly SearchOptionRow[]);++/** The derived shape of the served `brain_search` input schema. */+export type DerivedSearchInputSchema = {+ readonly type: "object";+ readonly properties: Record<string, unknown>;+ readonly required: string[];+ readonly additionalProperties: false;+};++/**+ * The mcp-visible projection of {@link SEARCH_OPTION_ROWS}: the served+ * `brain_search` input schema, in declaration order, with the one+ * required argument. `SEARCH_INPUT_SCHEMA` in `src/mcp/search-tools.ts`+ * IS this value; the schema-artifact test pins it byte-identical to the+ * literal this derivation replaced.+ */+export function deriveSearchInputSchema(): DerivedSearchInputSchema {+ const properties: Record<string, unknown> = {};+ const required: string[] = [];+ for (const row of SEARCH_OPTION_ROWS) {+ if (!row.surfaces.includes("mcp")) continue;+ // Fresh arrays, the way the literal minted them: the served schema is+ // a value handed to clients, not an alias into this table.+ properties[row.name] = {+ ...row.schema,+ ...(row.schema.enum !== undefined ? { enum: [...row.schema.enum] } : {}),+ };+ if (row.required === true) required.push(row.name);+ }+ return { type: "object", properties, required, additionalProperties: false };+}diff --git a/src/core/search/search.ts b/src/core/search/search.tsindex 1380c577..41d08b79 100644--- a/src/core/search/search.ts+++ b/src/core/search/search.ts@@ -61,12 +61,13 @@ import { detectHybridDegrade } from "./enrich.ts";import { isAbortError } from "./embeddings/http-util.ts";import type { CacheProbe } from "./pipeline/cache-slot.ts";import type { RetrievalDegradationSink } from "./retrieval-trail.ts";-import { RETRIEVAL_DEGRADATION, noteDegradation } from "./retrieval-trail.ts";+import { RETRIEVAL_DEGRADATION, noteDegradation, INDEX_STALE_SECONDS } from "./retrieval-trail.ts";import { indexAgeSeconds, maybeFreshenIndex } from "./freshen.ts";import { LAST_INDEXED_AT_STATE_KEY } from "./store/state.ts";import { isPathReadableAtReach, type FrontmatterCache } from "./result-filters.ts";import { Store } from "./store.ts";import { SearchError } from "./types.ts";+import { sha256Hex } from "../integrity/digest.ts";import type { BrainSearchResult } from "./search-result.ts";import type {IterativeStopReason,@@ -445,7 +446,23 @@ export async function search(...(opts.freshenSpawn !== undefined ? { spawn: opts.freshenSpawn } : {}),});const indexAge = indexAgeSeconds(lastIndexedAt, nowMs);- const served = (outcome: SearchOutcome): SearchOutcome => withIndexStale(outcome, indexAge);+ // The measured behind count rides the index-stale note (t_e4438152):+ // computed only when the note will fire, here above the cache branch+ // so a cache hit serves the same measurement. A fresh index performs+ // no walk at all; a failed measurement is null and the note then+ // names the age alone. The measurement is memoized per vault for+ // {@link INDEX_BEHIND_MEMO_TTL_MS} (finding 24): on a permanently-+ // stale origin - a read-only cross-vault recall, or freshening off -+ // the note fires on EVERY search, and without the memo each one paid+ // a full synchronous vault walk plus a second store open. `o2b+ // search status` measures live through `indexBehindCount` directly+ // and never sees this memo.+ const behindCount =+ indexAge !== null && indexAge > INDEX_STALE_SECONDS+ ? await measureIndexBehind(effectiveConfig, lastIndexedAt, nowMs)+ : null;+ const served = (outcome: SearchOutcome): SearchOutcome =>+ withIndexStale(outcome, indexAge, behindCount);// Shared across every frontmatter-reading stage below (Plan 1, 1.3)// so a candidate path already read by one stage is not re-read// and re-parsed by the next.@@ -1134,3 +1151,98 @@ export async function search(await store.close();}}++/**+ * How long a search-path behind-count measurement is reused by later+ * searches against the same vault. Bounded on purpose: the note's age+ * stays live, and the count is an upper-bound diagnostic, so a minute of+ * staleness costs nothing - while the bounded repeat is what keeps a+ * permanently-stale origin (read-only cross-vault recall, freshening+ * off) from paying the full stat walk on every query (finding 24).+ */+export const INDEX_BEHIND_MEMO_TTL_MS = 60_000;++/** One memoized measurement, valid for the TTL and the index generation. */+interface BehindMemoEntry {+ readonly behind: number;+ readonly measuredAtMs: number;+ /** The index stamp the measurement was taken against. */+ readonly lastIndexedAt: string | null;+}++/**+ * Per-process memo of the behind-count measurement, one entry per vault+ * index. The key is the digest of the index path - the absolute path+ * itself never becomes a map key, appears in no entry, and can therefore+ * surface through no diagnostic.+ */+const behindMemo = new Map<string, BehindMemoEntry>();++/** Sweep trigger: past this many vaults, expired entries are dropped. */+const BEHIND_MEMO_SWEEP_AT = 32;++/**+ * The measured index-behind count for the index-stale detail+ * (t_e4438152), or `null` when it could not be measured. Memoized per+ * vault for {@link INDEX_BEHIND_MEMO_TTL_MS} and per index generation (a+ * re-stamped index - a freshen run completed - invalidates the entry+ * immediately), and dropped by the in-process write path itself:+ * {@link invalidateIndexBehindMemo}, called where an applied note write+ * claims its detached refresh, so a served count never outlives a write+ * this process made. Only a write from ANOTHER process waits out the+ * TTL - the memo is per-process state, and that residual is disclosed in+ * the docs rather than pretended away. Repeated searches inside the+ * window reuse the measurement instead of re-walking the vault. Only a+ * real measurement is memoized: `null` - a failed measurement is not a+ * measurement - is retried by the next search. Status (`o2b search+ * status`) measures live through `indexBehindCount` and never consults+ * this memo. Deferred+ * import: `indexer.ts` sits above this module in the graph, and the+ * sanctioned cure for that in this tree is an import evaluated at call+ * time - reached only under the stale gate, so a fresh index never pays+ * it. Never throws: a diagnostic must not fail the answer it annotates.+ */+export async function measureIndexBehind(+ config: ResolvedSearchConfig,+ lastIndexedAt: string | null,+ nowMs: number = Date.now(),+): Promise<number | null> {+ const key = sha256Hex(config.dbPath);+ const memoed = behindMemo.get(key);+ if (+ memoed !== undefined &&+ nowMs - memoed.measuredAtMs < INDEX_BEHIND_MEMO_TTL_MS &&+ memoed.lastIndexedAt === lastIndexedAt+ ) {+ return memoed.behind;+ }+ try {+ const { indexBehindCount } = await import("./indexer.ts");+ const behind = (await indexBehindCount(config))?.behind ?? null;+ if (behind !== null) {+ if (behindMemo.size >= BEHIND_MEMO_SWEEP_AT) {+ for (const [sweptKey, entry] of behindMemo) {+ if (nowMs - entry.measuredAtMs >= INDEX_BEHIND_MEMO_TTL_MS) behindMemo.delete(sweptKey);+ }+ }+ behindMemo.set(key, { behind, measuredAtMs: nowMs, lastIndexedAt });+ }+ return behind;+ } catch {+ return null;+ }+}++/**+ * Drop the vault's memoized behind-count measurement. The in-process+ * note-write path calls this once an applied write has landed: the+ * measurement described the vault as it was, and serving a memoized 0+ * across notes this very process just wrote is the one lie a diagnostic+ * must not tell (M9). The next stale search re-measures - one extra+ * stat walk per write window, never a wrong number. Never throws, and+ * deleting an absent key is fine: invalidation is always safe, the+ * worst case is a re-walk the TTL would have saved.+ */+export function invalidateIndexBehindMemo(config: ResolvedSearchConfig): void {+ behindMemo.delete(sha256Hex(config.dbPath));+}diff --git a/src/core/state/surfaces.ts b/src/core/state/surfaces.tsindex 85b8674e..05703961 100644--- a/src/core/state/surfaces.ts+++ b/src/core/state/surfaces.ts@@ -76,6 +76,7 @@ import {BRAIN_ARTIFACTS_REL,BRAIN_CAPTURES_REL,BRAIN_CLAIM_GRAPH_FILE,+ BRAIN_CROSS_TOPIC_LEDGER_FILE,BRAIN_LOG_REL,BRAIN_PROCEDURAL_MEMORY_REL,BRAIN_ROLLUP_LEDGER_FILE,@@ -156,6 +157,7 @@ export const STATE_SURFACE_ID = Object.freeze({claudeMemoryManifest: "claude_memory_manifest",claimGraph: "claim_graph",rollupLedger: "rollup_ledger",+ crossTopicLedger: "cross_topic_ledger",proposalWatermark: "proposal_watermark",captureWatermark: "capture_watermark",decisionLedger: "decision_ledger",@@ -1062,6 +1064,20 @@ export const STATE_SURFACES: ReadonlyArray<StateSurface> = Object.freeze(["recomputing it.",sources: ["src/core/brain/paths.ts"],},+ {+ id: STATE_SURFACE_ID.crossTopicLedger,+ label: "cross-topic rule ledger",+ tier: STATE_TIER.vaultContent,+ derive: brainTree(BRAIN_CROSS_TOPIC_LEDGER_FILE),+ override_env: null,+ override_config_key: null,+ carries_memory: false,+ reason:+ "The last date each owner token promoted a cross-topic rule, so a budgeted-out dream pass " ++ "plans nothing rather than re-promoting. Like the rollup ladder ledger beside it, the state " ++ "accrues with the work: a reset just reopens today's promotion budget.",+ sources: ["src/core/brain/paths.ts"],+ },{id: STATE_SURFACE_ID.proposalWatermark,label: "proposal scan watermark",diff --git a/src/mcp/brain/pack-tools.ts b/src/mcp/brain/pack-tools.tsindex 5b2d92ca..0dd0bd61 100644--- a/src/mcp/brain/pack-tools.ts+++ b/src/mcp/brain/pack-tools.ts@@ -12,6 +12,7 @@ import { isAbsolute, relative } from "node:path";import {resolveDensityRankingContextPack,+ resolveModelContextWindowEnvTokens,resolveRecallAdequacyThresholds,resolveRecallGateTelemetry,resolveSearchFocusContextPack,@@ -67,9 +68,17 @@ import {diffContextPreset,getContextPreset,listContextPresets,+ presetForResolvedWindow,suggestContextPreset,+ unrecognisedModelBudgetRefusal,type ContextPresetCurrentConfig,} from "../../core/brain/context-presets.ts";+import {+ resolveModelContextWindowTokens,+ MODEL_CONTEXT_WINDOW_ENV_KEY,+ type ModelWindowSource,+ type ResolvedModelWindow,+} from "../../core/brain/model-window.ts";import { extractPreCompactRecords } from "../../core/brain/pre-compact-extract.ts";import { EventTraceSelectorError, resolveLogEventTraces } from "../../core/brain/event-trace.ts";import { gatedOwnerScopeView, ownerScopeView } from "../../core/brain/owner-scope-view.ts";@@ -146,6 +155,69 @@ async function withSearchErrorsOnWire<T>(}}+/**+ * The vault's declared `context.window_tokens`; `undefined` when the block+ * is absent or the file cannot be read. Fail-soft on purpose: a broken+ * `_brain.yaml` raises later, where the pack builds, exactly as it always+ * has - the derivation channel must not answer for the operator's config+ * before the real reader does.+ */+function contextWindowConfigValue(vault: string): number | undefined {+ try {+ return loadBrainConfig(vault).context?.window_tokens;+ } catch {+ return undefined;+ }+}++/**+ * Resolve the model context window for one tool call (t_a567cc12) from+ * the three channels this server owns - the vault's `context:` block, the+ * environment override, and the caller's model hint - in the resolver's+ * precedence (config > env > declared table > `1m` suffix > default).+ *+ * `null` means NOTHING is resolvable: no model hint, no operator block,+ * no env value. Callers refuse on it - the pinned decision is never a+ * silent default budget. A malformed env value raises (an operator typo+ * must not shrink every budget to the default unnoticed); wrap the call+ * where the tool wants that on the wire as INVALID_PARAMS.+ *+ * Only invoked on the derivation path: a call that carries its explicit+ * budget never reads the vault or the environment, so the explicit path+ * behaves byte-identically to before the resolver existed.+ */+function resolveSurfaceModelWindow(+ vault: string,+ model: string | undefined,+): ResolvedModelWindow | null {+ const operatorWindow = contextWindowConfigValue(vault);+ const envWindow = resolveModelContextWindowEnvTokens();+ if (model === undefined && operatorWindow === undefined && envWindow === undefined) return null;+ return resolveModelContextWindowTokens({+ ...(model !== undefined ? { model } : {}),+ ...(operatorWindow !== undefined ? { operatorWindowTokens: operatorWindow } : {}),+ ...(envWindow !== undefined ? { envWindowTokens: envWindow } : {}),+ });+}++/**+ * The caller's optional `model` id. A whitespace-only or empty value is+ * ABSENT - a blank name is no name - so the derivation answers+ * nothing-resolvable and refuses with the budget message, exactly as a+ * call without `model` does, instead of a model-argument complaint and+ * never a derived default budget. A non-string value stays a caller+ * error.+ */+function optionalModelArg(tool: string, args: Record<string, unknown>): string | undefined {+ const raw = args["model"];+ if (raw === undefined || raw === null) return undefined;+ if (typeof raw !== "string") {+ throw new MCPError(INVALID_PARAMS, `${tool}: model must be a non-empty string`);+ }+ const trimmed = raw.trim();+ return trimmed === "" ? undefined : trimmed;+}+/*** A pack refusal raised after the query embed still names that spend. The* loader's pre-embed check reads every belief in view, while the pack keeps@@ -184,9 +256,68 @@ async function toolBrainContextPack(ctx: ServerContext,args: Record<string, unknown>,): Promise<Record<string, unknown>> {- const maxTokens = coercePositiveInteger("brain_context_pack", "max_tokens", args["max_tokens"]);- if (maxTokens === undefined) {- throw new MCPError(INVALID_PARAMS, "brain_context_pack: max_tokens must be a positive integer");+ const model = optionalModelArg("brain_context_pack", args);+ const maxTokensArg = coercePositiveInteger(+ "brain_context_pack",+ "max_tokens",+ args["max_tokens"],+ );+ // The adequacy pairing is an input-SHAPE contract, declared in the+ // schema's `dependentRequired`, so it refuses an incomplete pair by+ // name before any semantic refusal can preempt it: `max_tokens` is now+ // optional behind the derivation below (t_a567cc12), and a payload+ // carrying one half of the pair must learn about the pairing, not about+ // a budget it never sent.+ const recallAttempt = coerceRecallAdequacyInput(+ "brain_context_pack",+ args,+ RECALL_SCORES_ARG_NAME,+ );+ const answerableArg = coerceDecisionAnswerable(+ "brain_context_pack",+ args,+ RECALL_SCORES_ARG_NAME,+ recallAttempt !== undefined,+ );+ // Derived budget (t_a567cc12): an explicit `max_tokens` is first-class+ // and untouched. When it is omitted, the budget derives from the model+ // context window the resolver resolves, through the matching preset's+ // `context_pack.max_tokens` - the curated mapping. A `default`-sourced+ // window defers to the model's hint preset, the same mapping+ // `brain_context_presets` suggest answers, so one model gets one budget+ // and one suggestion on every surface - and an id NOTHING places (no+ // table row, no suffix, no hint) refuses: the conservative posture this+ // tool held before derivation existed, never the default window's+ // long-context budget an 8k local model cannot hold. With nothing+ // resolvable the call refuses exactly as before: the pinned decision is+ // never a silent default budget.+ let maxTokens: number;+ let maxTokensSource: ModelWindowSource | undefined;+ if (maxTokensArg !== undefined) {+ maxTokens = maxTokensArg;+ } else {+ let resolved: ResolvedModelWindow | null;+ try {+ resolved = resolveSurfaceModelWindow(ctx.vault, model ?? undefined);+ } catch (e) {+ throw new MCPError(INVALID_PARAMS, `brain_context_pack: ${(e as Error).message}`);+ }+ if (resolved === null) {+ throw new MCPError(+ INVALID_PARAMS,+ "brain_context_pack: max_tokens must be a positive integer",+ );+ }+ const refusal = unrecognisedModelBudgetRefusal(model, resolved);+ if (refusal !== null) {+ throw new MCPError(INVALID_PARAMS, `brain_context_pack: ${refusal}`);+ }+ // The hint fallback rides along exactly when the resolver's answer is+ // the default-sourced assumption, so a hint-only model budgets the+ // preset `brain_context_presets` suggest names for it; the source+ // disclosed on the wire stays the window's.+ maxTokens = presetForResolvedWindow(model, resolved).context_pack.max_tokens;+ maxTokensSource = resolved.source;}const query = typeof args["query"] === "string" ? (args["query"] as string) : undefined;// Ranked query mode (v1.53.0). Enforced beside the `dependentRequired`@@ -256,20 +387,9 @@ async function toolBrainContextPack();const receipt = receiptOptionsFromArgs("brain_context_pack", args, "context_pack", "mcp");const telemetry = telemetryOptionsFromArgs("brain_context_pack", args, "mcp");- // Adequacy verdict (t_b8f66fec): when the caller passes the recall- // scores that produced this material, classify grounding fitness and- // name the action; also persist it in the receipt for the audit trail.- const recallAttempt = coerceRecallAdequacyInput(- "brain_context_pack",- args,- RECALL_SCORES_ARG_NAME,- );- const answerableArg = coerceDecisionAnswerable(- "brain_context_pack",- args,- RECALL_SCORES_ARG_NAME,- recallAttempt !== undefined,- );+ // The pairing coercions themselves ran above the budget derivation, so+ // an incomplete pair is refused by name; only the ASSESSMENT waits for+ // this point, beside the receipt and telemetry options it rides with.const adequacy =recallAttempt !== undefined? assessRecallAdequacy(@@ -429,6 +549,10 @@ async function toolBrainContextPack(return {vault_path: vaultPathField(ctx),max_tokens: report.maxTokens,+ // Present only when the budget was derived (t_a567cc12): the channel+ // that decided, so a caller can see a resolution was assumed rather+ // than paid for. An explicit `max_tokens` answers without it.+ ...(maxTokensSource !== undefined ? { max_tokens_source: maxTokensSource } : {}),tokens_used: report.tokensUsed,items: report.items.map((i) => ({id: i.id,@@ -938,6 +1062,7 @@ async function toolBrainPreCompressPack(ctx: ServerContext,args: Record<string, unknown>,): Promise<Record<string, unknown>> {+ const model = optionalModelArg("brain_pre_compress_pack", args);const topK = coercePositiveInteger("brain_pre_compress_pack", "top_k", args["top_k"]) ?? 10;const maxCharsPerMemory = coercePositiveInteger("brain_pre_compress_pack",@@ -949,6 +1074,40 @@ async function toolBrainPreCompressPack("max_total_chars",args["max_total_chars"],);+ // Derived caps (t_a567cc12): an absent cap used to mean unbounded - the+ // one injection surface with no ceiling at all. When a cap is absent+ // and a window resolves, the matching preset's `pre_compress` block+ // fills it; explicit caps stay first-class; with nothing resolvable the+ // historical unbounded addendum stands, byte-identical. `top_k` keeps+ // its own 10 default - the presets' top-k values are suggestion+ // diagnostics, not this tool's default.+ let resolvedCaps: ResolvedModelWindow | null = null;+ // A malformed OPEN_SECOND_BRAIN_MODEL_CONTEXT_WINDOW used to rethrow+ // here as INVALID_PARAMS - blaming the caller's parameters and losing+ // the addendum over an operator typo the caller cannot see and this+ // result never disclosed. On THIS path an unparseable env value means+ // nothing resolvable: the historical unbounded caps stand and a named+ // warning says which channel misread, never echoing the value itself.+ let windowWarning: string | undefined;+ if (maxCharsPerMemory === undefined || maxTotalChars === undefined) {+ try {+ resolvedCaps = resolveSurfaceModelWindow(ctx.vault, model ?? undefined);+ } catch {+ resolvedCaps = null;+ windowWarning =+ `${MODEL_CONTEXT_WINDOW_ENV_KEY} is not a well-formed positive integer; ` ++ "pre-compress caps stay unbounded and nothing was derived from it";+ }+ }+ // The hint fallback rides along here exactly as it does in the+ // context-pack budget above: when the resolver's answer is the+ // default-sourced assumption, a hint-only model's caps come from its+ // hint preset, the same mapping the pack and `brain_context_presets`+ // suggest name - one model, one mapping on every surface.+ const derivedCaps =+ resolvedCaps !== null ? presetForResolvedWindow(model, resolvedCaps).pre_compress : null;+ const effMaxCharsPerMemory = maxCharsPerMemory ?? derivedCaps?.max_chars_per_memory;+ const effMaxTotalChars = maxTotalChars ?? derivedCaps?.max_total_chars;const receipt = receiptOptionsFromArgs("brain_pre_compress_pack", args, "pre_compress", "mcp");const telemetry = telemetryOptionsFromArgs("brain_pre_compress_pack", args, "mcp");const agentScope = coerceAgentScope(ctx, args, true);@@ -961,8 +1120,8 @@ async function toolBrainPreCompressPack(...(readable !== undefined ? { readable } : {}),restricted: contextReach(ctx) !== TRANSPORT_REACH.local,...(agentScope !== undefined ? { agentScope } : {}),- ...(maxCharsPerMemory !== undefined ? { maxCharsPerMemory } : {}),- ...(maxTotalChars !== undefined ? { maxTotalChars } : {}),+ ...(effMaxCharsPerMemory !== undefined ? { maxCharsPerMemory: effMaxCharsPerMemory } : {}),+ ...(effMaxTotalChars !== undefined ? { maxTotalChars: effMaxTotalChars } : {}),...(configuredDegradation(ctx.vault) !== undefined? { degradation: configuredDegradation(ctx.vault)! }: {}),@@ -979,6 +1138,10 @@ async function toolBrainPreCompressPack(// builder has, so a warning dropped here is a broken `_brain.yaml`// nothing tells the caller about....(pack.warnings ? { warnings: pack.warnings } : {}),+ // The window channel's own warning: present only when the derivation+ // was skipped over an unparseable operator env value (M4), so a+ // normal answer stays byte-identical.+ ...(windowWarning !== undefined ? { window_warning: windowWarning } : {}),...(pack.receiptId ? { receipt_id: pack.receiptId } : {}),...(pack.telemetryId ? { telemetry_id: pack.telemetryId } : {}),items: pack.items.map((i) => ({@@ -1114,14 +1277,20 @@ export const PACK_TOOLS: ReadonlyArray<ToolDefinition> = Object.freeze([name: "brain_context_pack",previewBudget: MCP_PREVIEW_BUDGET,description:- "Return the highest-tier, most recent vault slice that fits under `max_tokens`. Ordered core → supporting → peripheral, newest first; stops adding pages when the next page would exceed the budget. Read-only.",+ "Return the highest-tier, most recent vault slice under `max_tokens` - derived from the model context window when omitted, refused when nothing resolves. Ordered core → supporting → peripheral, newest first; stops when the next page would exceed the budget. Read-only.",inputSchema: {type: "object",properties: {max_tokens: {type: "integer",minimum: 1,- description: "Strict upper bound on the returned slice's token count.",+ description:+ "Token cap for the slice. Omitted: derives from the resolved window (channel in `max_tokens_source`; `default` defers to the preset hint). Nothing resolvable is refused.",+ },+ model: {+ type: "string",+ description:+ "Model id. `max_tokens` omitted: the context window resolves (config, env, table, `1m` suffix); an unplaced id is refused (pass max_tokens or set context.window_tokens).",},query: {type: "string",@@ -1211,10 +1380,14 @@ export const PACK_TOOLS: ReadonlyArray<ToolDefinition> = Object.freeze([},agent_scope: AGENT_SCOPE_SCHEMA,},- required: ["max_tokens"],- // Both or neither, stated declaratively so a schema-driven client can- // discover the pairing instead of learning it from an INVALID_PARAMS- // at call time. Built beside the enforcement; see+ // `max_tokens` used to be the one required argument; the resolver+ // (t_a567cc12) made it optional behind a derivation contract+ // instead, so `required` is gone - the nothing-resolvable refusal+ // is enforced beside the handler, not expressible as `required`.+ //+ // Pairings, stated declaratively so a schema-driven client can+ // discover them instead of learning them from an INVALID_PARAMS at+ // call time. Built beside the enforcement; see// `recallAdequacyPairing`. `query_mode` joins it one-directionally:// a mode needs a query, a query needs no mode. `packing_policy`// joins the same way: a policy with nothing to order is inert, so@@ -1348,12 +1521,14 @@ export const PACK_TOOLS: ReadonlyArray<ToolDefinition> = Object.freeze([},model: {type: "string",- description: "Optional model name hint for suggest.",+ description:+ "Optional model for suggest. With `context_window_tokens` absent the window resolves first (table, `1m` suffix); a hint answers only when nothing places the id.",},context_window_tokens: {type: "integer",minimum: 1,- description: "Optional context-window size hint for suggest.",+ description:+ "Optional context-window size hint for suggest. Wins over model-derived resolution.",},current: {type: "object",@@ -1368,10 +1543,11 @@ export const PACK_TOOLS: ReadonlyArray<ToolDefinition> = Object.freeze([},{// No preview budget: the addendum is meant to be injected whole and- // is already bounded by its own per-entry / total character caps.+ // is bounded by its own per-entry / total character caps - now also+ // derived from the resolved context window when absent (t_a567cc12).name: "brain_pre_compress_pack",description:- "Return a compact system-prompt addendum (top-K confirmed preferences plus the head of active.md) for a host to inject right before context compression. Char-budgeted. Read-only.",+ "Return a compact system-prompt addendum (top-K confirmed preferences plus the head of active.md) for a host to inject right before context compression. Char-budgeted: absent caps derive from the resolved model context window, so the addendum is bounded whenever a window resolves. Read-only.",inputSchema: {type: "object",properties: {@@ -1381,17 +1557,22 @@ export const PACK_TOOLS: ReadonlyArray<ToolDefinition> = Object.freeze([description:"Maximum number of preferences to include, highest-confidence first (default 10).",},+ model: {+ type: "string",+ description:+ "Model id. When a char cap is absent the context window resolves from this id (table, `1m` suffix, or default); a preset hint sizes caps only when nothing places it.",+ },max_chars_per_memory: {type: "integer",minimum: 1,description:- "Optional per-entry character cap (code points); trimmed entries carry `trimmed: true`.",+ "Optional per-entry character cap; trimmed entries carry `trimmed: true`. Absent: the preset cap applies when a window resolves; nothing resolvable stays unbounded.",},max_total_chars: {type: "integer",minimum: 1,description:- "Optional total character cap (code points) across the addendum; lowest-priority overflow is dropped.",+ "Optional total character cap; lowest-priority overflow drops first. Absent: the preset cap applies when a window resolves; nothing resolvable stays unbounded.",},receipt: {type: "boolean",diff --git a/src/mcp/search-tools.ts b/src/mcp/search-tools.tsindex c0fd305e..2e439659 100644--- a/src/mcp/search-tools.ts+++ b/src/mcp/search-tools.ts@@ -31,7 +31,6 @@ import { parseDegreePredicate, type DegreePredicate } from "../core/search/propeimport { SEARCH_KINDS, isSearchKind } from "../core/search/property-pushdown.ts";import { REMOTE_DENY_VISIBILITY_TOKEN, normToken } from "../core/graph/visibility.ts";import { searchAcrossVaults } from "../core/search/cross-vault.ts";-import { RECALL_PROFILE_NAMES } from "../core/search/profiles.ts";import { fileContextRecall } from "../core/brain/file-recall.ts";import { withTimeout } from "../core/search/with-timeout.ts";import {@@ -94,6 +93,11 @@ import {import { projectScoreBreakdown } from "../core/search/enrich.ts";import { recordReinforce } from "../core/search/reinforce.ts";import { parseRecallBenchmarkDataset, runRecallBenchmark } from "../core/search/benchmark.ts";+import {+ deriveSearchInputSchema,+ MCP_LIMIT_MAX,+ MCP_QUERY_MAX_CHARS,+} from "../core/search/search-options-descriptor.ts";import {deriveRecallSignals,emitRecallTelemetry,@@ -107,10 +111,13 @@ import { emitGateTelemetry, emitNegativeRecallTelemetry } from "../core/brain/gaimport { emitGatedTelemetry } from "../core/brain/continuity/emit.ts";import { recordQueryDemand, recordRecallAdequacyDemand } from "../core/brain/query-demand.ts";-const MCP_LIMIT_MAX = 50;--/** The longest `query` a recall tool accepts, advertised and enforced from here. */-export const MCP_QUERY_MAX_CHARS = 2000;+/**+ * The longest `query` a recall tool accepts, advertised and enforced from+ * here. DECLARED in the search-options descriptor beside the schema that+ * advertises it (t_50c81d5c substrate); re-exported for the sibling tools+ * that cap the same way.+ */+export { MCP_QUERY_MAX_CHARS };/** The refusal text of a query over {@link MCP_QUERY_MAX_CHARS}, shared by every capped tool. */export const MCP_QUERY_CAP_MESSAGE = `argument 'query' exceeds ${MCP_QUERY_MAX_CHARS} characters`;@@ -134,223 +141,16 @@ const SEARCH_TIMEOUT_MS = 10_000;/** Surfaced rows named as source refs on one recall-telemetry record. */const TELEMETRY_TOP_ARTIFACTS_MAX = 10;-const SEARCH_INPUT_SCHEMA: Record<string, unknown> = {- type: "object",- properties: {- query: {- type: "string",- minLength: 1,- maxLength: MCP_QUERY_MAX_CHARS,- description:- "What to recall from the vault. Matched against the index by keyword, semantics, or both.",- },- query_document: {- type: "string",- minLength: 1,- maxLength: 4000,- description:- "Line-oriented query program with intent:, lex:, vec: and hyde: lanes, steering each retrieval layer separately. Absent means 'query' drives every lane.",- },- focus_query: {- type: "string",- minLength: 1,- maxLength: 1000,- description:- "Steer this one call towards a working-set topic without persisting a session focus.",- },- focus_path_prefix: {- type: "string",- minLength: 1,- maxLength: 256,- description:- "Steer this one call towards a vault subtree, paired with focus_query as a transient focus.",- },- focus_session: {- type: "string",- minLength: 1,- maxLength: 128,- description: "Session id whose bound focus applies (falls back to the global focus).",- },- evidence_pack: {- type: "boolean",- description:- "Return the evidence pack: matched/missing terms, coverage, abstention text and the false-absence guard. Default false.",- },- include_superseded: {- type: "boolean",- description:- "History mode for relation polarity: keep matched superseded predecessors undemoted and skip successor pull-in. Default false.",- },- since: {- type: "string",- maxLength: 64,- description:- "Hard filter on event time (validity, body anchor, mtime last): at/after this point. ISO date/datetime, today, yesterday, last week, last month, <n>h/<n>d/<n>w.",- },- until: {- type: "string",- maxLength: 64,- description:- "Hard filter on event time (validity, body anchor, mtime last): at/before this point. Same forms as 'since'.",- },- limit: {- type: "integer",- minimum: 1,- maximum: MCP_LIMIT_MAX,- description: "How many ranked results to return. Default 10.",- },- semantic: {- type: "boolean",- description:- "Force the semantic lane on or off. Absent lets the configured hybrid strategy decide.",- },- keyword_only: {- type: "boolean",- description: "Skip the semantic lane entirely, so no embedding is needed. Default false.",- },- match_mode: {- type: "string",- enum: [...FTS_MATCH_MODES],- description:- "FTS match breadth: 'all' (default) requires every term; 'any' matches a document carrying any one term. Absent leaves the implicit AND.",- },- disclosure: {- type: "string",- enum: [...DISCLOSURE_MODES],- description:- "Result depth: 'full' (default) returns full chunk content; 'cards' returns token-cheap layer-1 cards — drill a hit with brain_search_expand.",- },- profile: {- type: "string",- enum: [...RECALL_PROFILE_NAMES],- description:- "Named recall profile (fast|balanced|thorough): a fixed knob preset, preferred over persisted self-tuning. Absent leaves ranking unchanged.",- },- explain: {- type: "boolean",- description:- "Add a per-result score_breakdown plus the retrieval_decision_trace and memory_trust_assessment receipts. Default false.",- },- trust: {- type: "boolean",- description:- "Stamp each result with inline trust metadata (age_days, superseded, conflict), computed at read time. Default false.",- },- threshold: {- type: "number",- minimum: 0,- maximum: 1,- description:- "Relevance floor in [0,1] on the final score; drops weaker hits so an irrelevant query returns no match. Default 0 (disabled).",- },- rerank: {- type: "boolean",- description:- "Re-order the threshold-qualified results by core textual relevance (keyword + semantic). Default false.",- },- reinforce: {- type: "array",- maxItems: 50,- items: { type: "string", minLength: 1, maxLength: 512 },- description:- "Paths proven useful: recorded to the reinforce ledger and lifted (bounded) before the top_k cut. Default absent.",- },- record_access: {- type: "boolean",- description:- "Record the surfaced paths as one activation access event (feeds the usage-aware ranking layer). Default true; never recorded for global searches.",- },- global: {- type: "boolean",- description:- "Cross-vault union: search profile vaults and read-only recall sources too, merging results with origin labels. Default false (active vault only).",- },- path_prefix: {- type: "string",- maxLength: 256,- description: "Restrict results to this vault subtree. Absent searches the whole vault.",- },- telemetry: {- type: "boolean",- description: "Emit one recall-telemetry continuity record for this call. Default false.",- },- telemetry_host: {- type: "string",- maxLength: 200,- description: "Optional host/client label recorded on the telemetry record.",- },- session_id: {- type: "string",- maxLength: 512,- description: "Optional session correlation id recorded on the telemetry record.",- },- turn_id: {- type: "string",- maxLength: 512,- description: "Optional turn correlation id recorded on the telemetry record.",- },- properties: {- type: "object",- description:- "Optional frontmatter filter; values within a key OR, keys AND. type, pinned, visibility as indexed; other keys narrow on the attribute snapshot, judged live.",- additionalProperties: {- type: "array",- items: { type: "string" },- },- },- kind: {- type: "string",- enum: [...SEARCH_KINDS],- description:- "Restrict candidates by chunk kind: 'page' matches each document's frontmatter/head chunk (chunk 0), 'section' everything after it. Absent searches all chunks.",- },- degree: {- type: "array",- description:- "Graph-degree predicates over backlink/outlink counts, e.g. 'backlinks=0' (orphans) or 'outlinks>=5' (hubs); ANDed. Absent = no filter.",- items: { type: "string" },- },- visibility: {- type: "array",- description:- "Optional content-visibility scope; untagged pages always match, tagged pages only when this scope includes one of their values.",- items: { type: "string" },- },- agent_scope: {- type: "string",- description:- "Optional agent-ownership scope; shared (ownerless) pages always match, owner-tagged pages only their owner. Absent = no ownership filtering.",- },- session_scope: {- type: "string",- description:- "Optional session-scope filter; pages with no session always match, session-tagged pages only this session. Absent = no session filtering.",- },- project_scope: {- type: "string",- description:- "Optional project-scope filter; pages with no project always match, project-tagged pages only this project. Absent = no project filtering.",- },- iterative: {- type: "boolean",- description:- "Opt in to the bounded iterative recall loop (default off). Surviving gaps pause with a plan; resume via iterative_payload. Inert unless the knob is on.",- },- iterative_token: {- type: "string",- maxLength: 128,- description:- "The round token from a plan-phase response, submitted beside iterative_payload. Requires iterative: true; single use - a replayed token is refused by name.",- },- iterative_payload: {- type: "object",- description:- "Decider payload answering a plan-phase envelope: { evidence: [chunkId, ...], subQueries: [...] }, validated before any pull runs. Requires iterative_token.",- },- },- required: ["query"],- additionalProperties: false,-};+/**+ * The served `brain_search` input schema: the search-options descriptor's+ * mcp-visible projection, one derivation instead of a second+ * hand-maintained copy (t_50c81d5c substrate). Pinned byte-identical to+ * the pre-derivation literal by+ * tests/core/search/search-query-schema-artifact.test.ts - the day-one+ * contract is that tools/list and the vendored Hermes projection see the+ * same bytes.+ */+export const SEARCH_INPUT_SCHEMA: Record<string, unknown> = deriveSearchInputSchema();/*** The negative-recall states a zero-result `brain_search` can report.diff --git a/tests/cli/brain-context-pack.test.ts b/tests/cli/brain-context-pack.test.tsindex 4b7e86bc..53fcdea5 100644--- a/tests/cli/brain-context-pack.test.ts+++ b/tests/cli/brain-context-pack.test.ts@@ -141,3 +141,167 @@ test("brain context-pack exposes opt-in transform annotations", async () => {reference_hint: "see pref-alpha",});});++/**+ * Derived budget (t_a567cc12): `--max-tokens` is optional. When it is+ * omitted, the budget derives from the resolved model context window+ * (vault `context:` block, env, or `--model`) through the matching+ * preset; with nothing resolvable the verb refuses exactly as before.+ */+test("brain context-pack derives the budget from --model when --max-tokens is omitted", async () => {+ writePref("core", "core principle", "tier: core");++ const out = await runCli(+ ["brain", "context-pack", "--vault", vault, "--model", "gpt-4o", "--json"],+ {},+ );++ expect(out.returncode).toBe(0);+ const json = JSON.parse(out.stdout);+ expect(json.max_tokens).toBe(24_000);+ expect(json.max_tokens_source).toBe("declared");+});++test("brain context-pack derives from a 1m-suffix model", async () => {+ writePref("core", "core principle", "tier: core");++ const out = await runCli(+ ["brain", "context-pack", "--vault", vault, "--model", "qwen3-235b-1m", "--json"],+ {},+ );++ expect(out.returncode).toBe(0);+ const json = JSON.parse(out.stdout);+ expect(json.max_tokens).toBe(24_000);+ expect(json.max_tokens_source).toBe("suffix");+});++test("brain context-pack budgets a hint-only model from its hint, like suggest", async () => {+ writePref("core", "core principle", "tier: core");++ const out = await runCli(+ ["brain", "context-pack", "--vault", vault, "--model", "gemini-2.5-flash", "--json"],+ {},+ );++ expect(out.returncode).toBe(0);+ const json = JSON.parse(out.stdout);+ // Unknown to the declared table, the resolver answers the default+ // window; the budget defers to the model's hint (tight-context), the+ // same mapping `brain context-presets suggest` answers for the id.+ expect(json.max_tokens).toBe(4_000);+ expect(json.max_tokens_source).toBe("default");+});++test("brain context-pack keeps the declared mapping for a table-known hinted model", async () => {+ writePref("core", "core principle", "tier: core");++ const out = await runCli(+ ["brain", "context-pack", "--vault", vault, "--model", "gpt-4.1-mini", "--json"],+ {},+ );++ expect(out.returncode).toBe(0);+ const json = JSON.parse(out.stdout);+ // "gpt-4.1-mini" matches the "mini" hint AND the declared table; the+ // declared 1M window decides on both surfaces, never the hint.+ expect(json.max_tokens).toBe(24_000);+ expect(json.max_tokens_source).toBe("declared");+});++test("brain context-pack refuses an unrecognised model by name", async () => {+ writePref("core", "core principle", "tier: core");++ const out = await runCli(+ ["brain", "context-pack", "--vault", vault, "--model", "llama3:8b", "--json"],+ {},+ );++ // No table row, no `-1m` suffix, no hint: the verb refuses instead of+ // budgeting the default window's long-context 24k - the model's whole+ // 8k window is a third of that. The refusal names the id and remedies.+ expect(out.returncode).toBe(1);+ expect(out.stderr).toContain("llama3:8b");+ expect(out.stderr).toContain("not recognised");+ expect(out.stderr).toContain("context.window_tokens");+});++test("brain context-pack treats a blank --model as absent", async () => {+ writePref("core", "core principle", "tier: core");++ const out = await runCli(+ ["brain", "context-pack", "--vault", vault, "--model", " ", "--json"],+ {},+ );++ // A blank name is no name: the same nothing-resolvable refusal a call+ // without --model gets, never a derived default budget.+ expect(out.returncode).toBe(1);+ expect(out.stderr).toContain("--max-tokens <n> is required");+});++test("brain context-pack derives from the vault context block without --model", async () => {+ writePref("core", "core principle", "tier: core");+ writeFileSync(+ join(vault, "Brain", "_brain.yaml"),+ "schema_version: 1\ncontext:\n window_tokens: 150000\n",+ );++ const out = await runCli(["brain", "context-pack", "--vault", vault, "--json"], {});++ expect(out.returncode).toBe(0);+ const json = JSON.parse(out.stdout);+ expect(json.max_tokens).toBe(24_000);+ expect(json.max_tokens_source).toBe("operator-config");+});++test("brain context-pack passes an out-of-band declared window through unclamped", async () => {+ writePref("core", "core principle", "tier: core");+ writeFileSync(+ join(vault, "Brain", "_brain.yaml"),+ "schema_version: 1\ncontext:\n window_tokens: 5000000\n",+ );++ const out = await runCli(["brain", "context-pack", "--vault", vault, "--json"], {});++ expect(out.returncode).toBe(0);+ const json = JSON.parse(out.stdout);+ // A first-hand declaration passes through exactly as given (never+ // clamped into the band); 5M simply lands in the long-context bucket,+ // whose 24k budget is what the answer discloses.+ expect(json.max_tokens).toBe(24_000);+ expect(json.max_tokens_source).toBe("operator-config");+});++test("brain context-pack still refuses when nothing resolves", async () => {+ writePref("core", "core principle", "tier: core");++ const out = await runCli(["brain", "context-pack", "--vault", vault, "--json"], {});++ expect(out.returncode).toBe(1);+ expect(out.stderr).toContain("--max-tokens <n> is required");+});++test("brain context-pack explicit --max-tokens wins over --model", async () => {+ writePref("core", "core principle", "tier: core");++ const out = await runCli(+ [+ "brain",+ "context-pack",+ "--vault",+ vault,+ "--model",+ "gpt-4o",+ "--max-tokens",+ "1000",+ "--json",+ ],+ {},+ );++ expect(out.returncode).toBe(0);+ const json = JSON.parse(out.stdout);+ expect(json.max_tokens).toBe(1_000);+ expect(json.max_tokens_source).toBeUndefined();+});diff --git a/tests/cli/brain-context-presets.test.ts b/tests/cli/brain-context-presets.test.tsindex 33d7cee8..295c2eef 100644--- a/tests/cli/brain-context-presets.test.ts+++ b/tests/cli/brain-context-presets.test.ts@@ -26,6 +26,57 @@ test("brain context-presets show/suggest/diff returns dry-run diagnostics", asynconfidence: "high",});+ // `--model` alone resolves a window and the reason discloses what decided.+ const modelOnly = await runCli([+ "brain",+ "context-presets",+ "suggest",+ "--model",+ "gpt-4o",+ "--json",+ ]);+ expect(modelOnly.returncode).toBe(0);+ expect(JSON.parse(modelOnly.stdout)).toMatchObject({+ preset_id: "long-context",+ confidence: "high",+ reason: "context window 128000 tokens resolved from declared matched long-context",+ });++ // The disagreeing-model case: a declared table id that also matches a+ // hint must suggest the mapping the pack budget derives from.+ const hintAndTable = await runCli([+ "brain",+ "context-presets",+ "suggest",+ "--model",+ "gpt-4.1-mini",+ "--json",+ ]);+ expect(hintAndTable.returncode).toBe(0);+ expect(JSON.parse(hintAndTable.stdout)).toMatchObject({+ preset_id: "long-context",+ confidence: "high",+ reason: "context window 1000000 tokens resolved from declared matched long-context",+ });++ // A hint-only model - nothing published resolves for the id - answers+ // from its hint; the pack budget derivation applies the same fallback,+ // so both surfaces name one mapping for the model.+ const hintOnly = await runCli([+ "brain",+ "context-presets",+ "suggest",+ "--model",+ "gemini-2.5-flash",+ "--json",+ ]);+ expect(hintOnly.returncode).toBe(0);+ expect(JSON.parse(hintOnly.stdout)).toMatchObject({+ preset_id: "tight-context",+ confidence: "high",+ reason: "model hint matched tight-context",+ });+const diff = await runCli(["brain","context-presets",diff --git a/tests/cli/decision-model-eval.test.ts b/tests/cli/decision-model-eval.test.tsnew file mode 100644index 00000000..1016a3cc--- /dev/null+++ b/tests/cli/decision-model-eval.test.ts@@ -0,0 +1,279 @@+/**+ * `o2b decision-model eval run|list` and the doctor probe's measured+ * state (cycle 20261020, card t_4e1681b3, task C4).+ *+ * `eval run` grades the preregistered take over the real adapter - the+ * loopback fake here, never a hosted route - and a promote verdict+ * writes the machine-side tuning mark under the state root, which the+ * config resolver and the doctor then honor. `eval list` round-trips+ * the cached grade records and skips malformed ones with a named note.+ */++import { afterAll, afterEach, beforeAll, beforeEach, describe, expect, test } from "bun:test";+import { existsSync, mkdirSync, mkdtempSync, readFileSync, rmSync, writeFileSync } from "node:fs";+import { tmpdir } from "node:os";+import { join } from "node:path";++import { probeDecisionModel } from "../../src/core/doctor-readiness.ts";+import {+ decisionEvalSpecFor,+ decisionEvalSpecHash,+} from "../../src/core/decision-model/eval-spec.ts";+import { FAKE_DECISION_KEY } from "../helpers/fake-credentials.ts";+import { startFakeSystemOne, type FakeSystemOne } from "../helpers/fake-decision-provider.ts";+import { runCli } from "../helpers/run-cli.ts";++const KEY_VAR = "O2B_TEST_DECISION_EVAL_KEY";++let server: FakeSystemOne;+let tmp: string;+let vault: string;+let configPath: string;+let stateDir: string;++beforeAll(async () => {+ server = await startFakeSystemOne();+});+afterAll(async () => {+ await server.close();+});+beforeEach(() => {+ tmp = mkdtempSync(join(tmpdir(), "osb-dm-eval-cli-"));+ vault = join(tmp, "vault");+ mkdirSync(join(vault, "Brain"), { recursive: true });+ configPath = join(tmp, "config.yaml");+ stateDir = join(tmp, "state");+ server.requests.length = 0;+});+afterEach(() => {+ rmSync(tmp, { recursive: true, force: true });+});++function writeConfig(entries: Record<string, string>): void {+ const lines = [`vault: "${vault}"`, ...Object.entries(entries).map(([k, v]) => `${k}: "${v}"`)];+ writeFileSync(configPath, lines.join("\n") + "\n");+}++/** Env for a CLI child: the loopback key, this vault's config, this state root. */+function childEnv(extra: Record<string, string> = {}): Record<string, string> {+ return {+ OPEN_SECOND_BRAIN_CONFIG: configPath,+ XDG_STATE_HOME: stateDir,+ [KEY_VAR]: FAKE_DECISION_KEY,+ ...extra,+ };+}++/** The active eval config; the loopback base URL is added at call time. */+const ENABLED = {+ decision_model_enabled: "true",+ decision_model_provider: "compatible",+ decision_model_id: "fake-model-1",+ decision_model_env_key: KEY_VAR,+ decision_model_threshold_profile: "laya",+ decision_model_uses: "rerank:shadow",+};++function writeEnabledConfig(): void {+ writeConfig({ ...ENABLED, decision_model_base_url: server.url });+}++/**+ * Answer every relevance question by the fixtures' labeling rule, read+ * off the request body the adapter actually sent: an on-topic passage+ * helps. This is the same rule the committed gold labels follow.+ */+function answerByLabel(req: { body: Record<string, unknown> }): {+ json: unknown;+} {+ const state = req.body["state"] as {+ query?: string;+ passages?: Record<string, string>;+ };+ const subject = /the (.+)\?/.exec(state.query ?? "")![1] ?? "\u0000";+ const questions = req.body["questions"] as Record<string, { type: string }>;+ const answers: Record<string, unknown> = {};+ for (const [id, q] of Object.entries(questions)) {+ const key = id.startsWith("rel_") ? `P${id.slice(4)}` : null;+ const text = key === null ? "" : (state.passages?.[key] ?? "");+ answers[id] = { type: q.type, noul: text.includes(subject) ? 0.99 : 0.01 };+ }+ return {+ json: {+ model: "fake-model-1.0",+ answers,+ usage: { input_tokens: 321, output_tokens: 7 },+ },+ };+}++describe("o2b decision-model eval", () => {+ test("an unknown subcommand prints usage and exits 2", async () => {+ const res = await runCli(["decision-model", "eval", "--config", configPath], {+ env: { OPEN_SECOND_BRAIN_CONFIG: configPath },+ });+ expect(res.returncode).toBe(2);+ expect(res.stderr).toContain("usage: o2b decision-model");+ expect(res.stderr).toContain("eval run");+ expect(res.stderr).toContain("eval list");+ });++ test("eval run refuses an unknown use, a specless use and an inactive config", async () => {+ writeEnabledConfig();+ const env = childEnv();+ const bad = await runCli(+ ["decision-model", "eval", "run", "--use", "nonsense", "--config", configPath],+ { env },+ );+ expect(bad.returncode).toBe(2);+ expect(bad.stderr).toContain("decision-model use");++ const specless = await runCli(+ ["decision-model", "eval", "run", "--use", "dedup", "--config", configPath],+ { env },+ );+ expect(specless.returncode).toBe(2);+ expect(specless.stderr).toContain("no preregistered spec");++ writeEnabledConfig();+ const noKey = await runCli(+ ["decision-model", "eval", "run", "--use", "rerank", "--config", configPath],+ { env: { OPEN_SECOND_BRAIN_CONFIG: configPath, XDG_STATE_HOME: stateDir } },+ );+ expect(noKey.returncode).toBe(2);+ expect(noKey.stderr).toContain("o2b decision-model check");+ });++ test("eval run refuses a use that is off before sending or caching anything", async () => {+ // decision_model_uses lists only rerank: recall_inject defaults to+ // off, and the runner's mode override would send nothing, score+ // every item degraded, cache that junk grade and exit 0 - a named+ // refusal is owed instead, before any of that happens.+ writeEnabledConfig();+ server.setReply(answerByLabel);+ const res = await runCli(+ ["decision-model", "eval", "run", "--use", "recall_inject", "--config", configPath],+ { env: childEnv() },+ );+ expect(res.returncode).toBe(2);+ expect(res.stderr).toContain("recall_inject");+ expect(res.stderr).toContain("decision_model_uses");+ expect(server.requests).toHaveLength(0);+ const listJson = await runCli(+ ["decision-model", "eval", "list", "--config", configPath, "--json"],+ { env: childEnv() },+ );+ expect(listJson.returncode).toBe(0);+ const listed = JSON.parse(listJson.stdout) as { grades: unknown[]; skipped: unknown[] };+ expect(listed.grades).toHaveLength(0);+ expect(listed.skipped).toHaveLength(0);+ }, 30000);++ test("a promote run writes the mark, caches the grade and the doctor names it", async () => {+ writeEnabledConfig();+ server.setReply(answerByLabel);+ const res = await runCli(+ ["decision-model", "eval", "run", "--use", "rerank", "--config", configPath, "--json"],+ { env: childEnv() },+ );+ expect(res.returncode).toBe(0);+ const run = JSON.parse(res.stdout) as {+ verdict: string;+ mark_written: boolean;+ grade_record_id: string | null;+ counted: { n: number; error: number | null };+ };+ expect(run.verdict).toBe("promote");+ expect(run.mark_written).toBe(true);+ expect(run.counted).toMatchObject({ n: 30, error: 0 });++ // The machine-side mark exists under this run's state root, for the+ // resolved profile and use.+ const markPath = join(+ stateDir,+ "open-second-brain",+ "decision-model",+ "tuning-marks",+ "laya",+ "rerank.json",+ );+ expect(existsSync(markPath)).toBe(true);+ const mark = JSON.parse(readFileSync(markPath, "utf8")) as { verdict: string; use: string };+ expect(mark).toMatchObject({ verdict: "promote", use: "rerank" });++ // The grade record is cached in the vault and round-trips through+ // eval list, in prose and as JSON.+ expect(run.grade_record_id).not.toBeNull();+ const listJson = await runCli(+ ["decision-model", "eval", "list", "--use", "rerank", "--config", configPath, "--json"],+ { env: childEnv() },+ );+ expect(listJson.returncode).toBe(0);+ const listed = JSON.parse(listJson.stdout) as {+ grades: Array<{ use: string; verdict: string; spec_hash: string }>;+ skipped: string[];+ };+ expect(listed.grades).toHaveLength(1);+ expect(listed.grades[0]).toMatchObject({ use: "rerank", verdict: "promote" });+ expect(listed.skipped).toEqual([]);++ const listProse = await runCli(["decision-model", "eval", "list", "--config", configPath], {+ env: childEnv(),+ });+ const spec12 = decisionEvalSpecHash(decisionEvalSpecFor("rerank")!).slice(0, 12);+ expect(listProse.stdout).toContain("eval grades: 1 record(s)");+ expect(listProse.stdout).toContain("rerank (laya) promote");+ expect(listProse.stdout).toContain(`spec ${spec12}`);++ // The doctor probe names the measured state for the active config.+ const verdict = await probeDecisionModel({+ vault,+ config: configPath,+ env: childEnv() as unknown as NodeJS.ProcessEnv,+ });+ expect(verdict.status).toBe("pass");+ expect(verdict.detail).toContain("measured under spec hash");+ expect(verdict.detail).toContain("(rerank)");+ }, 30000);++ test("eval list skips a malformed record with a named note, in prose and JSON", async () => {+ writeEnabledConfig();+ server.setReply(answerByLabel);+ await runCli(["decision-model", "eval", "run", "--use", "rerank", "--config", configPath], {+ env: childEnv(),+ });+ // A hand-written record that claims a measurement without the fields.+ const { appendContinuityRecord } = await import("../../src/core/brain/continuity/store.ts");+ appendContinuityRecord(vault, {+ kind: "decision_model_eval_grade",+ createdAt: new Date().toISOString(),+ sourceRefs: [],+ payload: { use: "rerank", verdict: "promote" },+ });++ const listJson = await runCli(+ ["decision-model", "eval", "list", "--config", configPath, "--json"],+ {+ env: childEnv(),+ },+ );+ const listed = JSON.parse(listJson.stdout) as { grades: unknown[]; skipped: string[] };+ expect(listed.grades).toHaveLength(1);+ expect(listed.skipped).toHaveLength(1);+ expect(listed.skipped[0]).toMatch(/decision_model_eval_grade record .+ skipped: spec_hash/);++ const listProse = await runCli(["decision-model", "eval", "list", "--config", configPath], {+ env: childEnv(),+ });+ expect(listProse.stdout).toContain("skipped: decision_model_eval_grade record");+ }, 30000);++ test("eval list with no records says so and exits 0", async () => {+ writeEnabledConfig();+ const res = await runCli(["decision-model", "eval", "list", "--config", configPath], {+ env: childEnv(),+ });+ expect(res.returncode).toBe(0);+ expect(res.stdout).toContain("eval grades: none cached");+ });+});diff --git a/tests/cli/search-query-flag-manifest.test.ts b/tests/cli/search-query-flag-manifest.test.tsindex d54de6a9..9d789b80 100644--- a/tests/cli/search-query-flag-manifest.test.ts+++ b/tests/cli/search-query-flag-manifest.test.ts@@ -25,6 +25,7 @@ import { join } from "node:path";import { nestedCommand } from "../../src/cli/command-manifest.ts";import { VAULT_FLAGS } from "../../src/cli/search/helpers.ts";+import { SEARCH_QUERY_FLAGS } from "../../src/cli/search/verbs/query.ts";import { parsedFlagSchema } from "../helpers/parsed-flag-schema.ts";const VERBS_DIR = join(import.meta.dir, "..", "..", "src", "cli", "search", "verbs");@@ -106,8 +107,20 @@ const COVERED: ReadonlyArray<CoveredVerb> = Object.freeze([*/const INHERITED_FLAG_NAME = "json";-/** The `parseFlags(argv, { ... })` schema the verb declares, as `name -> type`. */+/**+ * The `parseFlags(argv, { ... })` schema the verb declares, as `name -> type`.+ *+ * The query verb's schema is no longer an inline literal: it is the+ * descriptor-derived {@link SEARCH_QUERY_FLAGS} export (t_50c81d5c E3),+ * read directly - same object the verb passes to its parser, so the+ * ratchet's direction is unchanged (what the verb parses must be+ * modelled) and the static source read stays only for the verbs whose+ * schemas are still literals.+ */function verbFlagSchema(entry: CoveredVerb): ReadonlyMap<string, string> {+ if (entry.source === "query.ts") {+ return new Map(Object.entries(SEARCH_QUERY_FLAGS).map(([name, spec]) => [name, spec.type]));+ }return parsedFlagSchema({file: join(VERBS_DIR, entry.source),marker: entry.marker,@@ -212,3 +225,41 @@ describe("the search verbs declare the flags they parse", () => {]);});});++describe("the schema verb declares the flags its two subcommands parse", () => {+ // `o2b search schema` sits outside the COVERED table above for one+ // pinned reason: that table's non-vacuity floor asserts every covered+ // verb parses `--vault`, and this verb addresses the repo's committed+ // artifact, not a vault. The same standard still applies, so it is held+ // here: both subcommand parse schemas are read from the verb and the+ // manifest row must account for every flag, never the reverse.+ const MARKER = "export async function cmdSearchSchema";+ const SOURCE = join(VERBS_DIR, "schema-export.ts");++ function schemaFor(callOpen: string): ReadonlyMap<string, string> {+ return parsedFlagSchema({ file: SOURCE, marker: MARKER, callOpen });+ }++ test("every parsed flag is modelled, with the same type", () => {+ const exportSchema = schemaFor("parseFlags(argv.slice(1), {");+ const checkSchema = schemaFor("parseFlags(argv.slice(1), { json:");+ // Pin both reads so a regex that stopped matching cannot pass: export+ // parses stdout + json, check parses json only.+ expect(Object.fromEntries(exportSchema)).toEqual({ stdout: "boolean", json: "boolean" });+ expect(Object.fromEntries(checkSchema)).toEqual({ json: "boolean" });+ const manifest = comparable(manifestFlagSchema("schema"));+ expect(mismatches(comparable(exportSchema), manifest, "schema").toSorted()).toEqual([]);+ expect(mismatches(comparable(checkSchema), manifest, "schema").toSorted()).toEqual([]);+ });++ test("no modelled flag outlives the parse that would accept it", () => {+ const parsed = schemaFor("parseFlags(argv.slice(1), {");+ for (const name of comparable(manifestFlagSchema("schema")).keys()) {+ expect(`${name} parsed: ${parsed.has(name)}`).toBe(`${name} parsed: true`);+ }+ });++ test("the witness flag is reachable from help", () => {+ expect(manifestFlagSchema("schema").has("stdout")).toBe(true);+ });+});diff --git a/tests/cli/search-query-flags.test.ts b/tests/cli/search-query-flags.test.tsnew file mode 100644index 00000000..dcdb8482--- /dev/null+++ b/tests/cli/search-query-flags.test.ts@@ -0,0 +1,172 @@+/**+ * The search CLI flag table derives from the search-options descriptor+ * (t_50c81d5c, Task E3): `o2b search "<query>"` no longer hand-lists its+ * flags - the table is projected from the descriptor's cli-visible rows,+ * so a flag cannot appear on one surface and vanish from the other.+ *+ * `LEGACY_QUERY_FLAGS` below is the literal table that lived in+ * `src/cli/search/verbs/query.ts` before the derivation, pasted verbatim+ * (frozen baseline, the `LEGACY_SEARCH_INPUT_SCHEMA` pattern): the+ * derived table must accept EXACTLY these flags with EXACTLY these+ * parse kinds, so every operator script keeps working unchanged. The+ * per-surface edges are pinned too: the CLI keeps `SEARCH_LIMIT_MAX`+ * bound at the read site (not here), the query stays uncapped, and the+ * `semantic` tri-state asymmetry stays a verb-body concern.+ *+ * The reverse direction holds the descriptor to its story: every+ * cli-visible row is in the table under its declared flag spelling and+ * parse kind, and nothing outside the cli rows is (the verb-local flags+ * `json` / `verbose` / `auto-refresh` and the vault triple stay local by+ * design).+ */++import { describe, expect, test } from "bun:test";++import { CliError, parseFlags } from "../../src/cli/argparse.ts";+import { SEARCH_QUERY_FLAGS } from "../../src/cli/search/verbs/query.ts";+import { SEARCH_OPTION_ROWS } from "../../src/core/search/search-options-descriptor.ts";++/**+ * The pre-derivation literal, frozen. The derived portion of+ * {@link SEARCH_QUERY_FLAGS} must equal the non-verb-local slice of this+ * object, and the full table must equal the vault triple plus that slice+ * plus the verb-local flags.+ */+const LEGACY_QUERY_FLAGS: Record<string, { type: string; default?: string }> = {+ vault: { type: "string" },+ config: { type: "string" },+ db: { type: "string" },+ limit: { type: "string", default: "10" },+ semantic: { type: "boolean" },+ "keyword-only": { type: "boolean" },+ "match-mode": { type: "string" },+ kind: { type: "string" },+ path: { type: "string" },+ "keyword-weight": { type: "string" },+ "semantic-weight": { type: "string" },+ "auto-refresh": { type: "boolean" },+ property: { type: "string-array" },+ degree: { type: "string-array" },+ visibility: { type: "string-array" },+ "agent-scope": { type: "string" },+ "query-doc": { type: "string" },+ expand: { type: "boolean" },+ disclosure: { type: "string" },+ profile: { type: "string" },+ "evidence-pack": { type: "boolean" },+ "include-superseded": { type: "boolean" },+ since: { type: "string" },+ until: { type: "string" },+ global: { type: "boolean" },+ "no-record-access": { type: "boolean" },+ json: { type: "boolean" },+ verbose: { type: "boolean" },+ explain: { type: "boolean" },+};++/** The verb-local flags that stay spelled in the verb, by design. */+const VERB_LOCAL = ["auto-refresh", "json", "verbose"] as const;++describe("the derived search CLI flag table (t_50c81d5c E3)", () => {+ test("accepts exactly the flags the literal table accepted, with the same kinds", () => {+ expect(Object.keys(SEARCH_QUERY_FLAGS).toSorted()).toEqual(+ Object.keys(LEGACY_QUERY_FLAGS).toSorted(),+ );+ for (const [name, spec] of Object.entries(LEGACY_QUERY_FLAGS)) {+ expect(`${name}: ${JSON.stringify(SEARCH_QUERY_FLAGS[name])}`).toBe(+ `${name}: ${JSON.stringify(spec)}`,+ );+ }+ });++ test("every cli-visible descriptor row is in the table under its declared spelling", () => {+ const cliRows = SEARCH_OPTION_ROWS.filter(+ (row) => row.surfaces.includes("cli") && row.cliFlag !== null,+ );+ expect(cliRows.length).toBeGreaterThan(0);+ const missing: string[] = [];+ for (const row of cliRows) {+ const spec = SEARCH_QUERY_FLAGS[row.cliFlag!];+ if (spec === undefined) {+ missing.push(row.name);+ continue;+ }+ expect(spec.type).toBe(row.cliKind);+ }+ expect(missing).toEqual([]);+ });++ test("no mcp-only row leaked into the CLI table", () => {+ const leaked: string[] = [];+ for (const row of SEARCH_OPTION_ROWS) {+ if (row.surfaces.includes("cli") || row.cliFlag === null) continue;+ if (row.cliFlag in SEARCH_QUERY_FLAGS) leaked.push(row.name);+ }+ expect(leaked).toEqual([]);+ });++ test("the verb-local flags stay verb-local, never descriptor-derived", () => {+ const cliFlagNames = new Set(+ SEARCH_OPTION_ROWS.filter((row) => row.cliFlag !== null).map((row) => row.cliFlag!),+ );+ for (const name of VERB_LOCAL) {+ expect(`${name} in the table: ${name in SEARCH_QUERY_FLAGS}`).toBe(+ `${name} in the table: true`,+ );+ expect(`${name} descriptor-derived: ${cliFlagNames.has(name)}`).toBe(+ `${name} descriptor-derived: false`,+ );+ }+ });++ test("the table parses the argv shapes the verb needs", () => {+ // Booleans parse bare; strings take a value; string-arrays repeat.+ const parsed = parseFlags(+ [+ "alpha query",+ "--limit",+ "5",+ "--semantic",+ "--match-mode",+ "any",+ "--path",+ "Brain/notes",+ "--property",+ "status=draft",+ "--property",+ "topic=tabs",+ "--degree",+ "backlinks=0",+ "--query-doc",+ "intent: exact",+ "--no-record-access",+ "--json",+ ],+ SEARCH_QUERY_FLAGS,+ );+ expect(parsed.positional).toEqual(["alpha query"]);+ expect(parsed.flags["limit"]).toBe("5");+ expect(parsed.flags["semantic"]).toBe(true);+ expect(parsed.flags["match-mode"]).toBe("any");+ expect(parsed.flags["path"]).toBe("Brain/notes");+ expect(parsed.flags["property"]).toEqual(["status=draft", "topic=tabs"]);+ expect(parsed.flags["degree"]).toEqual(["backlinks=0"]);+ expect(parsed.flags["query-doc"]).toBe("intent: exact");+ expect(parsed.flags["no-record-access"]).toBe(true);+ expect(parsed.flags["json"]).toBe(true);+ // The limit default survives the derivation.+ const defaulted = parseFlags(["query"], SEARCH_QUERY_FLAGS);+ expect(defaulted.flags["limit"]).toBe("10");+ });++ test("the table still refuses what the literal table refused", () => {+ // Unknown flags throw...+ expect(() => parseFlags(["q", "--definitely-not-a-flag"], SEARCH_QUERY_FLAGS)).toThrow(+ CliError,+ );+ // ...booleans refuse values...+ expect(() => parseFlags(["q", "--semantic=true"], SEARCH_QUERY_FLAGS)).toThrow(CliError);+ // ...and value-taking flags refuse to dangle.+ expect(() => parseFlags(["q", "--limit"], SEARCH_QUERY_FLAGS)).toThrow(CliError);+ });+});diff --git a/tests/cli/search-schema-artifact-packaging.test.ts b/tests/cli/search-schema-artifact-packaging.test.tsnew file mode 100644index 00000000..35b7b9c0--- /dev/null+++ b/tests/cli/search-schema-artifact-packaging.test.ts@@ -0,0 +1,47 @@+/**+ * The search-query schema artifact must SHIP (t_50c81d5c): the `o2b`+ * bin runs the packaged `src/`, and `SEARCH_QUERY_SCHEMA_PATH` resolves+ * module-relatively to `<package-root>/schemas/brain/search-query.schema.json`+ * - so `o2b search schema check` exits 2 ("missing or unreadable") and+ * `o2b search schema export` throws ENOENT in any installed copy where+ * the package `files` allowlist does not carry that path. This holds the+ * allowlist to the path the installed verb actually resolves, the exact+ * gap `npm pack` otherwise only shows at publish time.+ */++import { describe, expect, test } from "bun:test";+import { existsSync, readFileSync } from "node:fs";+import { dirname, join, relative, resolve, sep } from "node:path";+import { fileURLToPath } from "node:url";++import { SEARCH_QUERY_SCHEMA_PATH } from "../../src/cli/search/verbs/schema-export.ts";++const ROOT = resolve(dirname(fileURLToPath(import.meta.url)), "..", "..");++/** npm `files` semantics: an entry is one file, or a directory shipped recursively. */+function ships(files: ReadonlyArray<string>, rel: string): boolean {+ return files.some((entry) => {+ const asDir = entry.endsWith("/") ? entry : `${entry}/`;+ return entry === rel || rel.startsWith(asDir);+ });+}++describe("the search-query schema artifact ships in the package", () => {+ test("the verb's committed-artifact path is the package-relative schemas path", () => {+ const rel = relative(ROOT, SEARCH_QUERY_SCHEMA_PATH);+ expect(rel).toBe(join("schemas", "brain", "search-query.schema.json"));+ // The allowlist cannot ship a file the repo does not carry.+ expect(existsSync(SEARCH_QUERY_SCHEMA_PATH)).toBe(true);+ });++ test("the package.json files allowlist covers that path", () => {+ const pkg = JSON.parse(readFileSync(join(ROOT, "package.json"), "utf8")) as {+ files?: string[];+ };+ // Normalise to forward slashes: `relative` yields separators native to+ // the host (backslashes on Windows), while the `files` entries are posix.+ const rel = relative(ROOT, SEARCH_QUERY_SCHEMA_PATH).split(sep).join("/");+ const missing = ships(pkg.files ?? [], rel) ? [] : [rel];+ expect(missing).toEqual([]);+ });+});diff --git a/tests/cli/search-schema-export-flags.test.ts b/tests/cli/search-schema-export-flags.test.tsnew file mode 100644index 00000000..ff588ebf--- /dev/null+++ b/tests/cli/search-schema-export-flags.test.ts@@ -0,0 +1,106 @@+/**+ * `o2b search schema export` flag contract (t_50c81d5c, Task E4): the+ * usage string and every doc that names the verb+ * (docs/cli-reference.md, CHANGELOG.md, design.md) promise+ * `export [--stdout]`, where `--stdout` PRINTS the rendered artifact and+ * writes nothing - the dry-run/CI preview. The default (no flag) writes+ * the committed artifact and must stay byte-identical.+ *+ * `--json` is NOT advertised for export (it is `check`'s output mode),+ * yet `parseFlags` injects it into every schema, so export refuses it by+ * name instead of silently discarding it - a parsed-and-ignored flag on+ * this surface is exactly the defect class `--stdout` had.+ *+ * The tests mock `node:fs.writeFileSync` (bun `mock.module` retargets the+ * verb's named ESM import), so the red/green difference is observable+ * WITHOUT ever touching the real committed artifact, in either+ * direction - and the real module is handed back when the file ends, so+ * suites running later in the same process keep their writes.+ */++import { afterAll, afterEach, describe, expect, mock, spyOn, test } from "bun:test";+import * as fs from "node:fs";++import { CliError } from "../../src/cli/argparse.ts";+import {+ SEARCH_QUERY_SCHEMA_PATH,+ cmdSearchSchema,+ renderSearchQueryArtifact,+} from "../../src/cli/search/verbs/schema-export.ts";++const written: Array<unknown[]> = [];++// Capture BEFORE the mock: the real writer, handed back in `afterAll`.+const REAL_WRITE_FILE_SYNC = fs.writeFileSync;++mock.module("node:fs", () => ({+ ...fs,+ writeFileSync: (...args: unknown[]) => {+ written.push(args);+ },+}));++/** The stdout the verb under test produced since the last drain. */+let stdout = "";++/** Run `cmdSearchSchema` with stdout captured into {@link stdout}. */+async function runExport(argv: ReadonlyArray<string>): Promise<number> {+ const spy = spyOn(process.stdout, "write").mockImplementation(((chunk: unknown) => {+ stdout += String(chunk);+ return true;+ }) as typeof process.stdout.write);+ try {+ return await cmdSearchSchema(argv);+ } finally {+ spy.mockRestore();+ }+}++describe("o2b search schema export flags", () => {+ afterEach(() => {+ written.length = 0;+ stdout = "";+ });++ /**+ * bun test runs every file of one invocation in a SINGLE process, so a+ * module mock left installed here would silently swallow+ * `writeFileSync` in every suite that runs after this one - the CLI+ * e2e suites write their vaults and configs through node:fs. Hand the+ * real module back before the runner moves on.+ */+ afterAll(() => {+ mock.module("node:fs", () => ({+ ...fs,+ writeFileSync: REAL_WRITE_FILE_SYNC,+ }));+ });++ test("--stdout prints the rendered artifact and writes nothing", async () => {+ const code = await runExport(["export", "--stdout"]);+ expect(code).toBe(0);+ expect(stdout).toBe(renderSearchQueryArtifact());+ expect(written).toEqual([]);+ });++ test("--json is refused by name, with the usage, and writes nothing", async () => {+ let caught: unknown;+ try {+ await runExport(["export", "--json"]);+ } catch (e) {+ caught = e;+ }+ expect(caught).toBeInstanceOf(CliError);+ const message = caught instanceof Error ? caught.message : String(caught);+ expect(message).toContain("--json");+ expect(message).toContain("o2b search schema export [--stdout] | check");+ expect(written).toEqual([]);+ });++ test("the default (no flag) writes the committed path with the rendered bytes", async () => {+ const code = await runExport(["export"]);+ expect(code).toBe(0);+ expect(written).toEqual([[SEARCH_QUERY_SCHEMA_PATH, renderSearchQueryArtifact(), "utf8"]]);+ expect(stdout).toContain(`wrote ${SEARCH_QUERY_SCHEMA_PATH}`);+ });+});diff --git a/tests/cli/search-status-freshen.test.ts b/tests/cli/search-status-freshen.test.tsindex 67693756..2cbe0378 100644--- a/tests/cli/search-status-freshen.test.ts+++ b/tests/cli/search-status-freshen.test.ts@@ -1,14 +1,23 @@/*** `o2b search status` shows freshen on read: the interval (or off), how* old the index is, what the last background run did, and an active- * backoff - in the human output and under `freshen` in `--json`.+ * backoff - in the human output and under `freshen` in `--json`. Beside+ * the age it reports the live measured behind count (t_e4438152):+ * documents the next incremental run would pick up, or "(not measured)"+ * when the walk could not run.*/import { afterEach, beforeEach, expect, test } from "bun:test";import { mkdirSync, mkdtempSync, rmSync, writeFileSync } from "node:fs";import { tmpdir } from "node:os";import { join } from "node:path";-import { writeFreshenState } from "../../src/core/search/freshen.ts";+import {+ EMPTY_FRESHEN_STATE,+ renderFreshenStatus,+ serializeFreshenStatus,+ writeFreshenState,+ type FreshenStatus,+} from "../../src/core/search/freshen.ts";import { runCli } from "../helpers/run-cli.ts";let tmp: string;@@ -39,10 +48,37 @@ test("status names the interval, the index age and that no background run happenexpect(out.returncode).toBe(0);expect(out.stdout).toContain("freshen: every 60s");expect(out.stdout).toMatch(/index_age:\s+\d+s/);+ expect(out.stdout).toContain("index_behind: 0 docs");expect(out.stdout).toContain("last_freshen: (none)");expect(out.stdout).not.toContain("freshen_backoff");});+test("a measured behind count is serialized as a number, an unmeasured one as null", () => {+ const measured: FreshenStatus = {+ intervalSeconds: 60,+ indexAgeSeconds: 5,+ state: EMPTY_FRESHEN_STATE,+ activeBackoffUntil: null,+ indexBehind: 12,+ };+ expect(renderFreshenStatus(measured)).toContain("index_behind: 12 docs");+ expect(serializeFreshenStatus(measured)["index_behind"]).toBe(12);++ const unmeasured: FreshenStatus = { ...measured, indexBehind: null };+ expect(renderFreshenStatus(unmeasured)).toContain("index_behind: (not measured)");+ expect(serializeFreshenStatus(unmeasured)["index_behind"]).toBeNull();+});++test("status counts documents the index has not caught up with", async () => {+ writeFileSync(join(vault, "notes", "b.md"), "# B\n\nbrand new body\n");+ const out = await runCli(["search", "status"], { env: env("60") });+ expect(out.stdout).toContain("index_behind: 1 doc");+ const json = JSON.parse(+ (await runCli(["search", "status", "--json"], { env: env("60") })).stdout,+ );+ expect(json.freshen.index_behind).toBe(1);+});+test("an interval of 0 reads as off", async () => {const out = await runCli(["search", "status"], { env: env("0") });expect(out.stdout).toContain("freshen: off");@@ -89,8 +125,10 @@ test("every freshen line keeps the 21-column value alignment of the status blocklastChanged: null,});const out = await runCli(["search", "status"], { env: env("60") });- const lines = out.stdout.split("\n").filter((l) => /^(freshen|index_age|last_freshen)/.test(l));- expect(lines).toHaveLength(4);+ const lines = out.stdout+ .split("\n")+ .filter((l) => /^(freshen|index_age|index_behind|last_freshen)/.test(l));+ expect(lines).toHaveLength(5);for (const line of lines) {expect(line.slice(0, 21)).toMatch(/^[a-z_]+: +$/);expect(line[21]).not.toBe(" ");diff --git a/tests/core/architecture/claim-attribution-census.test.ts b/tests/core/architecture/claim-attribution-census.test.tsindex ee966541..716baa9c 100644--- a/tests/core/architecture/claim-attribution-census.test.ts+++ b/tests/core/architecture/claim-attribution-census.test.ts@@ -106,6 +106,12 @@ const PINNED_CONTINUITY_KINDS: ReadonlyArray<string> = Object.freeze(["negative_recall","decision_model_call","decision_model_extract_commit",+ // The preregistered-eval wave's additive kind (task C2): one cached+ // verdict set per graded eval run, written by `eval/grade.ts` next to+ // the `decision_model_call` rows it correlates with. Review evidence+ // only - the machine-side gate input is the tuning mark outside the+ // vault, never this record.+ "decision_model_eval_grade","session_entity_mention",// The storage-lifecycle wave's additive kind: the per-run audit of a// confirmed receipt compaction. Disjoint from the Hermesdiff --git a/tests/core/architecture/state-surface-census.test.ts b/tests/core/architecture/state-surface-census.test.tsindex 1d60b1fa..262d1918 100644--- a/tests/core/architecture/state-surface-census.test.ts+++ b/tests/core/architecture/state-surface-census.test.ts@@ -94,7 +94,9 @@ const SWEPT_POPULATION_SIZE = 27;// 50 -> 51: the session mining ledger joins the population with its row// (session-mining-economy), the same join the session import ledger made.// 51 -> 52: the pending mining surveys row (v1.86.1 review fixes).-const DECLARED_SURFACE_COUNT = 52;+// 52 -> 53: the cross-topic rule ledger row (t_642bc2b8 substrate), the+// same join the rollup ladder ledger made.+const DECLARED_SURFACE_COUNT = 53;/** An exclusion reason has to be an argument, not a label. */const MIN_REASON_LENGTH = 80;diff --git a/tests/core/architecture/verdict-vocabulary-census.test.ts b/tests/core/architecture/verdict-vocabulary-census.test.tsindex 4690f9ec..bcaa003e 100644--- a/tests/core/architecture/verdict-vocabulary-census.test.ts+++ b/tests/core/architecture/verdict-vocabulary-census.test.ts@@ -536,6 +536,11 @@ import {RECEIPT_MODE,RECEIPT_MODES,} from "../../../src/core/brain/receipts/types.ts";+import {+ BENCH_REFUSAL,+ BENCH_REFUSAL_KINDS,+ isBenchRefusalKind,+} from "../../../src/core/bench/guards.ts";interface VocabularyUnderCensus {/** Identifies the vocabulary in a failure message. */@@ -1685,6 +1690,17 @@ const CENSUS: ReadonlyArray<VocabularyUnderCensus> = Object.freeze([members: RECEIPT_MODES,guard: isReceiptMode,},+ {+ // Cycle 20261020, Lane E. The bench guards' refusal vocabulary: one+ // closed kind per catchable pre-run (P1-P7) and pre-report (T1-T7)+ // damaged state, rendered verbatim in `refused (<kind>): <detail>` -+ // a name an operator's script can branch on is the whole contract,+ // so it is audited like every other verdict a surface prints.+ name: "BENCH_REFUSAL",+ values: BENCH_REFUSAL,+ members: BENCH_REFUSAL_KINDS,+ guard: isBenchRefusalKind,+ },]);// ---------------------------------------------------------------------------@@ -1958,7 +1974,9 @@ const SCANNED = scanVocabularies(SOURCE_TREE);// 103: INDEX_REFRESH (note lifecycle) gains its isIndexRefresh guard,// completing the four-piece shape its sibling vocabularies already// carry and so entering the scanned population.-const VOCABULARY_POPULATION = 103;+// 104: BENCH_REFUSAL (cycle 20261020, Lane E) - the bench guards'+// closed refusal vocabulary, rendered by name in every bench refusal.+const VOCABULARY_POPULATION = 104;const REGISTERED = new Map(CENSUS.map((entry) => [entry.name, entry] as const));describe("verdict vocabulary census", () => {diff --git a/tests/core/architecture/write-site-census.test.ts b/tests/core/architecture/write-site-census.test.tsindex 5a583000..eaac5a68 100644--- a/tests/core/architecture/write-site-census.test.ts+++ b/tests/core/architecture/write-site-census.test.ts@@ -1467,8 +1467,14 @@ const DIRECT_WRITE_ROWS = 83;* signal page's `entities:` line in place through the shared atomic* writer on the apply arm - a dry-run-by-default repair pass over* existing signal pages, writing no note of its own.+ *+ * 125 -> 126: the cross-topic rule promotion (`src/core/brain/+ * dream-plan-cross-topic.ts`) writes its `Brain/cross-topic-rules.json`+ * daily-budget ledger through the shared atomic writer when a promotion+ * fires - machine state beside the rollup ledger, written only on the+ * changed path, needing no exclusion.*/-const SHARED_HELPER_ROWS = 125;+const SHARED_HELPER_ROWS = 126;// ----- Origin-channel coverage boundary (Unit C) ----------------------------@@ -1608,8 +1614,12 @@ const UNSTAMPED_DIRECT_ROWS = 82;* rewrites a signal page's `entities:` line through the shared atomic* writer on the apply arm - a dry-run-by-default repair pass over* existing signal pages; no origin stamp on a maintenance repair.+ * 122 -> 123: the cross-topic rule promotion (`src/core/brain/+ * dream-plan-cross-topic.ts`) writes its `Brain/cross-topic-rules.json`+ * daily-budget ledger through the shared atomic writer when a promotion+ * fires (machine state beside the rollup ledger; no origin stamp).*/-const UNSTAMPED_SHARED_ROWS = 122;+const UNSTAMPED_SHARED_ROWS = 123;describe("in-vault write-site census", () => {test("every direct-fs write site carries a written exclusion", () => {diff --git a/tests/core/bench/guards.test.ts b/tests/core/bench/guards.test.tsnew file mode 100644index 00000000..2bad2d32--- /dev/null+++ b/tests/core/bench/guards.test.ts@@ -0,0 +1,817 @@+/**+ * Bench-run integrity guards (t_d7ce8baf): the refusal vocabulary, the+ * pre-run preflight (P1-P7) and the pre-report trace validation (T1-T7),+ * each on hand-built fixtures.+ *+ * The doctrine the guards serve: a degraded run must neither CREATE state+ * (orphan run directories) nor PUBLISH scores (plausible-looking reports+ * off a tampered trace), and an all-questions-failed run stays a+ * legitimate benchmark outcome - score CONTENT never triggers refusal,+ * only structural damage does. Present-but-empty trace fields are+ * legitimate misses; absent ones are not.+ */++import { afterEach, beforeEach, describe, expect, test } from "bun:test";+import {+ chmodSync,+ existsSync,+ mkdirSync,+ mkdtempSync,+ readFileSync,+ rmSync,+ writeFileSync,+} from "node:fs";+import { tmpdir } from "node:os";+import { join } from "node:path";++import {+ BENCH_REFUSAL,+ BENCH_REFUSAL_KINDS,+ BenchRefusalError,+ countQuestionResults,+ preflightBenchRun,+ validateBenchTrace,+} from "../../../src/core/bench/guards.ts";+import { fixtureHash, parseBenchFixture } from "../../../src/core/bench/fixture.ts";+import { completeBenchPhase, createBenchRun } from "../../../src/core/bench/run-store.ts";+import { CHMOD_CANNOT_DENY } from "../../helpers/platform.ts";+import type {+ BenchFixture,+ BenchQuestionResult,+ BenchReport,+} from "../../../src/core/bench/types.ts";++let runsDir: string;++beforeEach(() => {+ runsDir = mkdtempSync(join(tmpdir(), "o2b-bench-guards-"));+});++afterEach(() => {+ rmSync(runsDir, { recursive: true, force: true });+});++const FIXTURE = parseBenchFixture({+ name: "guards",+ notes: [{ path: "Brain/notes/a.md", body: "alpha note body" }],+ continuity: [+ {+ kind: "session_turn",+ created_at: "2026-06-01T10:00:00.000Z",+ payload: { session_id: "s-1", turn_id: "t-1", role: "user", text: "hello" },+ },+ ],+ questions: [+ {+ id: "q1",+ category: "single_hop",+ query: "alpha",+ expected_paths: ["Brain/notes/a.md"],+ },+ {+ id: "q-handoff",+ category: "session_handoff",+ session_id: "s-1",+ expected_turns: 1,+ },+ ],+});++/** A checkpoint file, written the way the pipeline writes it. */+function writeCheckpoint(runId: string, phases: string[], fixture: BenchFixture = FIXTURE): string {+ const runDir = join(runsDir, runId);+ mkdirSync(runDir, { recursive: true });+ const checkpoint = {+ run_id: runId,+ fixture_name: fixture.name,+ fixture_hash: fixtureHash(fixture),+ pinned_knobs: { semantic: { enabled: false } },+ knobs_hash: "0123456789abcdef0123456789abcdef",+ created_at: "2026-06-03T12:00:00.000Z",+ completed_phases: phases,+ };+ writeFileSync(join(runDir, "checkpoint.json"), `${JSON.stringify(checkpoint, null, 2)}\n`);+ return runDir;+}++/** Materialize the disposable vault a completed ingest phase promises. */+function writeVault(runDir: string, fixture: BenchFixture = FIXTURE): void {+ mkdirSync(join(runDir, "vault", "Brain", "notes"), { recursive: true });+ for (const note of fixture.notes) {+ writeFileSync(join(runDir, "vault", note.path), note.body);+ }+}++/** A hand-built passing report the counts helper must agree with. */+function handReport(quality: BenchReport["quality"]): BenchReport {+ return {+ schema: "o2b.bench.v2",+ run_id: "run-x",+ fixture: "guards",+ fixture_hash: "0123456789abcdef",+ created_at: "2026-06-03T12:00:00.000Z",+ quality,+ latency_ms: { avg: 1, max: 1 },+ context_cost: { avg_chars: 0, avg_injected_tokens: 0 },+ failure_modes: {+ know_to_ask_failure_rate: 0,+ false_fire_rate: 0,+ source_isolation_violations: 0,+ },+ judge: { status: "skipped" },+ questions: [],+ } as BenchReport;+}++describe("the BENCH_REFUSAL vocabulary", () => {+ test("the table is frozen, closed, and every kind renders through the error", () => {+ expect(Object.isFrozen(BENCH_REFUSAL)).toBe(true);+ expect(Object.isFrozen(BENCH_REFUSAL_KINDS)).toBe(true);+ // One member per P1-P7 / T1-T7 state the recon names.+ expect([...BENCH_REFUSAL_KINDS].toSorted()).toEqual([+ "checkpoint_fixture_mismatch",+ "checkpoint_phase_order",+ "checkpoint_phase_unknown",+ "checkpoint_unparseable",+ "fixture_cross_reference",+ "report_counts_mismatch",+ "run_artifact_missing",+ "run_dir_exists",+ "runs_dir_unusable",+ "trace_extra_results",+ "trace_faulted_decisions",+ "trace_field_absent",+ "trace_id_mismatch",+ "trace_result_missing",+ "trace_result_unparseable",+ ]);+ const error = new BenchRefusalError(BENCH_REFUSAL.runDirExists, "already there");+ expect(error).toBeInstanceOf(Error);+ expect(error.kind).toBe("run_dir_exists");+ expect(error.detail).toBe("already there");+ expect(error.message).toBe("refused (run_dir_exists): already there");+ });+});++describe("preflightBenchRun", () => {+ test("a traversal resume id is refused by name before any checkpoint read", () => {+ // Findings 30: the preflight used to join and READ+ // `<runsDir>/<resume>/checkpoint.json` before any run-id guard ran, so+ // `--resume ..` answered with whatever parse error the PARENT+ // directory's checkpoint.json carries. The bait sits exactly at the+ // path the unguarded join used to read.+ const root = join(runsDir, "root");+ const runs = join(root, "runs");+ mkdirSync(runs, { recursive: true });+ writeFileSync(join(root, "checkpoint.json"), "{not json");+ try {+ preflightBenchRun({ runsDir: runs, fixture: FIXTURE, resume: ".." });+ throw new Error("expected the preflight to refuse");+ } catch (e) {+ const message = (e as Error).message;+ // Refused BY NAME - the id - never by the parent file's parse error.+ expect(message).toContain("..");+ expect(message).toMatch(/all dots|unsafe characters|escapes the runs dir/);+ expect(message).not.toContain("checkpoint_unparseable");+ }+ // The charset arm: a path-escaping id is refused by name too.+ try {+ preflightBenchRun({ runsDir: runs, fixture: FIXTURE, resume: "../escape" });+ throw new Error("expected the preflight to refuse");+ } catch (e) {+ const message = (e as Error).message;+ expect(message).toContain("../escape");+ expect(message).toContain("unsafe characters");+ expect(message).not.toContain("checkpoint_unparseable");+ }+ });++ test("a healthy fresh run and a healthy resume pass silently", () => {+ const run = createBenchRun(runsDir, FIXTURE, { now: new Date("2026-06-03T12:00:00Z") });+ writeVault(run.runDir);+ completeBenchPhase(run.runDir, run.checkpoint, "ingest");+ // Fresh: the collision check needs the id the caller is about to create.+ expect(() =>+ preflightBenchRun({ runsDir, fixture: FIXTURE, freshRunId: "run-20260603120001-abc123" }),+ ).not.toThrow();+ // Resume: the claimed phases have their artifacts.+ expect(() => preflightBenchRun({ runsDir, fixture: FIXTURE, resume: run.runId })).not.toThrow();+ });++ test("an unwritable runs directory is refused before anything is created", () => {+ // A FILE where the runs dir belongs: mkdir fails whatever the user.+ const blocker = join(runsDir, "blocked");+ writeFileSync(blocker, "not a directory");+ try {+ preflightBenchRun({ runsDir: blocker, fixture: FIXTURE, freshRunId: "run-x" });+ throw new Error("expected the preflight to refuse");+ } catch (e) {+ expect(e).toBeInstanceOf(BenchRefusalError);+ const refusal = e as BenchRefusalError;+ expect(refusal.kind).toBe("runs_dir_unusable");+ expect(refusal.detail).toContain(blocker);+ expect(refusal.detail).toContain("--runs-dir");+ }+ expect(existsSync(join(blocker, "run-x"))).toBe(false);+ });++ describe("a chmod-read-only runs directory", () => {+ // chmod cannot build this denial on root or on Windows; the shared+ // platform fact names that once, and the deny-guard census reads it.+ const gatedTest = test.skipIf(CHMOD_CANNOT_DENY);+ gatedTest("is refused by the writability probe", () => {+ const readOnly = join(runsDir, "read-only");+ mkdirSync(readOnly);+ chmodSync(readOnly, 0o555);+ try {+ preflightBenchRun({ runsDir: readOnly, fixture: FIXTURE, freshRunId: "run-x" });+ throw new Error("expected the preflight to refuse");+ } catch (e) {+ expect((e as BenchRefusalError).kind).toBe("runs_dir_unusable");+ } finally {+ chmodSync(readOnly, 0o755);+ }+ });+ });++ test("a fresh-run collision is refused naming --resume, and the prior checkpoint survives", () => {+ const run = createBenchRun(runsDir, FIXTURE, { now: new Date("2026-06-03T12:00:00Z") });+ const before = readFileSync(join(run.runDir, "checkpoint.json"), "utf8");+ try {+ preflightBenchRun({ runsDir, fixture: FIXTURE, freshRunId: run.runId });+ throw new Error("expected the preflight to refuse");+ } catch (e) {+ const refusal = e as BenchRefusalError;+ expect(refusal.kind).toBe("run_dir_exists");+ expect(refusal.detail).toContain(run.runId);+ expect(refusal.detail).toContain(`--resume ${run.runId}`);+ }+ // The collision left the prior run exactly as it was.+ expect(readFileSync(join(run.runDir, "checkpoint.json"), "utf8")).toBe(before);+ });++ test("resuming the colliding run itself is not a collision", () => {+ const run = createBenchRun(runsDir, FIXTURE, { now: new Date("2026-06-03T12:00:00Z") });+ expect(() =>+ preflightBenchRun({ runsDir, fixture: FIXTURE, resume: run.runId, freshRunId: run.runId }),+ ).not.toThrow();+ });++ test("a corrupt checkpoint on resume is refused naming the file", () => {+ const runDir = writeCheckpoint("run-broken", []);+ writeFileSync(join(runDir, "checkpoint.json"), "{not json");+ try {+ preflightBenchRun({ runsDir, fixture: FIXTURE, resume: "run-broken" });+ throw new Error("expected the preflight to refuse");+ } catch (e) {+ const refusal = e as BenchRefusalError;+ expect(refusal.kind).toBe("checkpoint_unparseable");+ expect(refusal.detail).toContain(join(runDir, "checkpoint.json"));+ }+ });++ test("a checkpoint that parses but lacks required fields is refused as unparseable", () => {+ // M11: {"completed_phases":["ingest"]} passes P3's JSON-object and+ // phases-array checks (and P5 when the artifacts happen to exist), and+ // used to explode later in parseCheckpoint as a plain Error the verb+ // does not catch - a source frame where the contract promises+ // `refused (checkpoint_unparseable)`. The preflight now runs the SAME+ // parser, so the refusal names the file and the missing fields.+ const runDir = join(runsDir, "run-minimal");+ mkdirSync(join(runDir, "vault", "Brain", "notes"), { recursive: true });+ writeFileSync(join(runDir, "vault", "Brain", "notes", "a.md"), "alpha note body");+ writeFileSync(+ join(runDir, "checkpoint.json"),+ `${JSON.stringify({ completed_phases: ["ingest"] })}\n`,+ );+ try {+ preflightBenchRun({ runsDir, fixture: FIXTURE, resume: "run-minimal" });+ throw new Error("expected the preflight to refuse");+ } catch (e) {+ const refusal = e as BenchRefusalError;+ expect(refusal).toBeInstanceOf(BenchRefusalError);+ expect(refusal.kind).toBe("checkpoint_unparseable");+ expect(refusal.detail).toContain(join(runDir, "checkpoint.json"));+ expect(refusal.detail).toContain("run_id");+ }+ // The empty-phases shape passes P3 AND P5 entirely; the parser gate is+ // what refuses it, so the run never reaches the raw load error.+ writeFileSync(join(runDir, "checkpoint.json"), `${JSON.stringify({ completed_phases: [] })}\n`);+ try {+ preflightBenchRun({ runsDir, fixture: FIXTURE, resume: "run-minimal" });+ throw new Error("expected the preflight to refuse");+ } catch (e) {+ expect((e as BenchRefusalError).kind).toBe("checkpoint_unparseable");+ }+ // A checkpoint with the full shape the parser requires still passes.+ const healthy = writeCheckpoint("run-full-shape", ["ingest"]);+ writeVault(healthy);+ expect(() =>+ preflightBenchRun({ runsDir, fixture: FIXTURE, resume: "run-full-shape" }),+ ).not.toThrow();+ });++ test("a checkpoint whose completed_phases is not a string array is refused", () => {+ writeCheckpoint("run-shape", "ingest" as unknown as string[]);+ expect(() => preflightBenchRun({ runsDir, fixture: FIXTURE, resume: "run-shape" })).toThrow(+ /checkpoint/,+ );+ });++ test("an unknown phase name is refused as written by a different build", () => {+ writeCheckpoint("run-future", ["ingest", "quantum_phase"]);+ try {+ preflightBenchRun({ runsDir, fixture: FIXTURE, resume: "run-future" });+ throw new Error("expected the preflight to refuse");+ } catch (e) {+ const refusal = e as BenchRefusalError;+ expect(refusal.kind).toBe("checkpoint_phase_unknown");+ expect(refusal.detail).toContain("quantum_phase");+ expect(refusal.detail).toContain("different build");+ }+ });++ test("out-of-order and duplicate completed phases are refused", () => {+ writeCheckpoint("run-swapped", ["retrieve", "ingest"]);+ try {+ preflightBenchRun({ runsDir, fixture: FIXTURE, resume: "run-swapped" });+ throw new Error("expected the preflight to refuse");+ } catch (e) {+ expect((e as BenchRefusalError).kind).toBe("checkpoint_phase_order");+ }+ writeCheckpoint("run-duped", ["ingest", "ingest"]);+ try {+ preflightBenchRun({ runsDir, fixture: FIXTURE, resume: "run-duped" });+ throw new Error("expected the preflight to refuse");+ } catch (e) {+ expect((e as BenchRefusalError).kind).toBe("checkpoint_phase_order");+ }+ });++ test("resuming with a different fixture is refused as a fixture mismatch naming the repair", () => {+ // The run directory matches its own checkpoint; only the fixture given+ // to THIS resume differs - an edited copy of the same fixture. The+ // preflight refuses by name with the seed-aware repair, and the run+ // directory is never condemned as tampered.+ const runDir = writeCheckpoint("run-fixture", ["ingest"]);+ writeVault(runDir);+ const raw = JSON.parse(JSON.stringify(FIXTURE)) as {+ notes: Array<{ path: string; body: string }>;+ };+ raw.notes[0]!.body = "an edited body under the same path";+ const edited = parseBenchFixture(raw);+ try {+ preflightBenchRun({ runsDir, fixture: edited, resume: "run-fixture" });+ throw new Error("expected the preflight to refuse");+ } catch (e) {+ const refusal = e as BenchRefusalError;+ expect(refusal.kind).toBe("checkpoint_fixture_mismatch");+ expect(refusal.detail).toContain(join(runDir, "checkpoint.json"));+ expect(refusal.detail).toContain(fixtureHash(FIXTURE));+ expect(refusal.detail).toContain(fixtureHash(edited));+ expect(refusal.detail).toContain("same fixture, seed and cap");+ }+ });++ test("a fixture mismatch is named before the artifact check on a damaged run", () => {+ // The misreport the fix removes: an interrupted run resumed under a+ // different fixture used to fail P5 first - `run_artifact_missing`+ // ... "tampered with or truncated; start a fresh run" - repair advice+ // that discards a run perfectly healthy under its own fixture.+ writeCheckpoint("run-mismatch", ["ingest"]);+ const raw = JSON.parse(JSON.stringify(FIXTURE)) as {+ notes: Array<{ path: string; body: string }>;+ };+ raw.notes[0]!.body = "an edited body under the same path";+ const edited = parseBenchFixture(raw);+ try {+ preflightBenchRun({ runsDir, fixture: edited, resume: "run-mismatch" });+ throw new Error("expected the preflight to refuse");+ } catch (e) {+ const refusal = e as BenchRefusalError;+ expect(refusal.kind).toBe("checkpoint_fixture_mismatch");+ expect(refusal.kind).not.toBe("run_artifact_missing");+ }+ });++ test("ingest-done with the vault deleted is refused before any scoring", () => {+ // The dangerous tamper: retrieval against the emptied vault would+ // score an empty corpus and publish ordinary FAILs.+ const runDir = writeCheckpoint("run-tampered", ["ingest"]);+ try {+ preflightBenchRun({ runsDir, fixture: FIXTURE, resume: "run-tampered" });+ throw new Error("expected the preflight to refuse");+ } catch (e) {+ const refusal = e as BenchRefusalError;+ expect(refusal.kind).toBe("run_artifact_missing");+ expect(refusal.detail).toContain(join(runDir, "vault"));+ expect(refusal.detail).toContain("fresh run");+ }+ });++ test("ingest-done with a fixture note missing from the vault is refused by path", () => {+ const runDir = writeCheckpoint("run-partial-vault", ["ingest"]);+ writeVault(runDir);+ rmSync(join(runDir, "vault", "Brain", "notes", "a.md"));+ try {+ preflightBenchRun({ runsDir, fixture: FIXTURE, resume: "run-partial-vault" });+ throw new Error("expected the preflight to refuse");+ } catch (e) {+ const refusal = e as BenchRefusalError;+ expect(refusal.kind).toBe("run_artifact_missing");+ expect(refusal.detail).toContain("Brain/notes/a.md");+ }+ });++ test("a finished run stays resumable with the disposable vault deleted", () => {+ // The doctrine the resume test pins: evaluate works only from the+ // persisted results, so a completed run does not need the vault.+ const runDir = writeCheckpoint("run-done", [+ "ingest",+ "index",+ "retrieve",+ "evaluate",+ "report",+ ]);+ writeVault(runDir);+ mkdirSync(join(runDir, "results"), { recursive: true });+ for (const question of FIXTURE.questions) {+ writeFileSync(+ join(runDir, "results", `${question.id}.json`),+ `${JSON.stringify({ id: question.id, latency_ms: 1 })}\n`,+ );+ }+ writeFileSync(join(runDir, "report.json"), "{}\n");+ rmSync(join(runDir, "vault"), { recursive: true, force: true });+ expect(() =>+ preflightBenchRun({ runsDir, fixture: FIXTURE, resume: "run-done" }),+ ).not.toThrow();+ });++ test("retrieve-done with the results deleted is refused by name", () => {+ const runDir = writeCheckpoint("run-no-results", ["ingest", "index", "retrieve"]);+ writeVault(runDir);+ try {+ preflightBenchRun({ runsDir, fixture: FIXTURE, resume: "run-no-results" });+ throw new Error("expected the preflight to refuse");+ } catch (e) {+ const refusal = e as BenchRefusalError;+ expect(refusal.kind).toBe("run_artifact_missing");+ expect(refusal.detail).toContain(join(runDir, "results"));+ }+ });++ test("report-done without report.json is refused by name", () => {+ const runDir = writeCheckpoint("run-no-report", [+ "ingest",+ "index",+ "retrieve",+ "evaluate",+ "report",+ ]);+ writeVault(runDir);+ mkdirSync(join(runDir, "results"), { recursive: true });+ for (const question of FIXTURE.questions) {+ writeFileSync(join(runDir, "results", `${question.id}.json`), "{}\n");+ }+ try {+ preflightBenchRun({ runsDir, fixture: FIXTURE, resume: "run-no-report" });+ throw new Error("expected the preflight to refuse");+ } catch (e) {+ const refusal = e as BenchRefusalError;+ expect(refusal.kind).toBe("run_artifact_missing");+ expect(refusal.detail).toContain("report.json");+ }+ });++ test("an expected_path naming a nonexistent note is refused naming the question", () => {+ const bad = parseBenchFixture({+ name: "bad-xref",+ notes: [{ path: "Brain/notes/a.md", body: "alpha note body" }],+ questions: [+ {+ id: "q-bad",+ category: "single_hop",+ query: "alpha",+ expected_paths: ["Brain/notes/never-materialized.md"],+ },+ ],+ });+ try {+ preflightBenchRun({ runsDir, fixture: bad, freshRunId: "run-x" });+ throw new Error("expected the preflight to refuse");+ } catch (e) {+ const refusal = e as BenchRefusalError;+ expect(refusal.kind).toBe("fixture_cross_reference");+ expect(refusal.detail).toContain("q-bad");+ expect(refusal.detail).toContain("Brain/notes/never-materialized.md");+ }+ });++ test("a not_expected_above path naming a nonexistent note is refused too", () => {+ const bad = parseBenchFixture({+ name: "bad-stale-xref",+ notes: [{ path: "Brain/notes/a.md", body: "alpha note body" }],+ questions: [+ {+ id: "q-stale",+ category: "temporal",+ query: "alpha",+ expected_paths: ["Brain/notes/a.md"],+ not_expected_above: ["Brain/notes/ghost.md"],+ },+ ],+ });+ expect(() => preflightBenchRun({ runsDir, fixture: bad, freshRunId: "run-x" })).toThrow(+ /q-stale.*Brain\/notes\/ghost\.md|Brain\/notes\/ghost\.md.*q-stale/s,+ );+ });++ test("a session_handoff question naming an unknown session is refused naming the value", () => {+ const bad = parseBenchFixture({+ name: "bad-session-xref",+ notes: [{ path: "Brain/notes/a.md", body: "alpha note body" }],+ questions: [+ {+ id: "q-orphan",+ category: "session_handoff",+ session_id: "s-unknown",+ },+ ],+ });+ try {+ preflightBenchRun({ runsDir, fixture: bad, freshRunId: "run-x" });+ throw new Error("expected the preflight to refuse");+ } catch (e) {+ const refusal = e as BenchRefusalError;+ expect(refusal.kind).toBe("fixture_cross_reference");+ expect(refusal.detail).toContain("q-orphan");+ expect(refusal.detail).toContain("s-unknown");+ }+ });++ test("the preflight adds zero stdout on success", () => {+ const run = createBenchRun(runsDir, FIXTURE, { now: new Date("2026-06-03T12:00:00Z") });+ writeVault(run.runDir);+ completeBenchPhase(run.runDir, run.checkpoint, "ingest");+ const writes: string[] = [];+ const original = process.stdout.write;+ process.stdout.write = ((chunk?: unknown) => {+ writes.push(String(chunk));+ return true;+ }) as typeof process.stdout.write;+ try {+ preflightBenchRun({ runsDir, fixture: FIXTURE, resume: run.runId });+ } finally {+ process.stdout.write = original;+ }+ expect(writes).toEqual([]);+ });+});++/** Write one per-question trace record the way the builders do. */+function traceRecord(fields: Record<string, unknown>): string {+ return `${JSON.stringify({ id: "q1", latency_ms: 1, ...fields }, null, 2)}\n`;+}++describe("validateBenchTrace", () => {+ /** A one-retrieval-question fixture with its results dir prepared. */+ function retrievalRun(recordBody: string, extraFile?: string): string {+ const runDir = join(runsDir, "run-trace");+ mkdirSync(join(runDir, "results"), { recursive: true });+ writeFileSync(join(runDir, "results", "q1.json"), recordBody);+ if (extraFile !== undefined) {+ writeFileSync(join(runDir, "results", extraFile), "{}\n");+ }+ return runDir;+ }++ const TRACE_FIXTURE = parseBenchFixture({+ name: "trace",+ notes: [{ path: "Brain/notes/a.md", body: "alpha note body" }],+ questions: [+ { id: "q1", category: "single_hop", query: "alpha", expected_paths: ["Brain/notes/a.md"] },+ ],+ });++ test("a healthy trace passes", () => {+ const runDir = retrievalRun(traceRecord({ paths: ["Brain/notes/a.md"] }));+ expect(() => validateBenchTrace({ runDir, fixture: TRACE_FIXTURE })).not.toThrow();+ });++ test("a missing result file is refused naming the question", () => {+ const runDir = retrievalRun("{}");+ rmSync(join(runDir, "results", "q1.json"));+ try {+ validateBenchTrace({ runDir, fixture: TRACE_FIXTURE });+ throw new Error("expected the trace validation to refuse");+ } catch (e) {+ const refusal = e as BenchRefusalError;+ expect(refusal.kind).toBe("trace_result_missing");+ expect(refusal.detail).toContain("q1");+ }+ });++ test("a truncated result file is refused naming the file", () => {+ const runDir = retrievalRun('{"id": "q1", "laten');+ try {+ validateBenchTrace({ runDir, fixture: TRACE_FIXTURE });+ throw new Error("expected the trace validation to refuse");+ } catch (e) {+ const refusal = e as BenchRefusalError;+ expect(refusal.kind).toBe("trace_result_unparseable");+ expect(refusal.detail).toContain(join(runDir, "results", "q1.json"));+ }+ });++ test("a record stored under the wrong question id is refused", () => {+ const runDir = retrievalRun(traceRecord({ id: "q-other", paths: [] }));+ try {+ validateBenchTrace({ runDir, fixture: TRACE_FIXTURE });+ throw new Error("expected the trace validation to refuse");+ } catch (e) {+ const refusal = e as BenchRefusalError;+ expect(refusal.kind).toBe("trace_id_mismatch");+ expect(refusal.detail).toContain("q-other");+ expect(refusal.detail).toContain("q1");+ }+ });++ test("an extra result file beyond the fixture's questions is refused", () => {+ const runDir = retrievalRun(traceRecord({ paths: [] }), "q-leftover.json");+ try {+ validateBenchTrace({ runDir, fixture: TRACE_FIXTURE });+ throw new Error("expected the trace validation to refuse");+ } catch (e) {+ const refusal = e as BenchRefusalError;+ expect(refusal.kind).toBe("trace_extra_results");+ expect(refusal.detail).toContain("q-leftover.json");+ }+ });++ test("an orphaned atomic-write temp does not make a crashed run unresumable", () => {+ // Finding 29: a SIGKILL between the atomic write and its rename leaves+ // `<id>.json.<pid>.tmp` in results/ (the rmSync cleanup only runs on a+ // thrown error), and T6 counting it as an extra refused the resumed+ // run - the crash recovery the atomic writes and resume exist for+ // demanded a manual rm first. The writer's own temp shape is exempt.+ const crashed = retrievalRun(traceRecord({ paths: [] }), "q1.json.424242.tmp");+ expect(() => validateBenchTrace({ runDir: crashed, fixture: TRACE_FIXTURE })).not.toThrow();+ // T6 still stands for real junk: any other leftover refuses.+ const leftover = retrievalRun(traceRecord({ paths: [] }), "q-leftover.json");+ try {+ validateBenchTrace({ runDir: leftover, fixture: TRACE_FIXTURE });+ throw new Error("expected the trace validation to refuse");+ } catch (e) {+ expect((e as BenchRefusalError).kind).toBe("trace_extra_results");+ }+ });++ test("each category family refuses an ABSENT required field but passes present-but-empty", () => {+ // (category, required field, the question, the record with the field+ // present but empty - the legitimate miss the guard must never+ // refuse.) Questions carry their category's parse-required shape.+ const families: ReadonlyArray<{+ category: string;+ field: string;+ question: Record<string, unknown>;+ presentButEmpty: unknown;+ }> = [+ {+ category: "single_hop",+ field: "paths",+ question: { query: "alpha", expected_paths: ["Brain/notes/a.md"] },+ presentButEmpty: [],+ },+ {+ category: "session_handoff",+ field: "turn_texts",+ question: { session_id: "s-1" },+ presentButEmpty: [],+ },+ {+ category: "budget",+ field: "item_ids",+ question: { expected_ids: ["x"] },+ presentButEmpty: [],+ },+ {+ category: "source_isolation",+ field: "item_ids",+ question: { agent_scope: "a", forbidden_ids: ["f"] },+ presentButEmpty: [],+ },+ {+ category: "proactive_recall",+ field: "recall_decision",+ question: { prompt: "p", expect_inject: true },+ presentButEmpty: { kind: "abstain", reason: "structural" },+ },+ {+ category: "write_fidelity",+ field: "labels",+ question: { intake_text: "text", expected_labels: ["label"] },+ presentButEmpty: [],+ },+ {+ category: "standing_instruction",+ field: "standing_items",+ question: {},+ presentButEmpty: [],+ },+ ];+ for (const { category, field, question, presentButEmpty } of families) {+ const fixture = parseBenchFixture({+ name: `trace-${category}`,+ notes: [{ path: "Brain/notes/a.md", body: "alpha note body" }],+ questions: [{ id: "q1", category, ...question } as never],+ });+ const runDir = join(runsDir, `run-${category}`);+ mkdirSync(join(runDir, "results"), { recursive: true });+ // Absent: the field is not in the record at all - structural damage+ // the evaluator would silently default into an ordinary FAIL.+ const absent: Record<string, unknown> = { id: "q1", latency_ms: 1 };+ writeFileSync(join(runDir, "results", "q1.json"), traceRecord(absent));+ let refusal: BenchRefusalError | undefined;+ try {+ validateBenchTrace({ runDir, fixture });+ } catch (e) {+ refusal = e as BenchRefusalError;+ }+ expect(`${category} absent ${field} refused: ${refusal?.kind}`).toBe(+ `${category} absent ${field} refused: trace_field_absent`,+ );+ expect(refusal!.detail).toContain(field);+ expect(refusal!.detail).toContain("q1");+ // Present but empty: a legitimate retrieval miss, never a refusal.+ writeFileSync(join(runDir, "results", "q1.json"), traceRecord({ [field]: presentButEmpty }));+ expect(() => validateBenchTrace({ runDir, fixture })).not.toThrow();+ }+ });++ test("a faulted proactive decision is refused with the fresh-run repair", () => {+ const fixture = parseBenchFixture({+ name: "trace-faulted",+ notes: [{ path: "Brain/notes/a.md", body: "alpha note body" }],+ questions: [{ id: "q1", category: "proactive_recall", prompt: "p", expect_inject: true }],+ });+ const runDir = join(runsDir, "run-faulted");+ mkdirSync(join(runDir, "results"), { recursive: true });+ writeFileSync(+ join(runDir, "results", "q1.json"),+ traceRecord({ recall_decision: { kind: "error", fault: "retrieval_error" } }),+ );+ try {+ validateBenchTrace({ runDir, fixture });+ throw new Error("expected the trace validation to refuse");+ } catch (e) {+ const refusal = e as BenchRefusalError;+ expect(refusal.kind).toBe("trace_faulted_decisions");+ expect(refusal.detail).toContain("q1");+ expect(refusal.detail).toContain("retrieval_error");+ expect(refusal.detail).toContain("fresh run");+ }+ });++ test("a report whose counts disagree with its trace is refused", () => {+ const runDir = retrievalRun(traceRecord({ paths: [] }));+ const results: ReadonlyArray<BenchQuestionResult> = [+ { id: "q1", category: "single_hop", pass: true, latency_ms: 1 },+ ];+ // The report claims a different headline than the results carry.+ const report = handReport({+ passed: 0,+ total: 1,+ pass_rate: 0,+ by_category: { single_hop: { passed: 0, total: 1 } },+ });+ try {+ validateBenchTrace({ runDir, fixture: TRACE_FIXTURE, results, report });+ throw new Error("expected the trace validation to refuse");+ } catch (e) {+ const refusal = e as BenchRefusalError;+ expect(refusal.kind).toBe("report_counts_mismatch");+ expect(refusal.detail).toContain("passed");+ }+ });++ test("counts agree on a passing run that includes the headline-excluded category", () => {+ const runDir = retrievalRun(traceRecord({ paths: [] }));+ const results: ReadonlyArray<BenchQuestionResult> = [+ { id: "q1", category: "single_hop", pass: true, latency_ms: 1 },+ { id: "q-standing", category: "standing_instruction", pass: false, latency_ms: 1 },+ ];+ const counts = countQuestionResults(results);+ const report = handReport({+ passed: counts.passed,+ total: counts.total,+ pass_rate: counts.total > 0 ? counts.passed / counts.total : 0,+ by_category: counts.byCategory,+ });+ expect(counts.total).toBe(1);+ expect(counts.byCategory["standing_instruction"]).toEqual({ passed: 0, total: 1 });+ expect(() =>+ validateBenchTrace({ runDir, fixture: TRACE_FIXTURE, results, report }),+ ).not.toThrow();+ });+});diff --git a/tests/core/bench/phases.test.ts b/tests/core/bench/phases.test.tsindex c081a78c..d993aeb4 100644--- a/tests/core/bench/phases.test.ts+++ b/tests/core/bench/phases.test.ts@@ -16,13 +16,17 @@ import {benchVectorCacheKey,} from "../../../src/core/bench/embedding-cache.ts";import { parseBenchFixture } from "../../../src/core/bench/fixture.ts";+import { countQuestionResults } from "../../../src/core/bench/guards.ts";+import { loadLongMemEvalFixture } from "../../../src/core/bench/longmemeval.ts";import { FAKE_PROVIDER_KEY } from "../../helpers/fake-credentials.ts";import { benchSearchConfig, runMemoryBench } from "../../../src/core/bench/phases.ts";+import { completeBenchPhase, createBenchRun } from "../../../src/core/bench/run-store.ts";import {BENCH_REPORT_SCHEMA,DEFAULT_BENCH_KNOB_PIN,type BenchPinnedKnobs,} from "../../../src/core/bench/types.ts";+import { cmdBrainBench } from "../../../src/cli/brain/verbs/bench.ts";import { LOCAL_DEFAULT_DIMENSION } from "../../../src/core/search/embeddings/local-provider.ts";import { LOCAL_EMBEDDING_MODEL } from "../../../src/core/search/embeddings/signature.ts";@@ -111,6 +115,22 @@ const FIXTURE = parseBenchFixture({],});+/**+ * One minimal LongMemEval dataset entry: a single-hop question over one+ * one-turn haystack session, shaped the way the suite parser reads it.+ */+function longMemEvalEntry(id: string) {+ return {+ q_id: id,+ question_type: "single-hop",+ question: `what does note ${id} say`,+ haystack_session_id: [`s-${id}`],+ haystack_session: [[{ role: "user", content: `note ${id} body` }]],+ haystack_dates: ["2023-05-20"],+ answer_session_ids: [`s-${id}`],+ };+}+describe("runMemoryBench", () => {test("the default bench config pins the semantic lane off", () => {// The resolved config is where network-freedom is real: the pin must@@ -193,16 +213,51 @@ describe("runMemoryBench", () => {expect(existsSync(join(runsDir, first.run_id, "vault"))).toBe(false);}, 30_000);- test("resume with a changed fixture fails fast on the hash guard", async () => {+ test("resume with a changed fixture is refused as a named fixture mismatch", async () => {const first = await runMemoryBench({ fixture: FIXTURE, runsDir });- const changed = parseBenchFixture({- ...JSON.parse(JSON.stringify(FIXTURE)),- name: "phase-suite",- notes: [{ path: "Brain/notes/x.md", body: "different" }],- });+ // Change the fixture CONTENT while keeping every referenced note path:+ // the preflight's cross-reference guard (P7) must stay out of the way+ // so the fixture mismatch is the refusal this pin is about.+ const raw = JSON.parse(JSON.stringify(FIXTURE)) as {+ notes: Array<{ path: string; body: string }>;+ };+ raw.notes[0]!.body = "# Coffee preference\n\nA different body under the same path.\n";+ const changed = parseBenchFixture(raw);await expect(runMemoryBench({ fixture: changed, runsDir, resume: first.run_id }),- ).rejects.toThrow("hash");+ ).rejects.toThrow(/refused \(checkpoint_fixture_mismatch\).*same fixture, seed and cap/s);+ }, 30_000);++ test("a LongMemEval resume under a different sample seed is a named fixture mismatch", async () => {+ // The seeded sampler selects a different subset per seed, so the+ // fixture a different `--sample-seed` loads is a DIFFERENT fixture+ // under the same dataset. The resume must be refused by name with the+ // seed-aware repair - never misread as a tampered run directory and+ // never as the raw load error the verb does not render.+ const datasetPath = join(runsDir, "dataset.json");+ writeFileSync(+ datasetPath,+ JSON.stringify({+ name: "seeded",+ questions: [+ longMemEvalEntry("a"),+ longMemEvalEntry("b"),+ longMemEvalEntry("c"),+ longMemEvalEntry("d"),+ ],+ }),+ );+ const seedA = loadLongMemEvalFixture(datasetPath, { sample: { seed: "seed-a", cap: 2 } });+ const seedB = loadLongMemEvalFixture(datasetPath, { sample: { seed: "seed-b", cap: 2 } });+ // The seeds select different questions, so the resumed fixture's+ // CONTENT differs - not just the sampling options.+ expect(seedA.fixture.questions.map((q) => q.id)).not.toEqual(+ seedB.fixture.questions.map((q) => q.id),+ );+ const first = await runMemoryBench({ fixture: seedA.fixture, runsDir });+ await expect(+ runMemoryBench({ fixture: seedB.fixture, runsDir, resume: first.run_id }),+ ).rejects.toThrow(/refused \(checkpoint_fixture_mismatch\)/);}, 30_000);test("the default knob pin equals today's hardcoded semantic-off override", () => {@@ -342,6 +397,215 @@ describe("runMemoryBench", () => {runMemoryBench({ fixture: FIXTURE, runsDir, resume: first.run_id }),).rejects.toThrow(/run identity mismatch/);}, 30_000);++ test("a passing run publishes exactly the report shape it always had", async () => {+ const report = await runMemoryBench({ fixture: FIXTURE, runsDir });+ // The guards add no field: the serialized top-level key order IS the+ // published shape a baseline diffs.+ expect(Object.keys(report)).toEqual([+ "schema",+ "run_id",+ "fixture",+ "fixture_hash",+ "created_at",+ "quality",+ "latency_ms",+ "context_cost",+ "failure_modes",+ "judge",+ "questions",+ ]);+ // The quality family is the shared aggregation, by construction.+ const counts = countQuestionResults(report.questions);+ expect(report.quality.passed).toBe(counts.passed);+ expect(report.quality.total).toBe(counts.total);+ expect(report.quality.by_category).toEqual(counts.byCategory);+ // The published file equals the returned report, JSON for JSON.+ const onDisk = JSON.parse(+ readFileSync(join(runsDir, report.run_id, "report.json"), "utf8"),+ ) as unknown;+ expect(onDisk).toEqual(JSON.parse(JSON.stringify(report)));+ }, 30_000);++ test("a passing run writes zero stdout from the guards", async () => {+ const writes: string[] = [];+ const original = process.stdout.write;+ process.stdout.write = ((chunk?: unknown) => {+ writes.push(String(chunk));+ return true;+ }) as typeof process.stdout.write;+ try {+ await runMemoryBench({ fixture: FIXTURE, runsDir });+ } finally {+ process.stdout.write = original;+ }+ expect(writes).toEqual([]);+ }, 30_000);+});++/**+ * The integrity guards wired into the pipeline (t_d7ce8baf): refusals+ * fire BEFORE a run directory can exist (config/capability ordering),+ * a fresh-run collision preserves the prior run, a tampered run dir is+ * refused by name before any scoring, and the verb renders the refusal+ * contract `refused (<kind>): <detail>` on stderr with a nonzero exit.+ */+describe("the integrity guards wired in", () => {+ test("a traversal --resume id is refused before any run state exists", async () => {+ // Findings 30 + 31 end to end: the raw `--resume ..` value must be+ // refused by name by the preflight's run-id guard, never answered by+ // whatever the parent directory happens to hold, and no run state may+ // exist when it is.+ await expect(runMemoryBench({ fixture: FIXTURE, runsDir, resume: ".." })).rejects.toThrow(+ /all dots/,+ );+ expect(readdirSync(runsDir)).toEqual([]);+ });++ test("an env-garbage provider refusal leaves no run dir behind", async () => {+ const envKey = "OPEN_SECOND_BRAIN_EMBEDDING_PROVIDER";+ process.env[envKey] = "no-such-provider";+ try {+ await expect(runMemoryBench({ fixture: FIXTURE, runsDir })).rejects.toThrow(+ /embedding_provider must be/,+ );+ } finally {+ delete process.env[envKey];+ }+ expect(readdirSync(runsDir)).toEqual([]);+ }, 30_000);++ test("a capability-gate refusal leaves no run dir behind", async () => {+ await expect(+ runMemoryBench({+ fixture: FIXTURE,+ runsDir,+ pinnedKnobs: { semantic: { enabled: true, provider: "local" } },+ }),+ ).rejects.toThrow(/embeddings capability/);+ expect(readdirSync(runsDir)).toEqual([]);+ }, 30_000);++ test("a fresh-run collision is refused by name and the prior checkpoint survives", async () => {+ // The injected clock is the point: run ids are second-precision+ // timestamp + identity hex, so a wall-clock pair of back-to-back runs+ // collides only when both mint inside the same second - a race this+ // test lost about one full-suite run in fifty. One fixed instant for+ // both runs makes the collision a fact of the fixture, not of the+ // wall clock.+ const now = new Date("2026-06-03T12:00:00Z");+ const first = await runMemoryBench({ fixture: FIXTURE, runsDir, now });+ const checkpointBefore = readFileSync(join(runsDir, first.run_id, "checkpoint.json"), "utf8");+ await expect(runMemoryBench({ fixture: FIXTURE, runsDir, now })).rejects.toThrow(+ new RegExp(`refused \\(run_dir_exists\\).*--resume ${first.run_id}`),+ );+ expect(readFileSync(join(runsDir, first.run_id, "checkpoint.json"), "utf8")).toBe(+ checkpointBefore,+ );+ // The refused second run left no run dir of its own.+ expect(readdirSync(runsDir)).toEqual([first.run_id]);+ // And resuming the very same run keeps working.+ const resumed = await runMemoryBench({ fixture: FIXTURE, runsDir, resume: first.run_id, now });+ expect(resumed.run_id).toBe(first.run_id);+ }, 60_000);++ test("ingest-done with the vault deleted is refused before any scoring", async () => {+ // A partial run: only ingest is checkpointed, then the disposable+ // vault disappears. Retrieval against the emptied vault would score+ // an empty corpus and publish ordinary FAILs - refused by name.+ const run = createBenchRun(runsDir, FIXTURE, { now: new Date("2026-06-03T12:00:00Z") });+ completeBenchPhase(run.runDir, run.checkpoint, "ingest");+ rmSync(join(run.runDir, "vault"), { recursive: true, force: true });+ await expect(runMemoryBench({ fixture: FIXTURE, runsDir, resume: run.runId })).rejects.toThrow(+ /refused \(run_artifact_missing\)/,+ );+ // Refused before scoring: no results and no report exist.+ expect(existsSync(join(run.runDir, "results"))).toBe(false);+ expect(existsSync(join(run.runDir, "report.json"))).toBe(false);+ }, 30_000);++ test("retrieve-done with a result file deleted is refused naming the file", async () => {+ const first = await runMemoryBench({ fixture: FIXTURE, runsDir });+ rmSync(join(runsDir, first.run_id, "results", "q-multi.json"));+ await expect(+ runMemoryBench({ fixture: FIXTURE, runsDir, resume: first.run_id }),+ ).rejects.toThrow(/refused \(run_artifact_missing\).*q-multi\.json/s);+ }, 60_000);++ test("the bench verb renders the refusal contract and exits nonzero", async () => {+ // Deterministic refusal #1: the runs dir is a FILE, so the preflight's+ // usability probe refuses before anything is created.+ const fixturePath = join(runsDir, "fixture.json");+ writeFileSync(+ fixturePath,+ JSON.stringify({+ name: "refusal-render",+ notes: [{ path: "Brain/notes/a.md", body: "alpha note body" }],+ questions: [+ {+ id: "q1",+ category: "single_hop",+ query: "alpha",+ expected_paths: ["Brain/notes/a.md"],+ },+ ],+ }),+ );+ const blockedRunsDir = join(runsDir, "blocked-runs");+ writeFileSync(blockedRunsDir, "not a directory");+ const stderr: string[] = [];+ const stdout: string[] = [];+ const originalErr = process.stderr.write;+ const originalOut = process.stdout.write;+ process.stderr.write = ((chunk?: unknown) => {+ stderr.push(String(chunk));+ return true;+ }) as typeof process.stderr.write;+ process.stdout.write = ((chunk?: unknown) => {+ stdout.push(String(chunk));+ return true;+ }) as typeof process.stdout.write;+ try {+ const code = await cmdBrainBench([+ "memory",+ "--fixture",+ fixturePath,+ "--runs-dir",+ blockedRunsDir,+ ]);+ expect(code).not.toBe(0);+ // Scenario #1's render is asserted before the buffer is reused.+ expect(stderr.join("")).toContain("refused (runs_dir_unusable)");+ // Deterministic refusal #2: resuming a run whose checkpoint is corrupt.+ const brokenDir = join(runsDir, "broken-runs");+ const { createBenchRun: create } = await import("../../../src/core/bench/run-store.ts");+ const broken = create(+ brokenDir,+ parseBenchFixture(JSON.parse(readFileSync(fixturePath, "utf8"))),+ {+ now: new Date("2026-06-03T12:00:00Z"),+ },+ );+ writeFileSync(join(broken.runDir, "checkpoint.json"), "{not json");+ stderr.length = 0;+ const corruptCode = await cmdBrainBench([+ "memory",+ "--fixture",+ fixturePath,+ "--runs-dir",+ brokenDir,+ "--resume",+ broken.runId,+ ]);+ expect(corruptCode).not.toBe(0);+ } finally {+ process.stderr.write = originalErr;+ process.stdout.write = originalOut;+ }+ expect(stderr.join("")).toContain("refused (checkpoint_unparseable)");+ // Refusals are stderr-only: stdout stays byte-empty for both.+ expect(stdout.join("")).toBe("");+ }, 30_000);});describe("the embeddings capability path", () => {@@ -487,13 +751,20 @@ describe("the embeddings capability path", () => {test("a shared cache written under another schema is refused, never honored", async () => {const cachePath = join(runsDir, "embedding-cache.json");- const run = () =>- runMemoryBench({+ // Each attempt takes its own minute: run ids are second-precision, so+ // two fresh same-identity runs in one second are a collision refusal+ // now (P2) - the days of silently resetting an existing run dir.+ let attempt = 0;+ const run = () => {+ const now = new Date(Date.UTC(2026, 5, 1, 0, attempt++, 0));+ return runMemoryBench({fixture: SEMANTIC_FIXTURE,runsDir,capabilities: CAPABILITIES,pinnedKnobs: SEMANTIC_PIN,+ now,});+ };writeFileSync(cachePath,`${JSON.stringify({ schema: "some.other.vectors.v9", entries: {} }, null, 2)}\n`,diff --git a/tests/core/bench/run-store.test.ts b/tests/core/bench/run-store.test.tsindex 857061a0..2090200f 100644--- a/tests/core/bench/run-store.test.ts+++ b/tests/core/bench/run-store.test.ts@@ -6,17 +6,20 @@*/import { afterEach, beforeEach, describe, expect, test } from "bun:test";-import { existsSync, mkdtempSync, readFileSync, rmSync, writeFileSync } from "node:fs";+import { existsSync, mkdtempSync, readdirSync, readFileSync, rmSync, writeFileSync } from "node:fs";import { tmpdir } from "node:os";import { join } from "node:path";import { parseBenchFixture } from "../../../src/core/bench/fixture.ts";import {+ benchRunDirPath,benchRunIdentityHash,benchVaultDir,completeBenchPhase,createBenchRun,loadBenchRun,+ nextBenchRunId,+ readBenchCheckpoint,} from "../../../src/core/bench/run-store.ts";import { DEFAULT_BENCH_KNOB_PIN, type BenchPinnedKnobs } from "../../../src/core/bench/types.ts";@@ -88,6 +91,20 @@ describe("bench run store", () => {expect(() => loadBenchRun(runsDir, "../escape")).toThrow();});+ test("benchRunDirPath refuses traversal ids instead of resolving them", () => {+ // Finding 31: the preflight and the pipeline derive the run dir (and+ // the vault path for config resolution) through this helper BEFORE+ // loadBenchRun's guard runs, so the resolve must carry the same guard+ // the checkpoint reader applies - `--resume ..` used to stat and read+ // under the runs dir's parent before any refusal.+ expect(() => benchRunDirPath(runsDir, "..")).toThrow(/all dots/);+ expect(() => benchRunDirPath(runsDir, "../escape")).toThrow(/unsafe characters/);+ // A safe id resolves exactly as before.+ expect(benchRunDirPath(runsDir, "run-20260603120000-abc123")).toBe(+ join(runsDir, "run-20260603120000-abc123"),+ );+ });+test("two runs with different knob pins get different run ids", () => {const pinA: BenchPinnedKnobs = { semantic: { enabled: false } };const pinB: BenchPinnedKnobs = { semantic: { enabled: false }, keywordWeight: 0.6 };@@ -163,6 +180,63 @@ describe("bench run store", () => {});});+/**+ * Checkpoint strictness and atomic persistence (t_d7ce8baf): a checkpoint+ * naming a phase this build does not know is a named refusal (never a+ * silent filter), the checkpoint reader is exposed for the preflight, and+ * every persist lands through temp+rename so a crash leaves the previous+ * generation intact.+ */+describe("checkpoint strictness and atomic persistence", () => {+ test("a checkpoint naming an unknown phase is refused, naming the build mismatch", () => {+ const run = createBenchRun(runsDir, FIXTURE, { now: new Date("2026-06-03T12:00:00Z") });+ const path = join(run.runDir, "checkpoint.json");+ const tampered = JSON.parse(readFileSync(path, "utf8")) as Record<string, unknown>;+ tampered["completed_phases"] = ["ingest", "quantum_phase"];+ writeFileSync(path, `${JSON.stringify(tampered, null, 2)}\n`, "utf8");+ expect(() => loadBenchRun(runsDir, run.runId)).toThrow(/different build/);+ expect(() => loadBenchRun(runsDir, run.runId)).toThrow(/quantum_phase/);+ });++ test("readBenchCheckpoint round-trips and keeps the missing-run message", () => {+ const run = createBenchRun(runsDir, FIXTURE, { now: new Date("2026-06-03T12:00:00Z") });+ const checkpoint = readBenchCheckpoint(runsDir, run.runId);+ expect(checkpoint.run_id).toBe(run.runId);+ expect(checkpoint.completed_phases).toEqual([]);+ expect(() => readBenchCheckpoint(runsDir, "run-nope")).toThrow(/bench run not found: run-nope/);+ });++ test("readBenchCheckpoint refuses corrupt JSON naming the file", () => {+ const run = createBenchRun(runsDir, FIXTURE, { now: new Date("2026-06-03T12:00:00Z") });+ const path = join(run.runDir, "checkpoint.json");+ writeFileSync(path, "{not json", "utf8");+ expect(() => readBenchCheckpoint(runsDir, run.runId)).toThrow(+ new RegExp(`${path.replace(/[.*+?^${}()|[\]\\]/g, "\\$&")} is not valid JSON`),+ );+ });++ test("the next-run-id helper is the id createBenchRun persists", () => {+ const now = new Date("2026-06-03T12:00:00Z");+ const pin: BenchPinnedKnobs = { semantic: { enabled: false }, keywordWeight: 0.6 };+ const predicted = nextBenchRunId(FIXTURE, { now, pinnedKnobs: pin, recallFloor: 0.4 });+ const run = createBenchRun(runsDir, FIXTURE, { now, pinnedKnobs: pin, recallFloor: 0.4 });+ expect(predicted).toBe(run.runId);+ // Deterministic: the preflight can read the same identity the store writes.+ expect(nextBenchRunId(FIXTURE, { now, pinnedKnobs: pin, recallFloor: 0.4 })).toBe(predicted);+ });++ test("persist is atomic: no temp files survive a completed phase", () => {+ const run = createBenchRun(runsDir, FIXTURE, { now: new Date("2026-06-03T12:00:00Z") });+ completeBenchPhase(run.runDir, run.checkpoint, "ingest");+ const leftovers = readdirSync(run.runDir).filter((entry) => entry.includes(".tmp"));+ expect(leftovers).toEqual([]);+ // The store alone lays down the checkpoint; the vault is the ingest+ // phase's artifact (the pipeline materializes it before completing+ // the phase), so a bare create+complete leaves exactly one file.+ expect(readdirSync(run.runDir).toSorted()).toEqual(["checkpoint.json"]);+ });+});+/*** The sampling fold in the run identity (wiring-shipped-seams wave,* t_4501c662): the canonical record spreads `sample` in ONLY whendiff --git a/tests/core/brain/anticipatory-cache.test.ts b/tests/core/brain/anticipatory-cache.test.tsindex beb85669..db7cc92a 100644--- a/tests/core/brain/anticipatory-cache.test.ts+++ b/tests/core/brain/anticipatory-cache.test.ts@@ -366,3 +366,110 @@ describe("owner scope in the cache key", () => {}});});++/**+ * Window-derived default budget (t_a567cc12, B4): when the operator+ * declares a context window - the vault's `context:` block or the+ * environment override - the default budget becomes a window fraction,+ * floored at the historical 2_000, so it only ever scales UP. With+ * nothing resolvable the 2_000 default stands byte-identically, and a+ * budget the derivation decided is disclosed on the results that used it+ * (`derivedMaxTokens` / `derived_max_tokens`); an explicit `maxTokens`+ * input stays first-class and is never disclosed as derived.+ */+describe("window-derived default budget", () => {+ const ENV_KEY = "OPEN_SECOND_BRAIN_MODEL_CONTEXT_WINDOW";+ let savedEnv: string | undefined;++ function writeContextWindow(contents: string): void {+ writeFileSync(join(vault, "Brain", "_brain.yaml"), contents);+ }++ function restoreEnv(): void {+ if (savedEnv === undefined) delete process.env[ENV_KEY];+ else process.env[ENV_KEY] = savedEnv;+ savedEnv = undefined;+ }++ test("a declared window scales the default budget above the floor", () => {+ writeContextWindow("schema_version: 1\ncontext:\n window_tokens: 1000000\n");+ const result = refreshAnticipatoryCache(vault, { sessionId: "s-win", now: T0 });+ expect(result.refreshed).toBe(true);+ expect(result.derivedMaxTokens).toBe(10_000);+ const raw = JSON.parse(+ readFileSync(anticipatoryCachePath(vault, result.rootSessionId), "utf8"),+ ) as { max_tokens: number };+ expect(raw.max_tokens).toBe(10_000);+ });++ test("the floor keeps a small declared window at today's default", () => {+ writeContextWindow("schema_version: 1\ncontext:\n window_tokens: 100000\n");+ const result = refreshAnticipatoryCache(vault, { sessionId: "s-floor", now: T0 });+ // At the floor the derivation answered with the historical constant,+ // so there is nothing derived to disclose and nothing observable+ // changed.+ expect(result.derivedMaxTokens).toBeUndefined();+ const raw = JSON.parse(+ readFileSync(anticipatoryCachePath(vault, result.rootSessionId), "utf8"),+ ) as { max_tokens: number };+ expect(raw.max_tokens).toBe(2_000);+ });++ test("the environment override scales the budget", () => {+ savedEnv = process.env[ENV_KEY];+ process.env[ENV_KEY] = "500000";+ try {+ const result = refreshAnticipatoryCache(vault, { sessionId: "s-env", now: T0 });+ expect(result.derivedMaxTokens).toBe(5_000);+ } finally {+ restoreEnv();+ }+ });++ test("an explicit maxTokens wins and is not disclosed as derived", () => {+ writeContextWindow("schema_version: 1\ncontext:\n window_tokens: 1000000\n");+ const result = refreshAnticipatoryCache(vault, {+ sessionId: "s-explicit",+ now: T0,+ maxTokens: 500,+ });+ expect(result.derivedMaxTokens).toBeUndefined();+ const raw = JSON.parse(+ readFileSync(anticipatoryCachePath(vault, result.rootSessionId), "utf8"),+ ) as { max_tokens: number };+ expect(raw.max_tokens).toBe(500);+ });++ test("nothing resolvable keeps the 2_000 default byte-identically", () => {+ const result = refreshAnticipatoryCache(vault, { sessionId: "s-default", now: T0 });+ expect(result.derivedMaxTokens).toBeUndefined();+ const raw = JSON.parse(+ readFileSync(anticipatoryCachePath(vault, result.rootSessionId), "utf8"),+ ) as { max_tokens: number };+ expect(raw.max_tokens).toBe(2_000);+ });++ test("a broken _brain.yaml fails the derivation soft, and the refresh as always", () => {+ writeContextWindow("schema_version: 1\ncontext:\n window_tokens: not-a-number\n");+ const result = refreshAnticipatoryCache(vault, { sessionId: "s-broken", now: T0 });+ // The derivation channel never answers for an unreadable config - no+ // budget is disclosed - and the pack build raises on it exactly as it+ // always has, so the fail-soft refresh reports a miss and writes+ // nothing rather than caching a bundle under defaults the operator+ // did not choose.+ expect(result.refreshed).toBe(false);+ expect(result.derivedMaxTokens).toBeUndefined();+ });++ test("the read path discloses the derived budget it answered under", () => {+ writeContextWindow("schema_version: 1\ncontext:\n window_tokens: 1000000\n");+ refreshAnticipatoryCache(vault, { sessionId: "s-read", now: T0 });+ const read = readAnticipatoryContext(vault, {+ sessionId: "s-read",+ now: new Date(T0.getTime() + 10_000),+ ttlSeconds: 120,+ });+ expect(read.cache_state).toBe("warm");+ expect(read.derived_max_tokens).toBe(10_000);+ });+});diff --git a/tests/core/brain/bridge-discovery.test.ts b/tests/core/brain/bridge-discovery.test.tsindex d60fd6a8..f0c56987 100644--- a/tests/core/brain/bridge-discovery.test.ts+++ b/tests/core/brain/bridge-discovery.test.ts@@ -200,6 +200,67 @@ describe("acceptBridge", () => {expect(acceptBridge(vault, "src.md", "a-dir/topic.md").changed).toBe(false);});+ /** One in-scope target, one twin under `dir`, and the link they earn. */+ function seedTwinUnder(dir: string): void {+ mkdirSync(join(vault, "a-dir"), { recursive: true });+ mkdirSync(join(vault, dir), { recursive: true });+ writeFileSync(join(vault, "a-dir", "topic.md"), "# Topic A\n\nBody.\n");+ writeFileSync(join(vault, dir, "topic.md"), "# Topic Twin\n\nBody.\n");+ writeFileSync(join(vault, "src.md"), "# Src\n\nBody.\n");+ }++ test.each(["node_modules", join("Brain", ".snapshots"), ".open-second-brain"])(+ "a twin under the default-ignored %s does not make the target ambiguous",+ (dir) => {+ seedTwinUnder(dir);+ const result = acceptBridge(vault, "src.md", "a-dir/topic.md");+ expect(result.changed).toBe(true);+ const [fm] = parseFrontmatter(join(vault, "src.md"));+ expect(fm["related"]).toEqual("[[topic]]");+ },+ );++ test("a twin under an operator-ignored directory does not make the target ambiguous", () => {+ seedTwinUnder("Archive");+ mkdirSync(join(vault, "Brain"), { recursive: true });+ writeFileSync(+ join(vault, "Brain", "_brain.yaml"),+ "schema_version: 1\nvault:\n ignore_paths:\n - Archive\n",+ );+ const result = acceptBridge(vault, "src.md", "a-dir/topic.md");+ expect(result.changed).toBe(true);+ const [fm] = parseFrontmatter(join(vault, "src.md"));+ expect(fm["related"]).toEqual("[[topic]]");+ });++ test("an out-of-scope target is counted itself, so an in-scope twin cannot take the bare basename", () => {+ seedTwinUnder("Archive");+ mkdirSync(join(vault, "Brain"), { recursive: true });+ writeFileSync(+ join(vault, "Brain", "_brain.yaml"),+ "schema_version: 1\nvault:\n ignore_paths:\n - Archive\n",+ );+ const result = acceptBridge(vault, "src.md", "Archive/topic.md");+ expect(result.changed).toBe(true);+ const [fm] = parseFrontmatter(join(vault, "src.md"));+ expect(fm["related"]).toEqual("[[Archive/topic]]");+ // Re-accept of the same pair stays idempotent on the full form.+ expect(acceptBridge(vault, "src.md", "Archive/topic.md").changed).toBe(false);+ });++ test("a twin outside the include_paths allowlist does not make the target ambiguous", () => {+ seedTwinUnder("b-dir");+ mkdirSync(join(vault, "Brain"), { recursive: true });+ writeFileSync(+ join(vault, "Brain", "_brain.yaml"),+ "schema_version: 1\nvault:\n include_paths:\n - a-dir\n",+ );+ const result = acceptBridge(vault, "src.md", "a-dir/topic.md");+ expect(result.changed).toBe(true);+ const [fm] = parseFrontmatter(join(vault, "src.md"));+ expect(fm["related"]).toEqual("[[topic]]");+ });+test("refuses paths outside the vault and missing notes", () => {expect(() => acceptBridge(vault, "../escape.md", "x.md")).toThrow(/outside the vault/);expect(() => acceptBridge(vault, "ghost.md", "also-ghost.md")).toThrow(/does not exist/);diff --git a/tests/core/brain/config-template-ratchet.test.ts b/tests/core/brain/config-template-ratchet.test.tsindex 3f709af0..d9b45dd8 100644--- a/tests/core/brain/config-template-ratchet.test.ts+++ b/tests/core/brain/config-template-ratchet.test.ts@@ -41,6 +41,7 @@ import {resolveSessions,resolveTemporal,validateBrainConfigDetailed,+ CONTEXT_WINDOW_TOKENS_DEFAULT,INJECT_BUDGET_CHARS_DEFAULT,LESSONS_CORROBORATION_MIN_DEFAULT,LESSONS_HALF_LIFE_DAYS_DEFAULT,@@ -185,6 +186,17 @@ function resolvedView(cfg: BrainConfig): Record<string, unknown> {ttl_seconds: cfg.anticipatory?.ttl_seconds ?? DEFAULT_ANTICIPATORY_TTL_SECONDS,max_tokens: cfg.anticipatory?.max_tokens ?? DEFAULT_ANTICIPATORY_MAX_TOKENS,},+ // The declared window falls back to the same default the absent key+ // resolves to downstream, so writing the commented default is a no-op+ // until the operator edits the number.+ context_window_tokens: cfg.context?.window_tokens ?? CONTEXT_WINDOW_TOKENS_DEFAULT,+ // The cross-topic block is opt-in: the enabled switch's documented+ // default (`false`) is exactly what an absent block means. The two+ // illustration keys are `commented-example`, so both sides stay+ // absent - writing them WOULD change behaviour.+ cross_topic_enabled: cfg.cross_topic?.enabled ?? false,+ cross_topic_min_topics: cfg.cross_topic?.min_topics,+ cross_topic_jaccard: cfg.cross_topic?.jaccard,recall_degradation: cfg.recall?.degradation ?? "hard-cut",hygiene_resolver_cmd: cfg.hygiene?.resolver_cmd,feedback_default_scope: cfg.feedback?.default_scope,@@ -265,6 +277,22 @@ describe("config template ratchet — generated text", () => {}}});++ test("the context block documents the shipped config-over-env precedence", () => {+ // Review finding: the doc used to promise the env var wins over+ // `window_tokens`, the opposite of the shipped resolver+ // (operator config > operator env > table > suffix > default). The+ // LIVE-surface byte-equality above deliberately ignores commentary,+ // so pin this promise in the text itself: an operator reading the+ // generated `_brain.yaml` must read what the resolver does.+ expect(DEFAULT_BRAIN_CONFIG_YAML).not.toContain(+ "OPEN_SECOND_BRAIN_MODEL_CONTEXT_WINDOW wins over this key",+ );+ expect(DEFAULT_BRAIN_CONFIG_YAML).toContain("This key wins over the");+ expect(DEFAULT_BRAIN_CONFIG_YAML).toContain(+ "OPEN_SECOND_BRAIN_MODEL_CONTEXT_WINDOW environment variable",+ );+ });});describe("config template ratchet — resolved-behaviour identity", () => {diff --git a/tests/core/brain/context-presets.test.ts b/tests/core/brain/context-presets.test.tsindex 6dd588d8..e2bfea08 100644--- a/tests/core/brain/context-presets.test.ts+++ b/tests/core/brain/context-presets.test.ts@@ -4,8 +4,12 @@ import {diffContextPreset,getContextPreset,listContextPresets,+ presetForResolvedWindow,+ presetForWindowTokens,suggestContextPreset,+ unrecognisedModelBudgetRefusal,} from "../../../src/core/brain/context-presets.ts";+import { resolveModelContextWindowTokens } from "../../../src/core/brain/model-window.ts";describe("context budget presets", () => {test("exposes named tight and long context presets", () => {@@ -39,6 +43,238 @@ describe("context budget presets", () => {});});+ test("a model-only call resolves the window and the reason discloses the source", () => {+ // Declared table (no hint word in "gpt-4o").+ expect(suggestContextPreset({ model: "gpt-4o" })).toEqual({+ preset_id: "long-context",+ confidence: "high",+ reason: "context window 128000 tokens resolved from declared matched long-context",+ preset: getContextPreset("long-context")!,+ resolvedWindow: { windowTokens: 128_000, source: "declared", clamped: false },+ });+ // Structural 1m suffix, hint-free id.+ expect(suggestContextPreset({ model: "qwen3-235b-1m" }).reason).toBe(+ "context window 1000000 tokens resolved from suffix matched long-context",+ );+ // Unknown model, no hint: nothing published places the id, so the+ // conservative fallback answers - the same tight-context/low answer a+ // model-free call gets - and no window resolution is claimed for the+ // id. The default window is an assumption, never a suggestion basis.+ expect(suggestContextPreset({ model: "kimi-k2" })).toEqual({+ preset_id: "tight-context",+ confidence: "low",+ reason: "no model or context-window hint matched; using conservative default",+ preset: getContextPreset("tight-context")!,+ });+ });++ test("a resolved window beats a model hint; a hint-only model keeps the hint", () => {+ // "gemini-2.5-pro-1m" carries a hint word ("pro" is a whole token of+ // the id), but the id also carries a published `-1m` suffix. The+ // resolver decides, because the derivation surfaces size every budget+ // from this same resolved window - the suggestion must name the+ // mapping the pack uses.+ const suggestion = suggestContextPreset({ model: "gemini-2.5-pro-1m" });+ expect(suggestion).toEqual({+ preset_id: "long-context",+ confidence: "high",+ reason: "context window 1000000 tokens resolved from suffix matched long-context",+ preset: getContextPreset("long-context")!,+ resolvedWindow: { windowTokens: 1_000_000, source: "suffix", clamped: false },+ });+ // A hint-only model - the resolver has nothing published for it - keeps+ // today's byte-identical hint answer, and no window resolution is+ // claimed for the same call.+ const hintOnly = suggestContextPreset({ model: "gemini-2.5-flash" });+ expect(hintOnly).toMatchObject({+ preset_id: "tight-context",+ confidence: "high",+ reason: "model hint matched tight-context",+ });+ expect(hintOnly.resolvedWindow).toBeUndefined();+ });++ test("a table-declared window beats a hint, so suggest agrees with the pack budget", () => {+ // The disagreeing-model case the review names: `gpt-4.1-mini` matches+ // the "mini" hint AND the declared table. The pack derives from the+ // resolved 1M window and budgets long-context; the suggestion used to+ // answer tight-context from the hint - two mappings for one model.+ const suggestion = suggestContextPreset({ model: "gpt-4.1-mini" });+ expect(suggestion).toEqual({+ preset_id: "long-context",+ confidence: "high",+ reason: "context window 1000000 tokens resolved from declared matched long-context",+ preset: getContextPreset("long-context")!,+ resolvedWindow: { windowTokens: 1_000_000, source: "declared", clamped: false },+ });+ // The mapping the pack sizes from names the same preset.+ expect(presetForWindowTokens(suggestion.resolvedWindow!.windowTokens).id).toBe("long-context");+ });++ test("a hint-only model budgets the same preset suggest answers", () => {+ // The remaining disagreement the review names: for an id the declared+ // table does not know, the resolver answers the default window, the+ // pack budgeted long-context (24k) from it, while suggest answered the+ // hint (tight-context, 4k) - two mappings for one model. The budget+ // derivation now applies the same `model_hints` fallback suggest uses+ // whenever the resolver's source is "default"; the disclosed source+ // stays the window's.+ for (const id of ["gemini-2.5-flash", "claude-3-haiku"]) {+ const suggestion = suggestContextPreset({ model: id });+ expect(suggestion).toMatchObject({+ preset_id: "tight-context",+ confidence: "high",+ reason: "model hint matched tight-context",+ });+ const resolved = resolveModelContextWindowTokens({ model: id });+ expect(resolved.source).toBe("default");+ const budgetPreset = presetForResolvedWindow(id, resolved);+ expect(budgetPreset.id).toBe(suggestion.preset_id);+ expect(budgetPreset.context_pack.max_tokens).toBe(suggestion.preset.context_pack.max_tokens);+ }+ // A table-known id keeps the table's mapping and never its hint, on+ // both surfaces: "gpt-4.1-mini" matches "mini" but resolves declared 1M.+ const declared = resolveModelContextWindowTokens({ model: "gpt-4.1-mini" });+ expect(declared.source).toBe("declared");+ expect(presetForResolvedWindow("gpt-4.1-mini", declared).id).toBe("long-context");+ expect(suggestContextPreset({ model: "gpt-4.1-mini" }).preset_id).toBe("long-context");+ // No model, no hint to fall back on: the resolved window decides.+ expect(+ presetForResolvedWindow(undefined, {+ windowTokens: 200_000,+ source: "default",+ clamped: false,+ }).id,+ ).toBe("long-context");+ });++ test("a hint matches a whole token of the id, never a fragment of one", () => {+ // "mini" is a substring of "gemini" and the declared table has no+ // gemini rows, so the raw-substring matcher fell every gemini-* id+ // through to the hint path and matched tight-context first:+ // gemini-2.5-pro - a 1M-class model whose id also carries "pro" -+ // was budgeted 4k. A hint now has to EQUAL one delimiter-split token+ // of the lowercased id: the spurious "mini" hit is gone, and the+ // genuine "pro" token decides - long-context, 24k.+ const suggestion = suggestContextPreset({ model: "gemini-2.5-pro" });+ expect(suggestion).toMatchObject({+ preset_id: "long-context",+ confidence: "high",+ reason: "model hint matched long-context",+ });+ expect(suggestion.resolvedWindow).toBeUndefined();+ const resolved = resolveModelContextWindowTokens({ model: "gemini-2.5-pro" });+ expect(resolved.source).toBe("default");+ const budget = presetForResolvedWindow("gemini-2.5-pro", resolved);+ expect(budget.id).toBe("long-context");+ expect(budget.context_pack.max_tokens).toBe(24_000);++ // The positive half of the contract: an exact token still matches.+ // gpt-4.1-mini is table-known, so its production budget answers from+ // the declared 1M window, but on the hint fallback itself (a+ // default-sourced answer) the whole token "mini" decides tight.+ expect(+ presetForResolvedWindow("gpt-4.1-mini", {+ windowTokens: 200_000,+ source: "default",+ clamped: false,+ }).id,+ ).toBe("tight-context");++ // A fragment inside a larger token is not a hit: "ministral" is one+ // token, so nothing places the id and the conservative fallback+ // answers - never the default window's long-context mapping, which+ // would budget a small local model three times its real window.+ expect(suggestContextPreset({ model: "ministral-8b" })).toMatchObject({+ preset_id: "tight-context",+ confidence: "low",+ reason: "no model or context-window hint matched; using conservative default",+ });+ });++ test("an unrecognised id refuses the derived budget; table and hint ids do not", () => {+ // M1: an id with no table row, no suffix and no hint used to budget+ // the default window's long-context 24k - about three times an 8k+ // local model's whole window. The pack surfaces refuse instead, and+ // this shared predicate is the exact condition they refuse on (and+ // the condition suggest's conservative fallback answers on).+ const unknown = resolveModelContextWindowTokens({ model: "llama3:8b" });+ expect(unknown.source).toBe("default");+ expect(unrecognisedModelBudgetRefusal("llama3:8b", unknown)).toBe(+ "model 'llama3:8b' not recognised; pass max_tokens or set context.window_tokens",+ );+ // A table-declared id budgets long-context from its row, never refuses.+ expect(+ unrecognisedModelBudgetRefusal(+ "gpt-4.1-mini",+ resolveModelContextWindowTokens({ model: "gpt-4.1-mini" }),+ ),+ ).toBeNull();+ // A hint-matching id budgets from its hint, never refuses.+ expect(+ unrecognisedModelBudgetRefusal(+ "gemini-2.5-flash",+ resolveModelContextWindowTokens({ model: "gemini-2.5-flash" }),+ ),+ ).toBeNull();+ // A blank model is ABSENT, not a name to match: with the default+ // window the only answer left, the refusal carries no id.+ expect(+ unrecognisedModelBudgetRefusal(" ", {+ windowTokens: 200_000,+ source: "default",+ clamped: false,+ }),+ ).toBe("model not recognised; pass max_tokens or set context.window_tokens");+ });++ test("an explicit window keeps today's exact answer with nothing resolved", () => {+ const suggestion = suggestContextPreset({ model: "kimi-k2", contextWindowTokens: 8000 });+ expect(suggestion).toMatchObject({+ preset_id: "tight-context",+ confidence: "high",+ reason: "context window 8000 tokens matched tight-context",+ });+ expect(suggestion.resolvedWindow).toBeUndefined();+ });++ test("an explicit window beats a model hint when both are given", () => {+ // The shipped order, pinned in both directions of the disagreement:+ // the `model_hints` check used to run first, so `gpt-4o-mini` with an+ // explicit 128000 window answered tight-context from the "mini" hint+ // while the window named long-context. The window is authoritative -+ // it is the caller's own number for the deployment at hand, the same+ // figure a derived budget sizes from - and a hint answers only when+ // the resolver has nothing to say, so the window's mapping wins.+ const hintTight = suggestContextPreset({+ model: "gpt-4o-mini",+ contextWindowTokens: 128_000,+ });+ expect(hintTight).toEqual({+ preset_id: "long-context",+ confidence: "high",+ reason: "context window 128000 tokens matched long-context",+ preset: getContextPreset("long-context")!,+ });+ // The number was given, not resolved: nothing is claimed.+ expect(hintTight.resolvedWindow).toBeUndefined();+ expect(+ suggestContextPreset({ model: "claude-sonnet-4", contextWindowTokens: 8_000 }),+ ).toMatchObject({+ preset_id: "tight-context",+ confidence: "high",+ reason: "context window 8000 tokens matched tight-context",+ });+ });++ test("no model and no window keeps the conservative fallback", () => {+ expect(suggestContextPreset({})).toMatchObject({+ preset_id: "tight-context",+ confidence: "low",+ reason: "no model or context-window hint matched; using conservative default",+ });+ });+test("diffs preset values while reporting explicit overrides", () => {const diff = diffContextPreset("tight-context", {context_pack: {diff --git a/tests/core/brain/dream-checkpoints.test.ts b/tests/core/brain/dream-checkpoints.test.tsindex 57e6d591..2d8baa93 100644--- a/tests/core/brain/dream-checkpoints.test.ts+++ b/tests/core/brain/dream-checkpoints.test.ts@@ -353,6 +353,7 @@ describe("the mutation stage does not absorb a safeguard stop", () => {quarantined: [],topicKeyContentions: [],signalsToArchive: new Map(),+ crossTopicRules: [],};}diff --git a/tests/core/brain/dream-cross-topic.test.ts b/tests/core/brain/dream-cross-topic.test.tsnew file mode 100644index 00000000..cebb4ce9--- /dev/null+++ b/tests/core/brain/dream-cross-topic.test.ts@@ -0,0 +1,1362 @@+/**+ * Cross-topic rule promotion (t_642bc2b8): the pure planner plus its+ * ledger helpers.+ *+ * Coverage map:+ * - `resolveCrossTopicConfig`: absent block = off; keys override the+ * named defaults.+ * - `planCrossTopicRules`: cross-bucket detection at the configured+ * `min_topics`/`jaccard`, same-bucket (and folded-same-key) clusters+ * never firing, content-slug determinism and dedup against live or+ * retired files, the duplicate-rule guard that keeps membership+ * churn from re-creating a live rule (M8: principle jaccard at the+ * same floor, or a superset of the rule's evidence, skips and+ * discloses without writing), the per-owner-token daily budget read+ * off the injected clock, owner-uniform source sets, and exclusion+ * of sources the same pass plans to retire.+ * - ledger read/write round trip through the shared atomic writer.+ *+ * Modeled on `tests/core/brain/rollup-ladder.test.ts`: the planner is a+ * pure function of its inputs, so most of the suite needs no vault.+ */++import { afterEach, beforeEach, describe, expect, test } from "bun:test";+import { existsSync, mkdtempSync, readdirSync, readFileSync, rmSync } from "node:fs";+import { tmpdir } from "node:os";+import { join } from "node:path";++import {+ CROSS_TOPIC_LEDGER_VERSION,+ DEFAULT_CROSS_TOPIC_JACCARD,+ DEFAULT_CROSS_TOPIC_MIN_TOPICS,+ MIN_CROSS_TOPIC_JACCARD,+ planCrossTopicRules,+ readCrossTopicLedger,+ resolveCrossTopicConfig,+ writeCrossTopicLedger,+ type CrossTopicLedger,+ type ResolvedCrossTopicConfig,+} from "../../../src/core/brain/dream-plan-cross-topic.ts";+import {+ emptyPlan,+ type PreferenceRecord,+ type RetiredRecord,+ type ScanResult,+} from "../../../src/core/brain/dream-plan.ts";+import type { RefreshResult } from "../../../src/core/brain/dream-refresh.ts";+import { appendApplyEvidence } from "../../../src/core/brain/apply-evidence.ts";+import { parseFrontmatter } from "../../../src/core/vault.ts";+import { pageVisibility } from "../../../src/core/graph/visibility.ts";+import { dream } from "../../../src/core/brain/dream.ts";+import { bootstrapBrain } from "../../../src/core/brain/init.ts";+import { tombstone } from "../../../src/core/brain/lifecycle/tombstone.ts";+import { buildReviewCandidates } from "../../../src/core/brain/review-candidates.ts";+import { stageDream, validateDreamBundle } from "../../../src/core/brain/dream-stage.ts";+import { brainConfigPath, crossTopicLedgerPath } from "../../../src/core/brain/paths.ts";+import { parsePreference, writePreference } from "../../../src/core/brain/preference.ts";+import { isoSecond } from "../../../src/core/brain/time.ts";+import { atomicWriteFileSync } from "../../../src/core/fs-atomic.ts";+import { DEFAULT_BRAIN_CONFIG } from "../../../src/core/brain/policy.ts";+import {+ BRAIN_PREFERENCE_STATUS,+ BRAIN_RETIRED_REASON,+ type BrainPreference,+ type BrainPreferenceStatus,+ type BrainConfig,+} from "../../../src/core/brain/types.ts";+import { sha256Hex } from "../../../src/core/integrity/digest.ts";++const NOW = new Date("2026-07-19T10:00:00Z");+const TODAY = "2026-07-19";+/** Two principles sharing 5 of 7 tokens: jaccard 5/7 > the 0.6 default. */+const P_ALPHA = "prefer bun over node for scripts";+const P_BETA = "prefer bun over node for tooling";+const P_FAR = "always write the failing test first";+/** A third family: mutually near, far from both P_ALPHA and P_FAR. */+const P_BASE_A = "docker builds must pin the base image digest";+const P_BASE_B = "docker builds should pin the base image digest";++const CONFIG: ResolvedCrossTopicConfig = { minTopics: 2, jaccard: 0.6 };++function pref(overrides: Partial<BrainPreference> = {}): BrainPreference {+ return {+ kind: "brain-preference",+ id: "pref-x",+ created_at: "2026-01-01T00:00:00Z",+ confirmed_at: "2026-01-02T00:00:00Z",+ unconfirmed_until: "2026-01-08T00:00:00Z",+ tags: [],+ topic: "t",+ status: BRAIN_PREFERENCE_STATUS.confirmed,+ principle: "p",+ evidenced_by: [],+ applied_count: 0,+ violated_count: 0,+ last_evidence_at: null,+ confidence: "low",+ confidence_value: 0,+ pinned: false,+ ...overrides,+ };+}++function rec(+ id: string,+ topic: string,+ principle: string,+ owner?: string,+ status?: BrainPreferenceStatus,+): PreferenceRecord {+ return {+ path: `/vault/Brain/preferences/${id}.md`,+ pref: pref({+ id,+ topic,+ principle,+ ...(owner ? { owner } : {}),+ ...(status ? { status } : {}),+ }),+ supersededBy: null,+ };+}++function retiredRec(id: string, topic: string, principle: string): RetiredRecord {+ return { path: `/vault/Brain/retired/${id}.md`, id, topic, principle };+}++/** A record re-scanned with `visibility:` tokens on its page. */+function withVisibility(record: PreferenceRecord, tokens: string[]): PreferenceRecord {+ return { ...record, visibility: Object.freeze(tokens) };+}++/**+ * The on-disk shape of a promoted rule after dream-refresh confirmed it+ * (one applied event auto-confirms it): an ordinary preference carrying+ * the `cross-` slug, `inferred` provenance and its evidence lineage.+ * `evidencedBy` overrides the self-citing default; `owner` stamps the+ * rule's owner token.+ */+function promotedRec(+ id: string,+ topic: string,+ principle: string,+ evidencedBy?: string[],+ owner?: string,+): PreferenceRecord {+ return {+ path: `/vault/Brain/preferences/${id}.md`,+ pref: pref({+ id,+ topic,+ principle,+ provenance: "inferred",+ evidenced_by: evidencedBy ?? [`[[${id}]]`],+ ...(owner ? { owner } : {}),+ }),+ supersededBy: null,+ };+}++const NO_REFRESH: RefreshResult = {+ confirmed: new Set(),+ updated: new Map(),+ bandDrops: [],+ outcomeRegressions: [],+};++function scanOf(preferences: PreferenceRecord[], retired: RetiredRecord[] = []): ScanResult {+ return { signals: [], preferences, retired, corrupted: [] };+}++/**+ * Run the planner over a scan, returning the result AND the mutated plan.+ * `tombstonedPaths` / `corruptedPaths` are preferences-dir files the scan+ * saw but did not parse into records: a tombstone keeps the file in place+ * and an unparseable one lands in `scan.corrupted`.+ */+function plan(+ preferences: PreferenceRecord[],+ opts: {+ config?: ResolvedCrossTopicConfig | null;+ ledger?: CrossTopicLedger | null;+ now?: Date;+ refresh?: RefreshResult;+ retired?: RetiredRecord[];+ retireSlugs?: string[];+ tombstonedPaths?: string[];+ corruptedPaths?: string[];+ } = {},+) {+ const planState = emptyPlan();+ for (const slug of opts.retireSlugs ?? []) {+ planState.retires.push({ slug, principle: "x", reason: BRAIN_RETIRED_REASON.staleNoEvidence });+ }+ const scan: ScanResult = {+ ...scanOf(preferences, opts.retired ?? []),+ ...(opts.tombstonedPaths+ ? { tombstonedPreferences: opts.tombstonedPaths.map((path) => ({ path })) }+ : {}),+ ...(opts.corruptedPaths ? { corrupted: opts.corruptedPaths.map((path) => ({ path })) } : {}),+ };+ const result = planCrossTopicRules({+ scan,+ refresh: opts.refresh ?? NO_REFRESH,+ config: opts.config === undefined ? CONFIG : opts.config,+ ledger: opts.ledger ?? null,+ now: opts.now ?? NOW,+ plan: planState,+ });+ return { result, plan: planState };+}++/** The content slug the planner must derive for a sorted source-id set. */+function expectedSlug(...ids: string[]): string {+ return `cross-${sha256Hex(ids.sort().join("\n")).slice(0, 12)}`;+}++describe("resolveCrossTopicConfig", () => {+ test("an absent block resolves to null (feature off)", () => {+ expect(resolveCrossTopicConfig(DEFAULT_BRAIN_CONFIG)).toBeNull();+ });++ test("enabled: false resolves to null", () => {+ const cfg: BrainConfig = {+ ...DEFAULT_BRAIN_CONFIG,+ cross_topic: { enabled: false },+ };+ expect(resolveCrossTopicConfig(cfg)).toBeNull();+ });++ test("enabled with no keys resolves the named defaults", () => {+ const cfg: BrainConfig = { ...DEFAULT_BRAIN_CONFIG, cross_topic: { enabled: true } };+ expect(resolveCrossTopicConfig(cfg)).toEqual({+ minTopics: DEFAULT_CROSS_TOPIC_MIN_TOPICS,+ jaccard: DEFAULT_CROSS_TOPIC_JACCARD,+ });+ });++ test("declared keys override the defaults", () => {+ const cfg: BrainConfig = {+ ...DEFAULT_BRAIN_CONFIG,+ cross_topic: { enabled: true, min_topics: 3, jaccard: 0.8 },+ };+ expect(resolveCrossTopicConfig(cfg)).toEqual({ minTopics: 3, jaccard: 0.8 });+ });++ // ----- Config floors (review findings 62 and 82) -------------------------+ // The parser contract promises out-of-range but well-formed values are+ // "clamped (and the clamp disclosed) by the consumer that resolves it".+ // `min_topics: 1` elects singletons and `jaccard: 0` unions every+ // same-owner cross-bucket pair into one arbitrary cluster, so the+ // resolver owns the floors and names every clamp.++ test("min_topics below two is floored to two with a disclosure", () => {+ const cfg: BrainConfig = {+ ...DEFAULT_BRAIN_CONFIG,+ cross_topic: { enabled: true, min_topics: 1 },+ };+ const disclosures: string[] = [];+ const resolved = resolveCrossTopicConfig(cfg, (code, message) =>+ disclosures.push(`${code}: ${message}`),+ );+ expect(resolved).toEqual({+ minTopics: DEFAULT_CROSS_TOPIC_MIN_TOPICS,+ jaccard: DEFAULT_CROSS_TOPIC_JACCARD,+ });+ expect(disclosures).toHaveLength(1);+ expect(disclosures[0]).toContain("cross_topic.min_topics");+ expect(disclosures[0]).toContain("2");+ });++ test("jaccard below the merge-suggestion floor is floored with a disclosure", () => {+ const cfg: BrainConfig = {+ ...DEFAULT_BRAIN_CONFIG,+ cross_topic: { enabled: true, jaccard: 0 },+ };+ const disclosures: string[] = [];+ const resolved = resolveCrossTopicConfig(cfg, (code, message) =>+ disclosures.push(`${code}: ${message}`),+ );+ expect(resolved).toEqual({+ minTopics: DEFAULT_CROSS_TOPIC_MIN_TOPICS,+ jaccard: MIN_CROSS_TOPIC_JACCARD,+ });+ expect(disclosures).toHaveLength(1);+ expect(disclosures[0]).toContain("cross_topic.jaccard");+ });++ test("in-range knobs pass through untouched with no disclosure", () => {+ const cfg: BrainConfig = {+ ...DEFAULT_BRAIN_CONFIG,+ cross_topic: { enabled: true, min_topics: 3, jaccard: 0.8 },+ };+ const disclosures: string[] = [];+ expect(+ resolveCrossTopicConfig(cfg, (code, message) => disclosures.push(`${code}: ${message}`)),+ ).toEqual({ minTopics: 3, jaccard: 0.8 });+ expect(disclosures).toEqual([]);+ });++ test("the floors apply only when the feature is on", () => {+ const disclosures: string[] = [];+ // Off: null, and the sink never fires.+ expect(+ resolveCrossTopicConfig(DEFAULT_BRAIN_CONFIG, (code, message) =>+ disclosures.push(`${code}: ${message}`),+ ),+ ).toBeNull();+ expect(disclosures).toEqual([]);+ });+});++describe("planCrossTopicRules", () => {+ test("fires across two buckets at the configured thresholds and pins the entry shape", () => {+ const { result, plan: planState } = plan([+ rec("pref-alpha", "Alpha", P_ALPHA),+ rec("pref-beta", "Beta", P_BETA),+ ]);+ expect(result.fired).toBe(true);+ expect(planState.crossTopicRules).toHaveLength(1);+ const entry = planState.crossTopicRules[0]!;+ expect(entry.slug).toBe(expectedSlug("pref-alpha", "pref-beta"));+ // Representative principle: the lexicographically smallest source, verbatim.+ expect(entry.principle).toBe(P_ALPHA);+ // Deterministic synthetic topic: sorted raw displays joined.+ expect(entry.topic).toBe("Alpha + Beta");+ expect([...entry.evidencedBy]).toEqual(["[[pref-alpha]]", "[[pref-beta]]"]);+ expect([...entry.related]).toEqual(["pref-alpha", "pref-beta"]);+ expect(entry.owner).toBeUndefined();+ // Default-visibility sources promote a default-visibility rule.+ expect(entry.visibility).toEqual([]);+ // The returned ledger stamps the shared (ownerless) token with today.+ expect(result.ledger?.version).toBe(CROSS_TOPIC_LEDGER_VERSION);+ expect(result.ledger?.last_promoted[""]).toBe(TODAY);+ });++ test("same-bucket clusters never fire", () => {+ const { result, plan: planState } = plan([+ rec("pref-a", "docker", P_ALPHA),+ rec("pref-b", "docker", P_BETA),+ rec("pref-c", "docker", P_ALPHA),+ ]);+ expect(result.fired).toBe(false);+ expect(planState.crossTopicRules).toHaveLength(0);+ });++ test("topics that fold onto one key are one bucket, not two", () => {+ const { result, plan: planState } = plan([+ rec("pref-a", "Docker", P_ALPHA),+ rec("pref-b", "docker", P_BETA),+ ]);+ expect(result.fired).toBe(false);+ expect(planState.crossTopicRules).toHaveLength(0);+ });++ test("a pair below the jaccard threshold never fires", () => {+ const { result, plan: planState } = plan([+ rec("pref-a", "Alpha", P_ALPHA),+ rec("pref-b", "Beta", P_FAR),+ ]);+ expect(result.fired).toBe(false);+ expect(planState.crossTopicRules).toHaveLength(0);+ });++ test("a cluster spanning fewer buckets than min_topics never fires", () => {+ const { result, plan: planState } = plan(+ [rec("pref-a", "Alpha", P_ALPHA), rec("pref-b", "Beta", P_BETA)],+ { config: { minTopics: 3, jaccard: 0.6 } },+ );+ expect(result.fired).toBe(false);+ expect(planState.crossTopicRules).toHaveLength(0);+ });++ test("a null config (feature off) plans nothing", () => {+ const { result, plan: planState } = plan(+ [rec("pref-a", "Alpha", P_ALPHA), rec("pref-b", "Beta", P_BETA)],+ { config: null },+ );+ expect(result.fired).toBe(false);+ expect(result.ledger).toBeNull();+ expect(planState.crossTopicRules).toHaveLength(0);+ });++ test("only confirmed preferences are sources; a pref confirmed this run qualifies", () => {+ const unconfirmed = rec(+ "pref-a",+ "Alpha",+ P_ALPHA,+ undefined,+ BRAIN_PREFERENCE_STATUS.unconfirmed,+ );+ const cold = plan([unconfirmed, rec("pref-b", "Beta", P_BETA)]);+ expect(cold.result.fired).toBe(false);++ const promoted = plan([unconfirmed, rec("pref-b", "Beta", P_BETA)], {+ refresh: { ...NO_REFRESH, confirmed: new Set(["a"]) },+ });+ expect(promoted.result.fired).toBe(true);+ });++ test("the slug is content-derived: the same source set maps to one file in any scan order", () => {+ const first = plan([rec("pref-alpha", "Alpha", P_ALPHA), rec("pref-beta", "Beta", P_BETA)]);+ const second = plan([rec("pref-beta", "Beta", P_BETA), rec("pref-alpha", "Alpha", P_ALPHA)]);+ expect(first.plan.crossTopicRules[0]!.slug).toBe(second.plan.crossTopicRules[0]!.slug);+ expect(first.plan.crossTopicRules[0]!.slug).toBe(expectedSlug("pref-alpha", "pref-beta"));+ });++ test("a slug already present live or in retired/ skips the cluster", () => {+ const sources = [rec("pref-a", "Alpha", P_ALPHA), rec("pref-b", "Beta", P_BETA)];+ const slug = expectedSlug("pref-a", "pref-b");++ const live = plan([...sources, rec(`pref-${slug}`, "already promoted", P_FAR)]);+ expect(live.result.fired).toBe(false);+ expect(live.plan.crossTopicRules).toHaveLength(0);++ const retired = plan(sources, { retired: [retiredRec(`ret-${slug}`, "gone", P_FAR)] });+ expect(retired.result.fired).toBe(false);+ expect(retired.plan.crossTopicRules).toHaveLength(0);+ });++ // ----- Visibility of the promoted rule (review finding 63) --------------+ // The rule restates its representative source's principle VERBATIM, so+ // it may never be more public than the most restricted member. The+ // topic plan's strictest-visibility rule, over the cluster members.++ test("a restricted source's rule carries that restriction (finding 63)", () => {+ const { plan: planState } = plan([+ withVisibility(rec("pref-a", "Alpha", P_ALPHA), ["private"]),+ rec("pref-b", "Beta", P_BETA),+ ]);+ expect(planState.crossTopicRules).toHaveLength(1);+ expect(planState.crossTopicRules[0]!.visibility).toEqual(["private"]);+ });++ test("a visibility intersection that misses falls closed on the reserved token", () => {+ const { plan: planState } = plan([+ withVisibility(rec("pref-a", "Alpha", P_ALPHA), ["team"]),+ withVisibility(rec("pref-b", "Beta", P_BETA), ["agent:x"]),+ ]);+ expect(planState.crossTopicRules).toHaveLength(1);+ expect(planState.crossTopicRules[0]!.visibility).toEqual(["private"]);+ });++ test("the strictest of several restricted sources wins", () => {+ const { plan: planState } = plan([+ withVisibility(rec("pref-a", "Alpha", P_ALPHA), ["team", "agent:x"]),+ withVisibility(rec("pref-b", "Beta", P_BETA), ["team"]),+ ]);+ expect(planState.crossTopicRules[0]!.visibility).toEqual(["team"]);+ });++ // ----- Tombstoned / corrupted slugs are still taken (review finding 64) --+ // Precision (review round 2): `scan.corrupted` holds unparseable files+ // from the signal directories and `retired/` too, but only a file under+ // `Brain/preferences/` can collide with apply's `overwrite: false`+ // write - the slug match must consider that directory alone.++ test("a tombstoned pref-cross file takes its slug (finding 64)", () => {+ const slug = expectedSlug("pref-a", "pref-b");+ const { result, plan: planState } = plan(+ [rec("pref-a", "Alpha", P_ALPHA), rec("pref-b", "Beta", P_BETA)],+ { tombstonedPaths: [`/vault/Brain/preferences/pref-${slug}.md`] },+ );+ expect(result.fired).toBe(false);+ expect(planState.crossTopicRules).toHaveLength(0);+ });++ test("a corrupted pref-cross file under preferences/ takes its slug too", () => {+ const slug = expectedSlug("pref-a", "pref-b");+ const { result, plan: planState } = plan(+ [rec("pref-a", "Alpha", P_ALPHA), rec("pref-b", "Beta", P_BETA)],+ { corruptedPaths: [`/vault/Brain/preferences/pref-${slug}.md`] },+ );+ expect(result.fired).toBe(false);+ expect(planState.crossTopicRules).toHaveLength(0);+ });++ test("a corrupted pref-cross file outside preferences/ never blocks (round 2)", () => {+ const slug = expectedSlug("pref-a", "pref-b");+ const { result, plan: planState } = plan(+ [rec("pref-a", "Alpha", P_ALPHA), rec("pref-b", "Beta", P_BETA)],+ {+ corruptedPaths: [+ `/vault/Brain/retired/pref-${slug}.md`,+ `/vault/Brain/inbox/pref-${slug}.md`,+ ],+ },+ );+ expect(result.fired).toBe(true);+ expect(planState.crossTopicRules).toHaveLength(1);+ });++ test("an unrelated tombstoned file takes nothing", () => {+ const { result, plan: planState } = plan(+ [rec("pref-a", "Alpha", P_ALPHA), rec("pref-b", "Beta", P_BETA)],+ { tombstonedPaths: ["/vault/Brain/preferences/pref-unrelated.md"] },+ );+ expect(result.fired).toBe(true);+ expect(planState.crossTopicRules).toHaveLength(1);+ });++ test("one promotion per owner token per calendar day, dated from the injected now", () => {+ const sources = [rec("pref-a", "Alpha", P_ALPHA), rec("pref-b", "Beta", P_BETA)];+ const spent: CrossTopicLedger = {+ version: CROSS_TOPIC_LEDGER_VERSION,+ last_promoted: { "": TODAY },+ };+ const budgeted = plan(sources, { ledger: spent });+ expect(budgeted.result.fired).toBe(false);+ expect(budgeted.plan.crossTopicRules).toHaveLength(0);++ // The same ledger the next day has budget again, and the date comes+ // from the injected clock, never the wall clock.+ const nextDay = plan(sources, {+ ledger: spent,+ now: new Date("2026-07-20T10:00:00Z"),+ });+ expect(nextDay.result.fired).toBe(true);+ expect(nextDay.result.ledger?.last_promoted[""]).toBe("2026-07-20");+ });++ test("mixed-owner source sets never fire (no owner leak through a merged rule)", () => {+ const { result, plan: planState } = plan([+ rec("pref-a", "Alpha", P_ALPHA, "kate"),+ rec("pref-b", "Beta", P_BETA, "sam"),+ ]);+ expect(result.fired).toBe(false);+ expect(planState.crossTopicRules).toHaveLength(0);+ });++ test("owned sources stamp the shared owner token and budget under it", () => {+ const { result, plan: planState } = plan([+ rec("pref-a", "Alpha", P_ALPHA, "kate"),+ rec("pref-b", "Beta", P_BETA, "kate"),+ ]);+ expect(result.fired).toBe(true);+ const entry = planState.crossTopicRules[0]!;+ expect(entry.owner).toBe("kate");+ expect(result.ledger?.last_promoted["kate"]).toBe(TODAY);+ expect(result.ledger?.last_promoted[""]).toBeUndefined();+ });++ test("a source the same pass plans to retire is not eligible", () => {+ const { result, plan: planState } = plan(+ [rec("pref-a", "Alpha", P_ALPHA), rec("pref-b", "Beta", P_BETA)],+ { retireSlugs: ["a"] },+ );+ expect(result.fired).toBe(false);+ expect(planState.crossTopicRules).toHaveLength(0);+ });++ test("two disjoint clusters with distinct owners both fire, each under its own budget", () => {+ const kateCluster = [+ rec("pref-a1", "Alpha", P_ALPHA, "kate"),+ rec("pref-a2", "Beta", P_BETA, "kate"),+ ];+ const samCluster = [+ rec("pref-b1", "Gamma", P_ALPHA, "sam"),+ rec("pref-b2", "Delta", P_BETA, "sam"),+ ];+ const { result, plan: planState } = plan([...kateCluster, ...samCluster]);+ expect(result.fired).toBe(true);+ expect(planState.crossTopicRules).toHaveLength(2);+ const owners = planState.crossTopicRules.map((e) => e.owner).sort();+ expect(owners).toEqual(["kate", "sam"]);+ expect(result.ledger?.last_promoted["kate"]).toBe(TODAY);+ expect(result.ledger?.last_promoted["sam"]).toBe(TODAY);+ });++ test("an owner budgeted out today still lets another owner fire", () => {+ const spent: CrossTopicLedger = {+ version: CROSS_TOPIC_LEDGER_VERSION,+ last_promoted: { kate: TODAY },+ };+ const { result, plan: planState } = plan(+ [+ rec("pref-a1", "Alpha", P_ALPHA, "kate"),+ rec("pref-a2", "Beta", P_BETA, "kate"),+ rec("pref-b1", "Gamma", P_ALPHA, "sam"),+ rec("pref-b2", "Delta", P_BETA, "sam"),+ ],+ { ledger: spent },+ );+ expect(result.fired).toBe(true);+ expect(planState.crossTopicRules).toHaveLength(1);+ expect(planState.crossTopicRules[0]!.owner).toBe("sam");+ expect(result.ledger?.last_promoted["kate"]).toBe(TODAY);+ expect(result.ledger?.last_promoted["sam"]).toBe(TODAY);+ });++ // ----- Self-cluster re-promotion (review finding 61) ---------------------+ // The promoted rule restates its representative source verbatim (jaccard+ // 1.0) and folds to its own topic key, so once refresh confirms it, the+ // rule itself qualifies as a source and every later pass "discovers" a+ // new cross-topic cluster containing it - one promotion per owner per+ // day, forever. A promoted rule is therefore never a source.++ test("a confirmed promoted rule never re-enters the source pool on a later day", () => {+ const slug = expectedSlug("pref-a", "pref-b");+ const day2 = new Date("2026-07-20T10:00:00Z");+ const spent: CrossTopicLedger = {+ version: CROSS_TOPIC_LEDGER_VERSION,+ last_promoted: { "": TODAY },+ };+ // Day 2: the rule was confirmed overnight; the two stated sources and+ // the promoted rule are all live.+ const { result, plan: planState } = plan(+ [+ rec("pref-a", "Alpha", P_ALPHA),+ rec("pref-b", "Beta", P_BETA),+ promotedRec(`pref-${slug}`, "Alpha + Beta", P_ALPHA),+ ],+ { ledger: spent, now: day2 },+ );+ expect(result.fired).toBe(false);+ expect(planState.crossTopicRules).toHaveLength(0);+ });++ test("an inferred preference renamed away from the cross- prefix is still excluded", () => {+ // The provenance identifier catches a promoted rule whose file a hand+ // renamed: it still restates its source verbatim and folds to its own+ // key, so it must not become a source either.+ const { result, plan: planState } = plan([+ rec("pref-a", "Alpha", P_ALPHA),+ promotedRec("pref-handrenamed", "Beta", P_ALPHA),+ ]);+ expect(result.fired).toBe(false);+ expect(planState.crossTopicRules).toHaveLength(0);+ });++ test("a stated preference carrying a cross-prefixed id is also excluded", () => {+ // The slug prefix is the reserved content shape; a hand-authored file+ // that kept it gets the same treatment.+ const { result, plan: planState } = plan([+ rec("pref-a", "Alpha", P_ALPHA),+ rec("pref-cross-handmade", "Beta", P_ALPHA),+ ]);+ expect(result.fired).toBe(false);+ expect(planState.crossTopicRules).toHaveLength(0);+ });++ // ----- Duplicate-rule guard (M8) -----------------------------------------+ // The slug hashes the EXACT source set, so membership churn - one+ // source joining or leaving a promoted cluster - mints a new slug and,+ // before the guard, a second live rule stating the identical principle+ // while the first stays live. Before promoting, the planner compares+ // the candidate against the owner's existing inferred `cross-` rules+ // (the very records it excludes from the source pool): a+ // near-identical principle at the same jaccard floor the clusters+ // elect at, or a source set that already superset-evidences the rule,+ // skips the promotion - disclosed on the planner's result the same way+ // the daily budget's skips are: nothing written, no budget spent.++ test("membership churn mints no second rule: the guard skips and discloses (M8)", () => {+ const day1Slug = expectedSlug("pref-a", "pref-b");+ const day1Ledger: CrossTopicLedger = {+ version: CROSS_TOPIC_LEDGER_VERSION,+ last_promoted: { "": "2026-07-19" },+ };+ // Day 3: Gamma joined the promoted cluster before the day-1 rule+ // ever confirmed (still unconfirmed - the guard does not wait for+ // confirmation). The joined set elects under a NEW content slug, so+ // the exact-set slug dedup cannot catch it; the principle guard must.+ const { result, plan: planState } = plan(+ [+ rec("pref-a", "Alpha", P_ALPHA),+ rec("pref-b", "Beta", P_BETA),+ rec("pref-c", "Gamma", P_ALPHA),+ promotedRec(`pref-${day1Slug}`, "Alpha + Beta", P_ALPHA),+ ],+ { now: new Date("2026-07-21T10:00:00Z"), ledger: day1Ledger },+ );+ expect(expectedSlug("pref-a", "pref-b", "pref-c")).not.toBe(day1Slug);+ expect(result.fired).toBe(false);+ expect(planState.crossTopicRules).toHaveLength(0);+ // Nothing written: the day-3 budget stays unspent, the ledger update+ // is null.+ expect(result.ledger).toBeNull();+ // The skip is disclosed with its reason and the rule it duplicates.+ expect(result.skips).toHaveLength(1);+ expect(result.skips[0]!.code).toBe("cross-topic-duplicate-rule");+ expect(result.skips[0]!.message).toContain(`pref-${day1Slug}`);+ });++ test("a cluster that only extends a live rule's evidence skips too (superset branch)", () => {+ // The old rule's principle has drifted below the floor from the+ // cluster's current representative (a source rewrite since the+ // promotion), but the cluster's sources already evidence the rule:+ // extending that evidence is a future concern, not a second rule.+ const { result, plan: planState } = plan([+ rec("pref-c", "Gamma", P_BASE_A),+ rec("pref-d", "Delta", P_BASE_B),+ promotedRec("pref-cross-manual", "Gamma + Delta", P_FAR, ["[[pref-c]]", "[[pref-d]]"]),+ ]);+ expect(result.fired).toBe(false);+ expect(planState.crossTopicRules).toHaveLength(0);+ expect(result.skips).toHaveLength(1);+ expect(result.skips[0]!.code).toBe("cross-topic-duplicate-rule");+ expect(result.skips[0]!.message).toContain("pref-cross-manual");+ });++ test("a genuinely different principle still promotes beside an existing rule", () => {+ const { result, plan: planState } = plan([+ rec("pref-c", "Gamma", P_BASE_A),+ rec("pref-d", "Delta", P_BASE_B),+ promotedRec("pref-cross-manual", "Alpha + Beta", P_ALPHA),+ ]);+ expect(result.fired).toBe(true);+ expect(planState.crossTopicRules).toHaveLength(1);+ expect(planState.crossTopicRules[0]!.slug).toBe(expectedSlug("pref-c", "pref-d"));+ expect(result.skips).toHaveLength(0);+ });++ test("the guard is owner-scoped: another owner's rule never blocks a cluster", () => {+ const { result, plan: planState } = plan([+ rec("pref-a", "Alpha", P_ALPHA),+ rec("pref-b", "Beta", P_BETA),+ promotedRec("pref-cross-kates", "Alpha + Beta", P_ALPHA, undefined, "kate"),+ ]);+ expect(result.fired).toBe(true);+ expect(planState.crossTopicRules).toHaveLength(1);+ expect(planState.crossTopicRules[0]!.owner).toBeUndefined();+ expect(result.skips).toHaveLength(0);+ });++ test("a guard skip spends no daily budget: a different cluster still promotes that day", () => {+ const { result, plan: planState } = plan([+ rec("pref-a", "Alpha", P_ALPHA),+ rec("pref-b", "Beta", P_BETA),+ rec("pref-c", "Gamma", P_BASE_A),+ rec("pref-d", "Delta", P_BASE_B),+ promotedRec("pref-cross-manual", "Alpha + Beta", P_ALPHA, ["[[pref-a]]", "[[pref-b]]"]),+ ]);+ // The duplicate cluster skips (the manual rule cites exactly its+ // sources), the different-principle cluster still fires under the+ // same owner token on the same day.+ expect(result.fired).toBe(true);+ expect(planState.crossTopicRules.map((e) => e.slug)).toEqual([+ expectedSlug("pref-c", "pref-d"),+ ]);+ expect(result.ledger?.last_promoted[""]).toBe(TODAY);+ expect(result.skips).toHaveLength(1);+ });++ test("an existing rule this pass retires does not guard its replacement", () => {+ const day1Slug = expectedSlug("pref-a", "pref-b");+ const { result, plan: planState } = plan(+ [+ rec("pref-a", "Alpha", P_ALPHA),+ rec("pref-b", "Beta", P_BETA),+ rec("pref-c", "Gamma", P_ALPHA),+ promotedRec(`pref-${day1Slug}`, "Alpha + Beta", P_ALPHA),+ ],+ { now: new Date("2026-07-21T10:00:00Z"), retireSlugs: [day1Slug] },+ );+ expect(result.fired).toBe(true);+ expect(planState.crossTopicRules).toHaveLength(1);+ expect(planState.crossTopicRules[0]!.slug).toBe(expectedSlug("pref-a", "pref-b", "pref-c"));+ expect(result.skips).toHaveLength(0);+ });+});++describe("cross-topic ledger", () => {+ let vault: string;++ beforeEach(() => {+ vault = mkdtempSync(join(tmpdir(), "o2b-cross-topic-ledger-"));+ bootstrapBrain(vault, {});+ });+ afterEach(() => {+ rmSync(vault, { recursive: true, force: true });+ });++ test("an absent ledger reads as null and a corrupt one fails open", () => {+ expect(readCrossTopicLedger(vault)).toBeNull();+ const ledgerPath = crossTopicLedgerPath(vault);+ require("node:fs").writeFileSync(ledgerPath, "{not json", "utf8");+ expect(readCrossTopicLedger(vault)).toBeNull();+ });++ test("write then read round-trips through the atomic writer", () => {+ const ledger: CrossTopicLedger = {+ version: CROSS_TOPIC_LEDGER_VERSION,+ last_promoted: { kate: TODAY },+ };+ writeCrossTopicLedger(vault, ledger);+ const path = crossTopicLedgerPath(vault);+ expect(existsSync(path)).toBe(true);+ expect(readCrossTopicLedger(vault)).toEqual(ledger);+ expect(readFileSync(path, "utf8")).toContain('"kate"');+ });+});++// ----- End to end: the promotion inside one dream pass (t_642bc2b8, A2) -----++/**+ * The same claims the planner suite pins, now through `dream()` on the+ * `dream-destructive-gate` pattern: a fired promotion counts as a state+ * change, writes an `inferred` preference with evidence lineage through+ * the transactional writer, lands the ledger beside the rollup ledger,+ * and keeps every non-firing path byte-identical - no-op summary, no+ * ledger, no log file.+ */+describe("dream pass wiring (end to end)", () => {+ const NOW_E2E = new Date("2026-07-19T10:00:00Z");+ const ENABLED = "schema_version: 1\ncross_topic:\n enabled: true\n";+ const SILENT = "schema_version: 1\n";++ let tmp: string;++ beforeEach(() => {+ tmp = mkdtempSync(join(tmpdir(), "o2b-cross-topic-e2e-"));+ });+ afterEach(() => {+ rmSync(tmp, { recursive: true, force: true });+ });++ function makeVault(name: string, configYaml: string): string {+ const vault = join(tmp, name);+ bootstrapBrain(vault, {});+ atomicWriteFileSync(brainConfigPath(vault), configYaml);+ return vault;+ }++ /** Two confirmed sources in two buckets, principles 5/7 apart. */+ function seedPair(vault: string, principleA = P_ALPHA, principleB = P_BETA): void {+ for (const [slug, topic, principle] of [+ ["alpha", "Alpha", principleA],+ ["beta", "Beta", principleB],+ ] as const) {+ writePreference(vault, {+ slug,+ topic,+ principle,+ created_at: "2026-01-01T00:00:00Z",+ unconfirmed_until: "2026-01-08T00:00:00Z",+ // Recent confirmation keeps the stale-no-evidence auto-retire+ // off both sources (see dream-salience-gate.test.ts).+ confirmed_at: "2026-07-17T00:00:00Z",+ status: BRAIN_PREFERENCE_STATUS.confirmed,+ evidenced_by: [],+ applied_count: 0,+ violated_count: 0,+ last_evidence_at: null,+ confidence_value: 0,+ });+ }+ }++ function logFiles(vault: string): string[] {+ const logDir = join(vault, "Brain", "log");+ return existsSync(logDir) ? readdirSync(logDir).map((f) => join(logDir, f)) : [];+ }++ test("a fired promotion writes an inferred pref with lineage and lands the ledger", () => {+ const vault = makeVault("fired", ENABLED);+ seedPair(vault);+ const alphaBefore = readFileSync(join(vault, "Brain", "preferences", "pref-alpha.md"));+ const betaBefore = readFileSync(join(vault, "Brain", "preferences", "pref-beta.md"));++ const summary = dream(vault, { now: NOW_E2E });++ // The promotion alone carries the changed gate.+ expect(summary.changed).toBe(true);+ const slug = expectedSlug("pref-alpha", "pref-beta");+ expect(summary.cross_topic_rules).toEqual([`pref-${slug}`]);+ expect(summary.phases.find((p) => p.phase === "synthesize")?.metrics["cross_topic_rules"]).toBe(+ 1,+ );++ // The written rule: ordinary unconfirmed preference, inferred+ // provenance, evidence wikilinks and related lineage, trial window+ // from the pass's clock.+ const rule = parsePreference(join(vault, "Brain", "preferences", `pref-${slug}.md`));+ expect(rule.provenance).toBe("inferred");+ expect(rule.status).toBe(BRAIN_PREFERENCE_STATUS.unconfirmed);+ expect(rule.topic).toBe("Alpha + Beta");+ expect(rule.principle).toBe(P_ALPHA);+ expect([...rule.evidenced_by]).toEqual(["[[pref-alpha]]", "[[pref-beta]]"]);+ expect([...(rule.related ?? [])]).toEqual(["pref-alpha", "pref-beta"]);+ expect(rule.unconfirmed_until).toBe(+ isoSecond(+ new Date(+ NOW_E2E.getTime() + DEFAULT_BRAIN_CONFIG.dream.unconfirmed_window_days * 24 * 3600 * 1000,+ ),+ ),+ );++ // The ledger, beside the rollup ledger's write discipline.+ expect(readCrossTopicLedger(vault)?.last_promoted[""]).toBe("2026-07-19");++ // The audit trail names the rule (device-sharded day files included).+ const logBody = logFiles(vault)+ .filter((f) => f.endsWith(".md"))+ .map((f) => readFileSync(f, "utf8"))+ .join("\n");+ expect(logBody).toContain(`pref-${slug}`);++ // Sources are untouched: never modified, never retired. (The+ // pass machinery may create the empty `retired/` directory even+ // with zero retires; what must not happen is a retired FILE.)+ expect(readFileSync(join(vault, "Brain", "preferences", "pref-alpha.md"))).toEqual(alphaBefore);+ expect(readFileSync(join(vault, "Brain", "preferences", "pref-beta.md"))).toEqual(betaBefore);+ const retiredDir = join(vault, "Brain", "retired");+ expect(+ existsSync(retiredDir) ? readdirSync(retiredDir).filter((f) => f.endsWith(".md")) : [],+ ).toEqual([]);+ });++ test("a restricted source's promoted rule is not public (finding 63)", () => {+ const vault = makeVault("restricted", ENABLED);+ // One source carries `visibility: [private]`; the rule restates its+ // principle verbatim and must land at that visibility, not the+ // default. The copied `owner` token does not substitute.+ writePreference(vault, {+ slug: "alpha",+ topic: "Alpha",+ principle: P_ALPHA,+ created_at: "2026-01-01T00:00:00Z",+ unconfirmed_until: "2026-01-08T00:00:00Z",+ confirmed_at: "2026-07-17T00:00:00Z",+ status: BRAIN_PREFERENCE_STATUS.confirmed,+ evidenced_by: [],+ applied_count: 0,+ violated_count: 0,+ last_evidence_at: null,+ confidence_value: 0,+ visibility: ["private"],+ });+ writePreference(vault, {+ slug: "beta",+ topic: "Beta",+ principle: P_BETA,+ created_at: "2026-01-01T00:00:00Z",+ unconfirmed_until: "2026-01-08T00:00:00Z",+ confirmed_at: "2026-07-17T00:00:00Z",+ status: BRAIN_PREFERENCE_STATUS.confirmed,+ evidenced_by: [],+ applied_count: 0,+ violated_count: 0,+ last_evidence_at: null,+ confidence_value: 0,+ });++ const summary = dream(vault, { now: NOW_E2E });+ expect(summary.changed).toBe(true);++ const slug = expectedSlug("pref-alpha", "pref-beta");+ const rulePath = join(vault, "Brain", "preferences", `pref-${slug}.md`);+ // The typed parser drops the field; the frontmatter is the contract.+ const rule = parsePreference(rulePath);+ expect(rule.provenance).toBe("inferred");+ expect(pageVisibility(parseFrontmatter(rulePath)[0])).toEqual(["private"]);++ // First counter change (review round 2): one applied event confirms the+ // rule, and the refresh update loop rewrites it. The rule - and the+ // restricted source alpha - carry a `visibility:` line on disk, so the+ // update must carry the tokens through the rewrite AND the no-op+ // pre-flight must be able to render them; a render that omits the line+ // can never match the file, and every later pass rewrites both files+ // with a `_revision` bump.+ const DAY2 = new Date("2026-07-20T10:00:00Z");+ appendApplyEvidence(+ vault,+ {+ pref_id: `pref-${slug}`,+ artifact: "[[Daily/2026.07.20]]",+ result: "applied",+ agent: "test",+ },+ { now: DAY2 },+ );+ dream(vault, { now: DAY2 });+ const changed = parsePreference(rulePath);+ expect(changed.applied_count).toBe(1);+ // The restriction survives the counter-change rewrite.+ expect(pageVisibility(parseFrontmatter(rulePath)[0])).toEqual(["private"]);++ // And the pass after it is a true no-op: same injected now, byte-+ // identical file, nothing counted as changed.+ const before = readFileSync(rulePath);+ const rerun = dream(vault, { now: DAY2 });+ expect(rerun.changed).toBe(false);+ expect(readFileSync(rulePath)).toEqual(before);+ });++ test("a tombstoned promotion never re-fires the slug collision (finding 64)", () => {+ const vault = makeVault("tombstoned", ENABLED);+ seedPair(vault);+ const slug = expectedSlug("pref-alpha", "pref-beta");+ const rulePath = join(vault, "Brain", "preferences", `pref-${slug}.md`);++ dream(vault, { now: NOW_E2E });+ expect(existsSync(rulePath)).toBe(true);++ // Tombstone the promoted file in place: the lifecycle keeps the bytes+ // on disk under `_status: tombstoned`, and the scan drops the record.+ tombstone({+ vault,+ path: `Brain/preferences/pref-${slug}.md`,+ reason: "superseded by hand",+ now: new Date("2026-07-19T12:00:00Z"),+ });++ // Before the fix this pass re-planned the identical content-derived+ // slug and apply's overwrite:false write threw on the live path,+ // blocking every later dream run.+ const day2 = dream(vault, { now: new Date("2026-07-20T10:00:00Z") });+ expect(day2.cross_topic_rules).toBeUndefined();+ expect(existsSync(rulePath)).toBe(true);+ });++ test("a same-day rerun is a no-op: slug dedup below the changed gate", () => {+ const vault = makeVault("rerun", ENABLED);+ seedPair(vault);+ const first = dream(vault, { now: NOW_E2E });+ expect(first.changed).toBe(true);+ const ledgerBefore = readFileSync(crossTopicLedgerPath(vault));++ const second = dream(vault, { now: NOW_E2E });+ expect(second.changed).toBe(false);+ expect(second.cross_topic_rules).toBeUndefined();+ expect(readFileSync(crossTopicLedgerPath(vault))).toEqual(ledgerBefore);+ });++ test("a below-threshold pass is byte-identical: no-op summary, no ledger, no log", () => {+ const vault = makeVault("quiet", ENABLED);+ seedPair(vault, P_ALPHA, P_FAR);++ const summary = dream(vault, { now: NOW_E2E });++ expect(summary.changed).toBe(false);+ expect(summary.cross_topic_rules).toBeUndefined();+ expect(existsSync(crossTopicLedgerPath(vault))).toBe(false);+ expect(logFiles(vault)).toEqual([]);+ });++ test("the block absent keeps a cross-bucket corpus byte-identical", () => {+ const vault = makeVault("off", SILENT);+ seedPair(vault);++ const summary = dream(vault, { now: NOW_E2E });++ expect(summary.changed).toBe(false);+ expect(summary.cross_topic_rules).toBeUndefined();+ expect(existsSync(crossTopicLedgerPath(vault))).toBe(false);+ expect(+ readdirSync(join(vault, "Brain", "preferences")).some((f) => f.startsWith("pref-cross-")),+ ).toBe(false);+ });++ test("a dry run plans the promotion but writes nothing", () => {+ const vault = makeVault("dry", ENABLED);+ seedPair(vault);++ const summary = dream(vault, { now: NOW_E2E, dryRun: true });++ expect(summary.changed).toBe(true);+ expect(summary.cross_topic_rules).toEqual([`pref-${expectedSlug("pref-alpha", "pref-beta")}`]);+ expect(summary.dry_run).toBe(true);+ expect(existsSync(crossTopicLedgerPath(vault))).toBe(false);+ expect(+ readdirSync(join(vault, "Brain", "preferences")).some((f) => f.startsWith("pref-cross-")),+ ).toBe(false);+ });++ test("day 2 after the rule confirms plans no second promotion (finding 61)", () => {+ const vault = makeVault("day2", ENABLED);+ seedPair(vault);+ const slug = expectedSlug("pref-alpha", "pref-beta");++ const day1 = dream(vault, { now: NOW_E2E });+ expect(day1.cross_topic_rules).toEqual([`pref-${slug}`]);++ // One applied event auto-confirms the promoted rule overnight.+ const DAY2 = new Date("2026-07-20T10:00:00Z");+ appendApplyEvidence(+ vault,+ {+ pref_id: `pref-${slug}`,+ artifact: "[[Daily/2026.07.20]]",+ result: "applied",+ agent: "test",+ },+ { now: DAY2 },+ );++ const day2 = dream(vault, { now: DAY2 });++ // The rule's own confirmation is the run's change; no second+ // promotion fires on top of it.+ expect(day2.confirmed).toEqual([`pref-${slug}`]);+ expect(day2.cross_topic_rules).toBeUndefined();+ const crossFiles = readdirSync(join(vault, "Brain", "preferences")).filter(+ (f) => f.startsWith("pref-cross-") && f.endsWith(".md"),+ );+ expect(crossFiles).toEqual([`pref-${slug}.md`]);+ });++ test("day-3 membership churn mints no second rule (M8); the summary reads like the budget skip", () => {+ const vault = makeVault("churn", ENABLED);+ seedPair(vault);+ const day1Slug = expectedSlug("pref-alpha", "pref-beta");++ const day1 = dream(vault, { now: NOW_E2E });+ expect(day1.cross_topic_rules).toEqual([`pref-${day1Slug}`]);++ // Gamma joins the cluster before the promoted rule ever confirms+ // (no applied evidence yet, still inside its 14-day trial window).+ // The joined cluster elects under a new content slug; without the+ // guard this pass mints a second live rule with the identical+ // principle while the day-1 rule stays live.+ writePreference(vault, {+ slug: "gamma",+ topic: "Gamma",+ principle: P_ALPHA,+ created_at: "2026-01-01T00:00:00Z",+ unconfirmed_until: "2026-01-08T00:00:00Z",+ confirmed_at: "2026-07-17T00:00:00Z",+ status: BRAIN_PREFERENCE_STATUS.confirmed,+ evidenced_by: [],+ applied_count: 0,+ violated_count: 0,+ last_evidence_at: null,+ confidence_value: 0,+ });++ const DAY3 = new Date("2026-07-21T10:00:00Z");+ const day3 = dream(vault, { now: DAY3 });++ // The guard's skip discloses on the run summary exactly the way the+ // daily budget's skip does: as the absence of a promotion -+ // `cross_topic_rules` stays absent, nothing counts as created.+ expect(day3.cross_topic_rules).toBeUndefined();+ // Exactly one live rule remains.+ const crossFiles = readdirSync(join(vault, "Brain", "preferences")).filter(+ (f) => f.startsWith("pref-cross-") && f.endsWith(".md"),+ );+ expect(crossFiles).toEqual([`pref-${day1Slug}.md`]);+ // And nothing was written: the ledger still carries only day 1's stamp.+ expect(readCrossTopicLedger(vault)?.last_promoted).toEqual({ "": "2026-07-19" });+ });++ test("the rule's provenance and lineage survive its first counter change (finding 77)", () => {+ const vault = makeVault("lineage", ENABLED);+ seedPair(vault);+ const slug = expectedSlug("pref-alpha", "pref-beta");+ const rulePath = join(vault, "Brain", "preferences", `pref-${slug}.md`);++ dream(vault, { now: NOW_E2E });+ const written = parsePreference(rulePath);+ expect(written.provenance).toBe("inferred");+ expect([...(written.related ?? [])]).toEqual(["pref-alpha", "pref-beta"]);++ // The first applied event: applied_count changes, so the refresh+ // update loop rewrites the file.+ const DAY2 = new Date("2026-07-20T10:00:00Z");+ appendApplyEvidence(+ vault,+ {+ pref_id: `pref-${slug}`,+ artifact: "[[Daily/2026.07.20]]",+ result: "applied",+ agent: "test",+ },+ { now: DAY2 },+ );+ dream(vault, { now: DAY2 });++ // The rewrite must carry both fields forward, not wipe them.+ const after = parsePreference(rulePath);+ expect(after.applied_count).toBe(1);+ expect(after.provenance).toBe("inferred");+ expect([...(after.related ?? [])]).toEqual(["pref-alpha", "pref-beta"]);++ // And with both fields carried through the update itself - not merely+ // preserved as file extras the input-driven render can never match -+ // the no-op pre-flight agrees again: a rerun at the same injected now+ // renders the same bytes and changes nothing. (Before the fix the+ // pre-flight render, built without provenance/related, could never+ // match the written file, so every later pass rewrote the rule.)+ const rerun = dream(vault, { now: DAY2 });+ expect(rerun.changed).toBe(false);+ });++ test("min_topics: 1 cannot promote a singleton and the clamp is disclosed (finding 62)", () => {+ const vault = makeVault(+ "floored",+ "schema_version: 1\ncross_topic:\n enabled: true\n min_topics: 1\n",+ );+ // A single confirmed preference: under the declared knob this elects+ // as a one-bucket "cross-topic" cluster citing one source.+ writePreference(vault, {+ slug: "alpha",+ topic: "Alpha",+ principle: P_ALPHA,+ created_at: "2026-01-01T00:00:00Z",+ unconfirmed_until: "2026-01-08T00:00:00Z",+ confirmed_at: "2026-07-17T00:00:00Z",+ status: BRAIN_PREFERENCE_STATUS.confirmed,+ evidenced_by: [],+ applied_count: 0,+ violated_count: 0,+ last_evidence_at: null,+ confidence_value: 0,+ });++ const summary = dream(vault, { now: NOW_E2E });++ expect(summary.changed).toBe(false);+ expect(summary.cross_topic_rules).toBeUndefined();+ expect(existsSync(crossTopicLedgerPath(vault))).toBe(false);+ const clamp = summary.warnings.find((w) => w.code === "cross-topic-config-clamped");+ expect(clamp?.message).toContain("cross_topic.min_topics");+ expect(clamp?.message).toContain("2");+ });+});++// ----- Staging surfaces (review finding 65) ---------------------------------+// The summary carried `cross_topic_rules`, but nothing downstream consumed+// it: the stage projection omitted the field, proposals.jsonl had no row,+// the report had no section, and the review preview built would_create from+// new_unconfirmed only - so a cross-topic-only pass read as "Planned+// changes: yes" with nothing created, and stage-vs-apply drift could not+// see WHICH rule the pass would promote.++describe("the staging surfaces see a cross-topic promotion (finding 65)", () => {+ const NOW_STAGED = new Date("2026-07-19T10:00:00Z");+ const ENABLED = "schema_version: 1\ncross_topic:\n enabled: true\n";++ let tmp: string;++ beforeEach(() => {+ tmp = mkdtempSync(join(tmpdir(), "o2b-cross-topic-stage-"));+ });+ afterEach(() => {+ rmSync(tmp, { recursive: true, force: true });+ });++ function makeVault(name: string): string {+ const vault = join(tmp, name);+ bootstrapBrain(vault, {});+ atomicWriteFileSync(brainConfigPath(vault), ENABLED);+ return vault;+ }++ function seedThird(vault: string): void {+ writePreference(vault, {+ slug: "gamma",+ topic: "Gamma",+ principle: P_ALPHA,+ created_at: "2026-01-01T00:00:00Z",+ unconfirmed_until: "2026-01-08T00:00:00Z",+ confirmed_at: "2026-07-17T00:00:00Z",+ status: BRAIN_PREFERENCE_STATUS.confirmed,+ evidenced_by: [],+ applied_count: 0,+ violated_count: 0,+ last_evidence_at: null,+ confidence_value: 0,+ });+ }++ test("the projection, proposals and report all name the promoted rule", () => {+ const vault = makeVault("projected");+ for (const [slug, topic, principle] of [+ ["alpha", "Alpha", P_ALPHA],+ ["beta", "Beta", P_BETA],+ ] as const) {+ writePreference(vault, {+ slug,+ topic,+ principle,+ created_at: "2026-01-01T00:00:00Z",+ unconfirmed_until: "2026-01-08T00:00:00Z",+ confirmed_at: "2026-07-17T00:00:00Z",+ status: BRAIN_PREFERENCE_STATUS.confirmed,+ evidenced_by: [],+ applied_count: 0,+ violated_count: 0,+ last_evidence_at: null,+ confidence_value: 0,+ });+ }+ const id = `pref-${expectedSlug("pref-alpha", "pref-beta")}`;++ const bundle = stageDream(vault, { now: NOW_STAGED });++ expect(bundle.plan.changed).toBe(true);+ expect(bundle.plan.cross_topic_rules).toEqual([id]);+ expect(bundle.plan.new_unconfirmed).toEqual([]);+ const proposals = readFileSync(join(bundle.dir, "proposals.jsonl"), "utf8")+ .split("\n")+ .filter((l) => l.trim().length > 0)+ .map((l) => JSON.parse(l) as Record<string, unknown>);+ expect(proposals).toContainEqual({ type: "create_preference", id });+ const report = readFileSync(join(bundle.dir, "REPORT.md"), "utf8");+ expect(report).toContain(id);+ });++ test("validate sees a changed promotion between stage and apply", () => {+ const vault = makeVault("drift");+ for (const [slug, topic, principle] of [+ ["alpha", "Alpha", P_ALPHA],+ ["beta", "Beta", P_BETA],+ ] as const) {+ writePreference(vault, {+ slug,+ topic,+ principle,+ created_at: "2026-01-01T00:00:00Z",+ unconfirmed_until: "2026-01-08T00:00:00Z",+ confirmed_at: "2026-07-17T00:00:00Z",+ status: BRAIN_PREFERENCE_STATUS.confirmed,+ evidenced_by: [],+ applied_count: 0,+ violated_count: 0,+ last_evidence_at: null,+ confidence_value: 0,+ });+ }+ const bundle = stageDream(vault, { now: NOW_STAGED });+ expect(bundle.plan.cross_topic_rules).toEqual(+ [expectedSlug("pref-alpha", "pref-beta")].map((s) => `pref-${s}`),+ );++ // A third source lands after staging: the elected cluster grows, so+ // the pass would promote a DIFFERENT rule than the bundle recorded.+ seedThird(vault);++ const validation = validateDreamBundle(vault, bundle.runId, { now: NOW_STAGED });+ expect(validation.valid).toBe(false);+ expect(validation.drift.some((d) => d.startsWith("cross_topic_rules:"))).toBe(true);+ });++ test("the review preview's would_create includes the promoted rule", async () => {+ const vault = makeVault("preview");+ for (const [slug, topic, principle] of [+ ["alpha", "Alpha", P_ALPHA],+ ["beta", "Beta", P_BETA],+ ] as const) {+ writePreference(vault, {+ slug,+ topic,+ principle,+ created_at: "2026-01-01T00:00:00Z",+ unconfirmed_until: "2026-01-08T00:00:00Z",+ confirmed_at: "2026-07-17T00:00:00Z",+ status: BRAIN_PREFERENCE_STATUS.confirmed,+ evidenced_by: [],+ applied_count: 0,+ violated_count: 0,+ last_evidence_at: null,+ confidence_value: 0,+ });+ }++ const report = await buildReviewCandidates(vault, { now: NOW_STAGED });++ expect(report.would_create).toEqual([`pref-${expectedSlug("pref-alpha", "pref-beta")}`]);+ expect(report.would_promote).toEqual([]);+ });+});diff --git a/tests/core/brain/model-window.test.ts b/tests/core/brain/model-window.test.tsnew file mode 100644index 00000000..c0006575--- /dev/null+++ b/tests/core/brain/model-window.test.ts@@ -0,0 +1,316 @@+import { describe, expect, test } from "bun:test";++import { presetForWindowTokens } from "../../../src/core/brain/context-presets.ts";+import { CONTEXT_WINDOW_TOKENS_DEFAULT } from "../../../src/core/brain/policy.ts";+import {+ DEFAULT_MODEL_CONTEXT_WINDOW_TOKENS,+ declaredModelContextWindowTokens,+ MAX_MODEL_CONTEXT_WINDOW_TOKENS,+ MIN_MODEL_CONTEXT_WINDOW_TOKENS,+ MODEL_CONTEXT_WINDOWS,+ resolveModelContextWindowTokens,+ structuralModelContextWindowTokens,+} from "../../../src/core/brain/model-window.ts";++describe("model context window table", () => {+ test("every table entry is a published in-band window with provenance", () => {+ for (const entry of MODEL_CONTEXT_WINDOWS) {+ expect(entry.windowTokens).toBeGreaterThanOrEqual(MIN_MODEL_CONTEXT_WINDOW_TOKENS);+ expect(entry.windowTokens).toBeLessThanOrEqual(MAX_MODEL_CONTEXT_WINDOW_TOKENS);+ expect(entry.note.length).toBeGreaterThan(0);+ }+ });++ test("declared lookup is exact-id only, case-insensitive", () => {+ expect(declaredModelContextWindowTokens("gpt-4o")).toBe(128_000);+ expect(declaredModelContextWindowTokens("GPT-4O")).toBe(128_000);+ expect(declaredModelContextWindowTokens(" gpt-4o ")).toBe(128_000);+ });++ test("no family substring ever resolves - neither direction", () => {+ // A prefix of a declared id is not the declared id.+ expect(declaredModelContextWindowTokens("gpt-4")).toBeNull();+ // A declared id's family name does not carry its window.+ expect(declaredModelContextWindowTokens("claude-sonnet-4")).toBeNull();+ // A longer id that merely contains a declared id resolves nothing.+ expect(declaredModelContextWindowTokens("my-gpt-4o-custom")).toBeNull();+ });++ test("host-side decorations normalize onto the exact row (M3)", () => {+ // Router prefix: the published model is what the table knows.+ expect(declaredModelContextWindowTokens("openai/gpt-4.1")).toBe(1_000_000);+ // A dated snapshot of a declared id is that declared id.+ expect(declaredModelContextWindowTokens("gpt-4.1-2025-04-14")).toBe(1_000_000);+ // Bedrock-style region prefix plus compact date plus `-vN:N` revision+ // suffix: all plumbing; the row is claude-sonnet-4-5's 200k (NOT 1M -+ // the row decides, the normalizer only reaches it).+ expect(declaredModelContextWindowTokens("us.anthropic.claude-sonnet-4-5-20250929-v1:0")).toBe(+ 200_000,+ );+ expect(declaredModelContextWindowTokens("bedrock/us.anthropic.claude-opus-4-1-v1:0")).toBe(+ 200_000,+ );+ // Through the resolver: the normalized hit answers `declared`, not+ // the default.+ expect(resolveModelContextWindowTokens({ model: "openai/gpt-4.1" })).toEqual({+ windowTokens: 1_000_000,+ source: "declared",+ clamped: false,+ });+ });++ test("normalization never invents a row", () => {+ // A dot-led minor version is not a prefix: `gpt-4.1` survives whole.+ expect(declaredModelContextWindowTokens("gpt-4.1")).toBe(1_000_000);+ // Unknown models stay unknown whatever plumbing they carry.+ expect(declaredModelContextWindowTokens("openai/llama3:8b")).toBeNull();+ expect(declaredModelContextWindowTokens("llama3:8b")).toBeNull();+ // A non-date tail is not stripped.+ expect(declaredModelContextWindowTokens("gpt-4o-preview")).toBeNull();+ });++ test("unknown and null models declare nothing", () => {+ expect(declaredModelContextWindowTokens(null)).toBeNull();+ expect(declaredModelContextWindowTokens(undefined)).toBeNull();+ expect(declaredModelContextWindowTokens("")).toBeNull();+ expect(declaredModelContextWindowTokens("totally-unknown-model")).toBeNull();+ });+});++describe("structural 1m suffix rule", () => {+ test("a trailing delimited 1m suffix declares one million tokens", () => {+ expect(structuralModelContextWindowTokens("gemini-2.5-pro-1m")).toBe(1_000_000);+ expect(structuralModelContextWindowTokens("some-model_1m")).toBe(1_000_000);+ expect(structuralModelContextWindowTokens("GEMINI-2.5-PRO-1M")).toBe(1_000_000);+ });++ test("the bracket form hosts report is a structural 1m suffix too (M3)", () => {+ expect(structuralModelContextWindowTokens("claude-sonnet-5-5[1m]")).toBe(1_000_000);+ expect(structuralModelContextWindowTokens("opus[1m]")).toBe(1_000_000);+ expect(structuralModelContextWindowTokens("MODEL[1M]")).toBe(1_000_000);+ // Through the resolver: the bracket answers `suffix`.+ expect(resolveModelContextWindowTokens({ model: "claude-sonnet-5-5[1m]" })).toEqual({+ windowTokens: 1_000_000,+ source: "suffix",+ clamped: false,+ });+ // Only trailing: text after the bracket is not a window.+ expect(structuralModelContextWindowTokens("model[1m]-preview")).toBeNull();+ // A dot-led fragment is still a version, bracket or not.+ expect(structuralModelContextWindowTokens("gpt-4.1[m]")).toBeNull();+ });++ test("1m inside a larger token never matches", () => {+ // Not trailing.+ expect(structuralModelContextWindowTokens("gemini-2.5-pro-1m-preview")).toBeNull();+ // Trailing but larger token ("1million").+ expect(structuralModelContextWindowTokens("model-1million")).toBeNull();+ // Preceded by an alphanumeric, not a delimiter ("m11m").+ expect(structuralModelContextWindowTokens("minimax-m11m")).toBeNull();+ // Dot-delimited version fragment, not a window suffix ("4.1m").+ expect(structuralModelContextWindowTokens("gpt-4.1m")).toBeNull();+ // A different magnitude.+ expect(structuralModelContextWindowTokens("model-128k")).toBeNull();+ expect(structuralModelContextWindowTokens("model-1mx")).toBeNull();+ });++ test("suffix and declared lookups agree that unknown models carry nothing structural", () => {+ expect(structuralModelContextWindowTokens(null)).toBeNull();+ expect(structuralModelContextWindowTokens("")).toBeNull();+ });+});++describe("resolveModelContextWindowTokens", () => {+ test("the default is the repo's de-facto standard window", () => {+ expect(DEFAULT_MODEL_CONTEXT_WINDOW_TOKENS).toBe(200_000);+ expect(DEFAULT_MODEL_CONTEXT_WINDOW_TOKENS).toBe(CONTEXT_WINDOW_TOKENS_DEFAULT);+ expect(resolveModelContextWindowTokens({})).toEqual({+ windowTokens: 200_000,+ source: "default",+ clamped: false,+ });+ expect(resolveModelContextWindowTokens({ model: null })).toEqual({+ windowTokens: 200_000,+ source: "default",+ clamped: false,+ });+ // An unknown model id is a default, never a family guess.+ expect(resolveModelContextWindowTokens({ model: "mystery-model" })).toEqual({+ windowTokens: 200_000,+ source: "default",+ clamped: false,+ });+ });++ test("declared table beats suffix beats default", () => {+ expect(resolveModelContextWindowTokens({ model: "gpt-4o" })).toEqual({+ windowTokens: 128_000,+ source: "declared",+ clamped: false,+ });+ expect(resolveModelContextWindowTokens({ model: "gemini-2.5-pro-1m" })).toEqual({+ windowTokens: 1_000_000,+ source: "suffix",+ clamped: false,+ });+ });++ test("operator env beats table and suffix", () => {+ expect(+ resolveModelContextWindowTokens({+ model: "gpt-4o",+ envWindowTokens: 150_000,+ }),+ ).toEqual({ windowTokens: 150_000, source: "operator-env", clamped: false });+ expect(+ resolveModelContextWindowTokens({+ model: "gemini-2.5-pro-1m",+ envWindowTokens: 150_000,+ }),+ ).toEqual({ windowTokens: 150_000, source: "operator-env", clamped: false });+ });++ test("operator config beats env", () => {+ expect(+ resolveModelContextWindowTokens({+ model: "gpt-4o",+ operatorWindowTokens: 400_000,+ envWindowTokens: 150_000,+ }),+ ).toEqual({ windowTokens: 400_000, source: "operator-config", clamped: false });+ });++ test("a declared window passes through unclamped at any size", () => {+ // The declaration exists to keep budgets inside the true window: an+ // 8k local model declared exactly must not be re-inflated.+ expect(resolveModelContextWindowTokens({ operatorWindowTokens: 8_000 })).toEqual({+ windowTokens: 8_000,+ source: "operator-config",+ clamped: false,+ });+ expect(resolveModelContextWindowTokens({ envWindowTokens: 8_000 })).toEqual({+ windowTokens: 8_000,+ source: "operator-env",+ clamped: false,+ });+ // Above the historical ceiling too - the operator knows the deployment.+ expect(resolveModelContextWindowTokens({ operatorWindowTokens: 5_000_000 })).toEqual({+ windowTokens: 5_000_000,+ source: "operator-config",+ clamped: false,+ });+ expect(resolveModelContextWindowTokens({ envWindowTokens: 5_000_000 })).toEqual({+ windowTokens: 5_000_000,+ source: "operator-env",+ clamped: false,+ });+ // Band edges were never clamps and still are not.+ expect(resolveModelContextWindowTokens({ operatorWindowTokens: 100_000 })).toEqual({+ windowTokens: 100_000,+ source: "operator-config",+ clamped: false,+ });+ expect(resolveModelContextWindowTokens({ operatorWindowTokens: 1_000_000 })).toEqual({+ windowTokens: 1_000_000,+ source: "operator-config",+ clamped: false,+ });+ });++ test("a declared 32k window sizes tight-context, not the 100k clamp", () => {+ const resolved = resolveModelContextWindowTokens({ operatorWindowTokens: 32_000 });+ expect(resolved).toEqual({+ windowTokens: 32_000,+ source: "operator-config",+ clamped: false,+ });+ // The bucket mapping every derived budget is sized from agrees: the+ // tight-context pack budget, never long-context.+ expect(presetForWindowTokens(resolved.windowTokens).id).toBe("tight-context");+ expect(presetForWindowTokens(resolved.windowTokens).context_pack.max_tokens).toBe(4_000);+ });++ test("a declared 32k base beats a -1m suffix and is never clamped to the 100k floor", () => {+ // The reviewed bug: the old resolver clamped the declaration up to+ // the band minimum (100_000, clamped: true) and every derived budget+ // went long-context, overflowing the very model the declaration+ // describes. The declaration is first-hand; the suffix is a guess.+ expect(+ resolveModelContextWindowTokens({ operatorWindowTokens: 32_000, model: "qwen3-32b-1m" }),+ ).toEqual({ windowTokens: 32_000, source: "operator-config", clamped: false });+ // The suffix alone stays a derived answer inside the band: one+ // million, exactly the band's top edge, reported unclamped.+ expect(resolveModelContextWindowTokens({ model: "qwen3-32b-1m" })).toEqual({+ windowTokens: 1_000_000,+ source: "suffix",+ clamped: false,+ });+ });++ test("the band governs the guessed answers, which sit inside it today", () => {+ // The clamp's remaining charge: the `-1m` suffix expansion and the+ // unknown-model default, where the true window is unknown and the+ // band is the sanity bound. Both published figures sit inside the+ // band, so `clamped` is false on every derivable answer - and a+ // constant drifting out of band is a bug this pins.+ expect(resolveModelContextWindowTokens({ model: "gemini-2.5-pro-1m" })).toEqual({+ windowTokens: MAX_MODEL_CONTEXT_WINDOW_TOKENS,+ source: "suffix",+ clamped: false,+ });+ expect(resolveModelContextWindowTokens({})).toEqual({+ windowTokens: DEFAULT_MODEL_CONTEXT_WINDOW_TOKENS,+ source: "default",+ clamped: false,+ });+ expect(DEFAULT_MODEL_CONTEXT_WINDOW_TOKENS).toBeGreaterThanOrEqual(+ MIN_MODEL_CONTEXT_WINDOW_TOKENS,+ );+ expect(DEFAULT_MODEL_CONTEXT_WINDOW_TOKENS).toBeLessThanOrEqual(+ MAX_MODEL_CONTEXT_WINDOW_TOKENS,+ );+ });++ test("a declared value still wins over a lower declared table entry", () => {+ expect(+ resolveModelContextWindowTokens({+ model: "gpt-4o",+ operatorWindowTokens: 5_000_000,+ }),+ ).toEqual({ windowTokens: 5_000_000, source: "operator-config", clamped: false });+ });++ test("zero, negative and non-finite operator values resolve nothing", () => {+ expect(resolveModelContextWindowTokens({ operatorWindowTokens: 0 })).toEqual({+ windowTokens: 200_000,+ source: "default",+ clamped: false,+ });+ expect(resolveModelContextWindowTokens({ envWindowTokens: -5 })).toEqual({+ windowTokens: 200_000,+ source: "default",+ clamped: false,+ });+ expect(resolveModelContextWindowTokens({ operatorWindowTokens: Number.NaN })).toEqual({+ windowTokens: 200_000,+ source: "default",+ clamped: false,+ });+ });++ test("the resolver is pure: it never reads the environment itself", () => {+ const key = "OPEN_SECOND_BRAIN_MODEL_CONTEXT_WINDOW";+ const previous = process.env[key];+ process.env[key] = "999_999";+ try {+ expect(resolveModelContextWindowTokens({})).toEqual({+ windowTokens: 200_000,+ source: "default",+ clamped: false,+ });+ } finally {+ if (previous === undefined) delete process.env[key];+ else process.env[key] = previous;+ }+ });+});diff --git a/tests/core/brain/policy/context-block.test.ts b/tests/core/brain/policy/context-block.test.tsnew file mode 100644index 00000000..5e00b1c6--- /dev/null+++ b/tests/core/brain/policy/context-block.test.ts@@ -0,0 +1,230 @@+/**+ * The two blocks of the cycle-20261020 substrate wave (`cross_topic:`+ * and `context:`) plus the environment channel that overrides the+ * context window. Both blocks are operator opt-ins whose ABSENCE must+ * leave a vault byte-identical, so the acceptance cases pin the stored+ * shape and the rejection cases make a typo a named load error rather+ * than a silently ignored key: an unknown top-level key only warns+ * forward-compat, so a misspelled block would otherwise resolve to the+ * default with no sign of why.+ *+ * Out-of-range but well-formed numeric values are ACCEPTED here - these+ * parsers store what the operator declared, they do not second-guess it.+ * What the consumer does next differs by block: the cross-topic resolver+ * floors its knobs (disclosing every clamp), while the context window's+ * operator declarations pass through the resolver UNCLAMPED - only the+ * resolver's guessed answers clamp to its band (model-window.ts;+ * design decision 2).+ */++import { describe, expect, test } from "bun:test";++import {+ MODEL_CONTEXT_WINDOW_ENV_KEY,+ resolveModelContextWindowEnvTokens,+} from "../../../../src/core/config.ts";+import {+ CONTEXT_WINDOW_TOKENS_DEFAULT,+ parseContextBlock,+ parseCrossTopicBlock,+} from "../../../../src/core/brain/policy.ts";+import { BrainConfigError } from "../../../../src/core/brain/policy/errors.ts";+import {+ validateBrainConfig,+ validateBrainConfigDetailed,+} from "../../../../src/core/brain/policy/validate.ts";+import {+ KeyIndexCollector,+ type BlockParseContext,+} from "../../../../src/core/brain/policy/key-index.ts";+import { parseBrainYaml } from "../../../../src/core/brain/yaml-parse.ts";++function load(block: string) {+ return validateBrainConfigDetailed(+ parseBrainYaml(`schema_version: 1\n${block}`),+ "<test fixture>",+ );+}++function blockContext(obj: Record<string, unknown>): BlockParseContext {+ return { obj, source: "<test fixture>", warnings: [], keys: new KeyIndexCollector() };+}++function expectFieldError(block: string, field: string): void {+ let caught: unknown;+ try {+ load(block);+ } catch (err) {+ caught = err;+ }+ expect(caught).toBeInstanceOf(BrainConfigError);+ expect((caught as BrainConfigError).field).toBe(field);+}++describe("cross_topic block", () => {+ test("the parsers are re-exported from the public policy surface", () => {+ expect(parseCrossTopicBlock(blockContext({ cross_topic: { enabled: true } }))).toEqual({+ enabled: true,+ });+ expect(parseContextBlock(blockContext({ context: { window_tokens: 400000 } }))).toEqual({+ window_tokens: 400000,+ });+ });++ test("the full block parses to a frozen partial config", () => {+ const { config, warnings } = load(+ "cross_topic:\n enabled: true\n min_topics: 3\n jaccard: 0.5\n",+ );+ expect(warnings).toEqual([]);+ expect(config.cross_topic).toEqual({ enabled: true, min_topics: 3, jaccard: 0.5 });+ expect(Object.isFrozen(config.cross_topic)).toBe(true);+ });++ test("a vault without the block has no cross_topic key", () => {+ const config = validateBrainConfig(parseBrainYaml("schema_version: 1\n"), "<test fixture>");+ expect("cross_topic" in config).toBe(false);+ });++ test("an absent sub-key stays absent, exactly as declared", () => {+ expect(load("cross_topic:\n enabled: true\n").config.cross_topic).toEqual({ enabled: true });+ });++ test("enabled: false parses - the explicit spelling of the absent behaviour", () => {+ expect(load("cross_topic:\n enabled: false\n").config.cross_topic).toEqual({+ enabled: false,+ });+ });++ test("a non-boolean enabled is a hard error", () => {+ expectFieldError("cross_topic:\n enabled: yes\n", "cross_topic.enabled");+ expectFieldError("cross_topic:\n enabled: 1\n", "cross_topic.enabled");+ });++ test("min_topics outside the positive integers is a hard error", () => {+ expectFieldError("cross_topic:\n min_topics: 0\n", "cross_topic.min_topics");+ expectFieldError("cross_topic:\n min_topics: -1\n", "cross_topic.min_topics");+ expectFieldError("cross_topic:\n min_topics: 2.5\n", "cross_topic.min_topics");+ expectFieldError("cross_topic:\n min_topics: two\n", "cross_topic.min_topics");+ });++ test("min_topics: 1 is stored as declared - the resolver floors it, not the parser (finding 82)", () => {+ expect(load("cross_topic:\n min_topics: 1\n").config.cross_topic).toEqual({+ min_topics: 1,+ });+ });++ test("jaccard outside [0, 1] is a hard error, and the endpoints are accepted", () => {+ expectFieldError("cross_topic:\n jaccard: 1.5\n", "cross_topic.jaccard");+ expectFieldError("cross_topic:\n jaccard: -0.1\n", "cross_topic.jaccard");+ expect(load("cross_topic:\n jaccard: 0\n").config.cross_topic?.jaccard).toBe(0);+ expect(load("cross_topic:\n jaccard: 1\n").config.cross_topic?.jaccard).toBe(1);+ });++ test("an unknown sub-key warns and does not error", () => {+ const { config, warnings } = load("cross_topic:\n enabled: true\n future_knob: 3\n");+ expect(config.cross_topic?.enabled).toBe(true);+ expect(warnings.map((w) => w.message)).toEqual([+ "cross_topic.future_knob: unknown field ignored (forward-compat)",+ ]);+ });++ test("a block that is not a map is a hard error", () => {+ expectFieldError("cross_topic: 5\n", "cross_topic");+ });+});++describe("context block", () => {+ test("window_tokens parses to the declared value", () => {+ const { config, warnings } = load("context:\n window_tokens: 1000000\n");+ expect(warnings).toEqual([]);+ expect(config.context).toEqual({ window_tokens: 1000000 });+ expect(Object.isFrozen(config.context)).toBe(true);+ });++ test("a vault without the block has no context key", () => {+ const config = validateBrainConfig(parseBrainYaml("schema_version: 1\n"), "<test fixture>");+ expect("context" in config).toBe(false);+ });++ test("out-of-range values are accepted and stored - the parser never clamps", () => {+ expect(load("context:\n window_tokens: 50\n").config.context).toEqual({ window_tokens: 50 });+ expect(load("context:\n window_tokens: 5000000\n").config.context).toEqual({+ window_tokens: 5000000,+ });+ });++ test("a value outside the positive integers is a hard error", () => {+ expectFieldError("context:\n window_tokens: 0\n", "context.window_tokens");+ expectFieldError("context:\n window_tokens: -100\n", "context.window_tokens");+ expectFieldError("context:\n window_tokens: 2.5\n", "context.window_tokens");+ expectFieldError("context:\n window_tokens: big\n", "context.window_tokens");+ });++ test("an unknown sub-key warns and does not error", () => {+ const { config, warnings } = load("context:\n window_tokens: 400000\n future_knob: 1\n");+ expect(config.context?.window_tokens).toBe(400000);+ expect(warnings.map((w) => w.message)).toEqual([+ "context.future_knob: unknown field ignored (forward-compat)",+ ]);+ });++ test("a block that is not a map is a hard error", () => {+ expectFieldError("context: 200000\n", "context");+ });+});++describe("the model context window env helper", () => {+ function withEnv(value: string | undefined, run: () => void): void {+ const previous = process.env[MODEL_CONTEXT_WINDOW_ENV_KEY];+ if (value === undefined) delete process.env[MODEL_CONTEXT_WINDOW_ENV_KEY];+ else process.env[MODEL_CONTEXT_WINDOW_ENV_KEY] = value;+ try {+ run();+ } finally {+ if (previous === undefined) delete process.env[MODEL_CONTEXT_WINDOW_ENV_KEY];+ else process.env[MODEL_CONTEXT_WINDOW_ENV_KEY] = previous;+ }+ }++ test("the env key is the documented one and the default constant is exported", () => {+ expect(MODEL_CONTEXT_WINDOW_ENV_KEY).toBe("OPEN_SECOND_BRAIN_MODEL_CONTEXT_WINDOW");+ expect(CONTEXT_WINDOW_TOKENS_DEFAULT).toBe(200_000);+ });++ test("an unset variable resolves to undefined", () => {+ withEnv(undefined, () => {+ expect(resolveModelContextWindowEnvTokens()).toBeUndefined();+ });+ });++ test("a blank variable is unset", () => {+ withEnv(" ", () => {+ expect(resolveModelContextWindowEnvTokens()).toBeUndefined();+ });+ });++ test("an integer is parsed", () => {+ withEnv("400000", () => {+ expect(resolveModelContextWindowEnvTokens()).toBe(400_000);+ });+ });++ test("out-of-range integers are accepted - passed through downstream, not refused", () => {+ withEnv("50", () => {+ expect(resolveModelContextWindowEnvTokens()).toBe(50);+ });+ withEnv("5000000", () => {+ expect(resolveModelContextWindowEnvTokens()).toBe(5_000_000);+ });+ });++ test("a value outside the positive integers fails fast, naming the key", () => {+ for (const garbage of ["big", "2.5", "0", "-5"]) {+ withEnv(garbage, () => {+ expect(() => resolveModelContextWindowEnvTokens()).toThrow(+ `${MODEL_CONTEXT_WINDOW_ENV_KEY} must be a positive integer`,+ );+ });+ }+ });+});diff --git a/tests/core/brain/published-schema-contracts.test.ts b/tests/core/brain/published-schema-contracts.test.tsindex ac607602..68115c3d 100644--- a/tests/core/brain/published-schema-contracts.test.ts+++ b/tests/core/brain/published-schema-contracts.test.ts@@ -43,6 +43,8 @@ import {complexityPathFactors,} from "../../../src/core/discipline/complexity.ts";import { BRAIN_TOOLS } from "../../../src/mcp/brain-tools.ts";+import { SEARCH_INPUT_SCHEMA } from "../../../src/mcp/search-tools.ts";+import { buildSearchQueryArtifact } from "../../../src/cli/search/verbs/schema-export.ts";import {assertSupportedSchema,type SchemaNode,@@ -57,6 +59,7 @@ const SCHEMA_IDS: Readonly<Record<string, string>> = {"retention-review.schema.json": "brain.retention_review.v1","monthly-review.schema.json": "brain.monthly_review.v1","complexity-report.schema.json": "brain.complexity_report.v1",+ "search-query.schema.json": "brain.search_query.v1",};function loadSchema(file: string): SchemaNode {@@ -151,6 +154,67 @@ describe("the published schema set", () => {'unsupported format "uri"',);});++ test("the string and array length bounds the search schema uses are enforced", () => {+ // t_50c81d5c E4: the brain_search language bounds its strings+ // (minLength/maxLength) and arrays (maxItems); a validator that+ // skipped them would claim a guarantee the published file makes.+ const schema: SchemaNode = {+ type: "object",+ required: ["q"],+ additionalProperties: false,+ properties: {+ q: { type: "string", minLength: 1, maxLength: 4 },+ tags: { type: "array", maxItems: 2, items: { type: "string" } },+ },+ };+ expect(validateAgainstSchema(schema, { q: "ok", tags: ["a"] }).ok).toBe(true);+ expect(validateAgainstSchema(schema, { q: "", tags: [] }).errors).toContain(+ "q must be at least 1 character(s)",+ );+ expect(validateAgainstSchema(schema, { q: "toolong", tags: [] }).errors).toContain(+ "q must be at most 4 character(s)",+ );+ expect(validateAgainstSchema(schema, { q: "ok", tags: ["a", "b", "c"] }).errors).toContain(+ "tags must have at most 2 item(s)",+ );+ });++ test("additionalProperties as a SCHEMA validates unknown keys against it", () => {+ // The properties row of the search schema types its extra keys; the+ // boolean form keeps its exact previous meaning.+ const typed: SchemaNode = {+ type: "object",+ properties: { known: { type: "string" } },+ additionalProperties: { type: "array", items: { type: "string" } },+ };+ expect(+ validateAgainstSchema(typed, { known: "x", filter: ["a", "b"] }).ok,+ "unknown keys matching the schema pass",+ ).toBe(true);+ expect(validateAgainstSchema(typed, { known: "x", filter: "not-an-array" }).errors).toContain(+ "filter must be array",+ );+ const closed: SchemaNode = {+ type: "object",+ properties: { known: { type: "string" } },+ additionalProperties: false,+ };+ expect(validateAgainstSchema(closed, { known: "x", extra: 1 }).errors).toContain(+ "extra is not allowed",+ );+ });++ test("a $defs block is walked like any schema node, and its children are checked", () => {+ // The search-query artifact carries its query-document grammar as a+ // $defs sibling; an unsupported keyword hiding inside $defs must+ // still be refused.+ expect(() =>+ assertSupportedSchema({+ $defs: { doc: { type: "string", pattern: "^x$" } },+ }),+ ).toThrow('unsupported schema keyword "pattern"');+ });});describe("brain.intent_review.v1", () => {@@ -320,3 +384,58 @@ describe("brain.complexity_report.v1", () => {expectValid(loadSchema("complexity-report.schema.json"), report);});});++describe("brain.search_query.v1 (t_50c81d5c E4)", () => {+ test("the committed file equals what the descriptor derives - the generator check", () => {+ // JSON equality, not byte equality: the file is hand-formatted like+ // its siblings and the generator owns the content, not the layout.+ const onDisk: unknown = JSON.parse(+ readFileSync(join(SCHEMA_DIR, "search-query.schema.json"), "utf8"),+ );+ expect(onDisk).toEqual(asJson(buildSearchQueryArtifact()));+ });++ test("the artifact is the mcp projection plus the query-document grammar", () => {+ const artifact = loadSchema("search-query.schema.json");+ expect(artifact.$id).toBe("brain.search_query.v1");+ const served = SEARCH_INPUT_SCHEMA as unknown as Record<string, unknown>;+ const properties = artifact.properties as Record<string, SchemaNode>;+ // Every served brain_search argument is a property of the artifact,+ // spelled identically.+ for (const [name, fragment] of Object.entries(served.properties as Record<string, unknown>)) {+ expect(properties[name] as unknown).toEqual(fragment);+ }+ expect(Object.keys(properties).toSorted()).toEqual(+ Object.keys(served.properties as Record<string, unknown>).toSorted(),+ );+ expect(artifact.required).toEqual(["query"]);+ expect(artifact.additionalProperties).toBe(false);+ // The sibling grammar block declares its own versioned id.+ const docGrammar = (+ (artifact as unknown as Record<string, unknown>)["$defs"] as Record<string, SchemaNode>+ )["search_query_document"];+ expect(docGrammar).toBeDefined();+ expect(docGrammar!.$id).toBe("brain.search_query_document.v1");+ });++ test("a documented brain_search argument object validates against the artifact", () => {+ const artifact = loadSchema("search-query.schema.json");+ const args = {+ query: "project alpha",+ query_document: 'intent: entity\nlex: "project alpha" -archived\nvec: active context',+ kind: "section",+ since: "last week",+ limit: 10,+ disclosure: "cards",+ match_mode: "any",+ };+ expectValid(artifact, args);+ // And the drift the contract exists to catch is refused by name.+ const unknown = { ...args, definitely_not_an_argument: true };+ expect(validateAgainstSchema(artifact, unknown).errors).toContain(+ "definitely_not_an_argument is not allowed",+ );+ const badEnum = { ...args, disclosure: "essays" };+ expect(validateAgainstSchema(artifact, badEnum).errors[0]).toContain("disclosure");+ });+});diff --git a/tests/core/brain/session-identity-check.test.ts b/tests/core/brain/session-identity-check.test.tsindex 233aa50e..59a2684c 100644--- a/tests/core/brain/session-identity-check.test.ts+++ b/tests/core/brain/session-identity-check.test.ts@@ -362,6 +362,15 @@ const KIND_WRITERS: ReadonlyArray<{},{ kind: "negative_recall", sessionScoped: false, writers: ["core/brain/gate-telemetry.ts"] },{ kind: "decision_model_call", sessionScoped: false, writers: ["core/decision-model/record.ts"] },+ {+ // Cycle 20261020: the preregistered eval's grade cache. Machine-side+ // evidence keyed by spec hash, fixture hash and item ids - no session+ // correlation anywhere in the payload, exactly like the call record+ // beside it.+ kind: "decision_model_eval_grade",+ sessionScoped: false,+ writers: ["core/decision-model/record.ts"],+ },{kind: "decision_model_extract_commit",sessionScoped: true,diff --git a/tests/core/decision-model/eval-grade.test.ts b/tests/core/decision-model/eval-grade.test.tsnew file mode 100644index 00000000..bcfa17ce--- /dev/null+++ b/tests/core/decision-model/eval-grade.test.ts@@ -0,0 +1,794 @@+/**+ * The graded eval runner and its cached verdict records (cycle 20261020,+ * card t_4e1681b3, task C2).+ *+ * The runner verifies the preregistration (spec receipt, fixture hash)+ * before it sends anything, runs one decision request per take item with+ * `recordOrigin: "eval"`, and caches the verdicts as+ * `decision_model_eval_grade` records stamped with the spec hash. Eval+ * requests are real spend: they count toward the daily cost gate but+ * stay out of the rerank shadow agreement. The graded eval itself runs+ * against the fake provider - no real model calls in tests.+ */++import { afterEach, beforeEach, describe, expect, mock, test } from "bun:test";+import { mkdirSync, mkdtempSync, readFileSync, rmSync, writeFileSync } from "node:fs";+import { tmpdir } from "node:os";+import { join } from "node:path";++import type { DecisionRequest } from "../../../src/core/decision-model/contract.ts";+import { appendContinuityRecord } from "../../../src/core/brain/continuity/store.ts";+import type { ResolvedDecisionModelConfig } from "../../../src/core/decision-model/config.ts";+import {+ DECISION_EVAL_DEV_FRACTION,+ DECISION_EVAL_METRIC,+ DECISION_EVAL_SPEC_VERSION,+ DECISION_EVAL_SPLIT_RULE,+ decisionEvalSpecFor,+ decisionEvalSpecHash,+ type DecisionEvalSpec,+} from "../../../src/core/decision-model/eval-spec.ts";+import { runDecisionModelEval, scoreRecall } from "../../../src/core/decision-model/eval/grade.ts";+import {+ decisionModelTuningMarkPath,+ resetTuningMarkCache,+ validatedTuningMark,+} from "../../../src/core/decision-model/eval/mark.ts";+import {+ hashOrderSplit,+ loadDecisionEvalFixture,+} from "../../../src/core/decision-model/eval/take.ts";+import { canonicalJson, sha256Hex } from "../../../src/core/integrity/digest.ts";+import { buildDecisionModelReport } from "../../../src/core/decision-model/diagnostics.ts";+import {+ listDecisionModelCalls,+ listDecisionModelEvalGrades,+ resetDecisionSpendCache,+ todaySpendUsd,+} from "../../../src/core/decision-model/record.ts";+import { FakeDecisionProvider } from "../../helpers/fake-decision-provider.ts";+import type { PlatformDirsEnv } from "../../../src/core/platform-dirs.ts";++let tmp: string;+let vault: string;+let stateEnv: PlatformDirsEnv;++beforeEach(() => {+ tmp = mkdtempSync(join(tmpdir(), "osb-dm-eval-grade-"));+ vault = join(tmp, "vault");+ mkdirSync(join(vault, "Brain"), { recursive: true });+ stateEnv = { platform: "linux", home: tmp, env: { XDG_STATE_HOME: join(tmp, "state") } };+ resetDecisionSpendCache();+ resetTuningMarkCache();+});+afterEach(() => {+ rmSync(tmp, { recursive: true, force: true });+ resetDecisionSpendCache();+ resetTuningMarkCache();+});++/** The subject each fixture query prompts about, by the fixtures' own rule. */+function subjectOf(query: string): string {+ return /the (.+)\?/.exec(query)![1]!;+}++/** Answers relevance/helps by the fixtures' labeling rule: on-topic helps. */+function byLabelRule(id: string, req: DecisionRequest): number {+ const state = req.state as {+ query?: string;+ prompt?: string;+ passages?: Record<string, string>;+ notes?: Record<string, string>;+ };+ const subject = subjectOf(state.query ?? state.prompt ?? "");+ const key = id.startsWith("rel_")+ ? `P${id.slice(4)}`+ : id.startsWith("helps_")+ ? `N${id.slice(6)}`+ : null;+ if (key === null) return 0.5;+ const text = state.passages?.[key] ?? state.notes?.[key] ?? "";+ return text.includes(subject) ? 0.99 : 0.01;+}++const INVERTED = (id: string, req: DecisionRequest): number =>+ byLabelRule(id, req) > 0.5 ? 0.01 : 0.99;++function evalConfig(+ overrides: Partial<ResolvedDecisionModelConfig> = {},+): ResolvedDecisionModelConfig {+ const uses = {+ rerank: "shadow",+ answerable: "off",+ skills: "off",+ extract_prefilter: "off",+ dedup: "off",+ tension: "off",+ labels: "off",+ recall_inject: "shadow",+ } as ResolvedDecisionModelConfig["uses"];+ return {+ status: "active",+ errors: [],+ notes: [],+ enabled: true,+ provider: "compatible",+ adapter: "systemone",+ baseUrl: "http://127.0.0.1:9",+ model: "fake-model-1",+ envKey: "FAKE_DECISION_KEY_UNUSED",+ keyPresent: true,+ allowInsecureHttp: false,+ timeoutMs: 3000,+ hookBudgetMs: 700,+ maxStateTokens: 32_000,+ uses,+ configuredUses: uses,+ dailyCostGateUsd: 0.5,+ inputPriceUsdPerMtok: 0.042,+ allowUncalibrated: false,+ calibrated: true,+ thresholdProfile: "laya",+ shadowOnlyUses: ["rerank", "recall_inject"],+ processor: null,+ vault,+ ...overrides,+ };+}++describe("runDecisionModelEval", () => {+ test("a provider that answers by the labeling rule promotes the rerank use", async () => {+ const spec = decisionEvalSpecFor("rerank")!;+ const result = await runDecisionModelEval("rerank", {+ config: evalConfig(),+ provider: new FakeDecisionProvider({ answer: byLabelRule }),+ });+ expect(result.verdict).toBe("promote");+ expect(result.use).toBe("rerank");+ expect(result.profile).toBe("laya");+ expect(result.spec_hash).toBe(decisionEvalSpecHash(spec));+ expect(result.counted.n).toBe(30);+ expect(result.counted.error).toBe(0);+ // The committed take holds the gold-relevant candidate first on only+ // 11 of 43 items, and the counted split of those is 8 - the+ // input-order baseline must not look better than it is.+ expect(result.baseline_error).toBeCloseTo(22 / 30, 10);+ // One grade record, stamped with the spec hash and the correlated+ // per-item request ids.+ const { grades, skipped } = listDecisionModelEvalGrades(vault);+ expect(skipped).toEqual([]);+ expect(grades).toHaveLength(1);+ const grade = grades[0]!;+ expect(grade.use).toBe("rerank");+ expect(grade.profile).toBe("laya");+ expect(grade.specHash).toBe(decisionEvalSpecHash(spec));+ expect(grade.countedIds).toHaveLength(30);+ expect(grade.devIds).toHaveLength(13);+ expect(Object.entries(grade.verdicts)).toHaveLength(30);+ for (const verdict of Object.values(grade.verdicts)) expect(verdict).toBe(true);+ expect(grade.callIds).toHaveLength(43);+ expect(grade.verdict).toBe("promote");+ expect(grade.metric).toBe("counted_error_rate");+ });++ test("a provider that ranks the relevant candidate last holds, and the record says so", async () => {+ const result = await runDecisionModelEval("rerank", {+ config: evalConfig(),+ provider: new FakeDecisionProvider({ answer: INVERTED }),+ });+ expect(result.verdict).toBe("hold");+ expect(result.counted.error).toBe(1);+ const { grades } = listDecisionModelEvalGrades(vault);+ expect(grades[0]!.verdict).toBe("hold");+ expect(grades[0]!.countedError).toBe(1);+ for (const verdict of Object.values(grades[0]!.verdicts)) expect(verdict).toBe(false);+ });++ test("eval requests carry origin eval, count as spend, and stay out of shadow agreement", async () => {+ await runDecisionModelEval("rerank", {+ config: evalConfig(),+ provider: new FakeDecisionProvider({ answer: byLabelRule }),+ });+ const calls = listDecisionModelCalls(vault);+ expect(calls.length).toBe(43);+ for (const call of calls) {+ expect(`origin: ${String(call.payload["origin"])}`).toBe("origin: eval");+ expect(`mode: ${String(call.payload["mode"])}`).toBe("mode: enforce");+ }+ expect(todaySpendUsd(vault)).toBeGreaterThan(0);+ // The agreement compares shadow records only; eval records are kept+ // out of it (diagnostics agreementOf skips any record with an origin).+ const report = buildDecisionModelReport(vault, { use: "rerank" });+ const rerank = report.uses.find((u) => u.use === "rerank");+ expect(rerank?.agreement).toBeUndefined();+ });++ test("a spec whose counted take is below its minimum n is not enough evidence", async () => {+ const registry = decisionEvalSpecFor("rerank")!;+ const spec: DecisionEvalSpec = {+ ...registry,+ min_counted: registry.receipt.counted.length + 1,+ };+ const result = await runDecisionModelEval("rerank", {+ config: evalConfig(),+ provider: new FakeDecisionProvider({ answer: byLabelRule }),+ spec,+ });+ expect(result.verdict).toBe("not_enough_evidence");+ const { grades } = listDecisionModelEvalGrades(vault);+ expect(grades[0]!.specHash).toBe(decisionEvalSpecHash(spec));+ expect(grades[0]!.specHash).not.toBe(decisionEvalSpecHash(registry));+ });++ test("degraded requests shrink the counted n instead of counting as misses", async () => {+ const result = await runDecisionModelEval("rerank", {+ config: evalConfig(),+ provider: new FakeDecisionProvider({ fail: "timeout" }),+ });+ expect(result.degraded_n).toBe(43);+ expect(result.counted.n).toBe(0);+ expect(result.verdict).toBe("not_enough_evidence");+ });++ test("the eval asks inject_any and grades its abstain arm like enforce does", async () => {+ // High helps everywhere, but inject_any below the pinned any_min: the+ // enforced filter abstains the whole brief (every note was sent), so+ // every useful note is lost - real regret the metric must see.+ const provider = new FakeDecisionProvider({+ answer: (id, req) => (id === "inject_any" ? 0.01 : byLabelRule(id, req)),+ });+ const result = await runDecisionModelEval("recall_inject", {+ config: evalConfig(),+ provider,+ });+ expect(Object.keys(provider.requests[0]!.questions)).toContain("inject_any");+ expect(result.verdict).toBe("hold");+ expect(result.counted.n).toBe(20);+ expect(result.counted.error).toBe(1);+ const { grades } = listDecisionModelEvalGrades(vault);+ expect(grades).toHaveLength(1);+ expect(grades[0]!.verdict).toBe("hold");+ for (const verdict of Object.values(grades[0]!.verdicts)) expect(verdict).toBe(false);+ });++ test("an inject_any answer above the abstain floor does not manufacture regret", async () => {+ const result = await runDecisionModelEval("recall_inject", {+ config: evalConfig(),+ provider: new FakeDecisionProvider({+ answer: (id, req) => (id === "inject_any" ? 0.99 : byLabelRule(id, req)),+ }),+ });+ expect(result.verdict).toBe("promote");+ expect(result.counted.error).toBe(0);+ });++ test("the recall_inject use grades regret against the pinned drop floor", async () => {+ const promoted = await runDecisionModelEval("recall_inject", {+ config: evalConfig(),+ provider: new FakeDecisionProvider({ answer: byLabelRule }),+ });+ expect(promoted.verdict).toBe("promote");+ expect(promoted.counted.n).toBe(20);+ expect(promoted.counted.error).toBe(0);+ // A useful note rated below the pinned note_min floor is regret.+ const regretful = await runDecisionModelEval("recall_inject", {+ config: evalConfig(),+ provider: new FakeDecisionProvider({ answer: INVERTED }),+ });+ expect(regretful.verdict).toBe("hold");+ expect(regretful.counted.error).toBe(1);+ });++ test("an ok reply whose every answer is invalid degrades instead of matching the baseline", async () => {+ // Every relevance answer unusable: the enforced reorder has no usable+ // answer either, so the item shrinks n - it must never count as a+ // full-n sample whose verdict equals the input-order baseline.+ const result = await runDecisionModelEval("rerank", {+ config: evalConfig(),+ provider: new FakeDecisionProvider({ answer: () => ({ invalid: true }) }),+ });+ expect(result.degraded_n).toBe(43);+ expect(result.counted.n).toBe(0);+ expect(result.verdict).toBe("not_enough_evidence");+ });++ test("an invalid first answer still pins the top slot like the enforced reorder", async () => {+ // One unusable answer with the rest usable is not degradation: the+ // enforced reorder pins the unanswered candidate at index 0.+ const result = await runDecisionModelEval("rerank", {+ config: evalConfig(),+ provider: new FakeDecisionProvider({+ answer: (id) => (id === "rel_0" ? { invalid: true } : 0.5),+ }),+ });+ expect(result.degraded_n).toBe(0);+ expect(result.counted.n).toBe(30);+ expect(result.counted.error).toBeCloseTo(22 / 30, 10);+ });++ test("scoring is canonical: an early invalid answer does not mask a later below-floor note", async () => {+ // Two counted items carry the same answers in opposite slot order:+ // one useful note with no usable answer and one valid answer below+ // the pinned note_min. The below-floor note is dropped in enforce on+ // both, so both are counted failures - the first slot's invalid+ // answer must not turn the item into a shrunk-n degrade.+ const seed = "order-scoring";+ const ids = ["ord-1", "ord-2", "ord-3", "ord-4", "ord-5", "ord-6", "ord-7"];+ const { dev, counted } = hashOrderSplit(seed, ids);+ const [invalidFirst, floorFirst] = counted.slice(0, 2);+ const fillerSubjects = new Map(+ ids+ .filter((id) => id !== invalidFirst && id !== floorFirst)+ .map((id, i) => [id, ["marmalade", "ballast", "kestrel", "vellum", "tundra"][i]!]),+ );+ const note = (+ subject: string,+ useful: boolean,+ ): { title: string; text: string; useful: boolean } => ({+ title: `${subject} note`,+ text: useful ? `all about ${subject}` : "nothing about anything",+ useful,+ });+ const raw = {+ use: "recall_inject",+ items: ids.map((id) => {+ if (id === invalidFirst || id === floorFirst) {+ const subject = id === invalidFirst ? "arduino" : "beadwork";+ return {+ id,+ kind: "recall_inject",+ prompt: `What should I know about the ${subject}?`,+ notes: [note(subject, true), note(`${subject} second`, true)],+ };+ }+ const subject = fillerSubjects.get(id)!;+ return {+ id,+ kind: "recall_inject",+ prompt: `What should I know about the ${subject}?`,+ notes: [note(subject, true), note("unrelated", false)],+ };+ }),+ };+ const fixturePath = join(tmp, "order-take.json");+ writeFileSync(fixturePath, JSON.stringify(raw), "utf8");+ const spec: DecisionEvalSpec = {+ version: DECISION_EVAL_SPEC_VERSION,+ use: "recall_inject",+ fixture: fixturePath,+ seed,+ split: { rule: DECISION_EVAL_SPLIT_RULE, dev_fraction: DECISION_EVAL_DEV_FRACTION },+ receipt: { dev, counted },+ fixture_hash: sha256Hex(canonicalJson(raw)),+ metric: DECISION_EVAL_METRIC,+ ceiling: 0,+ min_counted: counted.length,+ thresholds: { any_min: 0.2, note_min: 0.2 },+ };+ const provider = new FakeDecisionProvider({+ answer: (id, req) => {+ const prompt = (req.state as { prompt?: string }).prompt ?? "";+ if (prompt.includes("arduino")) {+ if (id === "helps_0") return { invalid: true };+ if (id === "helps_1") return 0.01;+ }+ if (prompt.includes("beadwork")) {+ if (id === "helps_0") return 0.01;+ if (id === "helps_1") return { invalid: true };+ }+ return byLabelRule(id, req);+ },+ });+ const result = await runDecisionModelEval("recall_inject", {+ config: evalConfig(),+ provider,+ spec,+ });+ expect(result.degraded_n).toBe(0);+ expect(result.counted.n).toBe(4);+ expect(result.counted.error).toBe(0.5);+ expect(result.baseline_error).toBe(0);+ expect(result.verdict).toBe("hold");+ const { grades } = listDecisionModelEvalGrades(vault);+ expect(grades[0]!.verdicts[invalidFirst!]).toBe(false);+ expect(grades[0]!.verdicts[floorFirst!]).toBe(false);+ });++ test("a grade record correlates only its own run's calls", async () => {+ await runDecisionModelEval("recall_inject", {+ config: evalConfig(),+ provider: new FakeDecisionProvider({ answer: byLabelRule }),+ });+ await runDecisionModelEval("recall_inject", {+ config: evalConfig(),+ provider: new FakeDecisionProvider({ answer: INVERTED }),+ });+ const { grades } = listDecisionModelEvalGrades(vault);+ expect(grades).toHaveLength(2);+ // The take has 29 items: each record lists this run's one call per+ // item, never the earlier runs' calls with the same item ids.+ const [first, second] = grades;+ expect(first!.callIds).toHaveLength(29);+ expect(second!.callIds).toHaveLength(29);+ expect(second!.callIds.filter((id) => first!.callIds.includes(id))).toEqual([]);+ });++ test("a promote with no grade evidence refuses the mark by name", async () => {+ // No vault: nothing was recorded, so the promote has no review+ // evidence a reviewer could audit the mark against - the run+ // measures, but the gate input is never written.+ const result = await runDecisionModelEval("rerank", {+ config: evalConfig({ vault: null }),+ provider: new FakeDecisionProvider({ answer: byLabelRule }),+ markSource: stateEnv,+ });+ expect(result.verdict).toBe("promote");+ expect(result.grade_record_id).toBeNull();+ expect(result.mark_written).toBe(false);+ expect(result.mark_note).toMatch(/grade record/);+ expect(validatedTuningMark("laya", "rerank", stateEnv)).toBeNull();+ });++ test("a promote whose day's recorded spend reached the daily cost gate refuses the mark", async () => {+ // The gate reads the vault's total for the whole UTC day - this run's+ // own records included, alongside anything else that spent today. The+ // run's records push that day total past the gate: the verdict is+ // promote and the spend is real, yet the day's recorded spend has+ // reached the gate, so the mark waits for a run that stays under it.+ const result = await runDecisionModelEval("rerank", {+ config: evalConfig({ dailyCostGateUsd: 42.5, inputPriceUsdPerMtok: 1 }),+ provider: new FakeDecisionProvider({+ answer: byLabelRule,+ usage: { inputTokens: 1_000_000, outputTokens: 0 },+ }),+ markSource: stateEnv,+ });+ expect(result.verdict).toBe("promote");+ expect(result.counted.n).toBe(30);+ expect(result.counted.error).toBe(0);+ expect(todaySpendUsd(vault)).toBeGreaterThanOrEqual(42.5);+ expect(result.mark_written).toBe(false);+ expect(result.mark_note).toMatch(/today's recorded spend reached the daily cost gate/);+ expect(result.mark_note).not.toMatch(/run's counted spend/);+ expect(validatedTuningMark("laya", "rerank", stateEnv)).toBeNull();+ });++ test("an unreadable day-spend log refuses the mark by name instead of throwing", async () => {+ // `todaySpendUsd` throws when the call log cannot be read, and the+ // mark decision runs after the measurement and the grade record are+ // already written - so the throw must fold into the refusal, the way+ // the gate itself treats an unreadable log (over the limit), never+ // escape `runDecisionModelEval` at this stage. The mock raises only+ // once the run's grade record is on disk: the pre-request gate+ // consults the same read, and there the log is still readable - the+ // log breaks between the measurement and the mark, the exact race+ // this stage must survive.+ const RECORD_MODULE = "../../../src/core/decision-model/record.ts";+ // This runner's mock registration outlives mock.restore() across test+ // FILES, so the teardown re-registers the REAL module object instead:+ // whatever leaks past this file is record.ts itself, byte for byte.+ const realRecord = { ...(await import(RECORD_MODULE)) };+ mock.module(RECORD_MODULE, () => ({+ ...realRecord,+ todaySpendUsd: (v: string, n: Date) => {+ if (realRecord.listDecisionModelEvalGrades(v).grades.length > 0) {+ throw new Error("the call log could not be read");+ }+ return realRecord.todaySpendUsd(v, n);+ },+ }));+ try {+ const result = await runDecisionModelEval("rerank", {+ config: evalConfig(),+ provider: new FakeDecisionProvider({ answer: byLabelRule }),+ markSource: stateEnv,+ });+ expect(result.verdict).toBe("promote");+ // The measurement and its review evidence are already on disk.+ expect(result.grade_record_id).not.toBeNull();+ expect(listDecisionModelEvalGrades(vault).grades).toHaveLength(1);+ expect(result.mark_written).toBe(false);+ expect(result.mark_note).toMatch(/could not be read/);+ expect(validatedTuningMark("laya", "rerank", stateEnv)).toBeNull();+ } finally {+ mock.module(RECORD_MODULE, () => realRecord);+ mock.restore();+ }+ });++ test("a counted error past the baseline holds even under a permissive ceiling", async () => {+ // The no-regression arm is a refusal in its own right, distinct from+ // the ceiling: this provider answers the labeling rule on the dev+ // split only, so the counted split regresses past the input-order+ // baseline (error 1 against 22/30) while staying under this spec's+ // permissive ceiling of 1. Only the baseline comparison refuses the+ // promote - and with it, the tuning mark.+ const registry = decisionEvalSpecFor("rerank")!;+ // Queries repeat across the take, so the split is keyed by request+ // order: the runner sends exactly one request per item, in fixture+ // order.+ const items = loadDecisionEvalFixture(registry.fixture, "rerank").fixture.items;+ const countedIndexes = new Set(+ items+ .map((item, i) => (registry.receipt.counted.includes(item.id) ? i : -1))+ .filter((i) => i >= 0),+ );+ const spec: DecisionEvalSpec = { ...registry, ceiling: 1 };+ // One index per distinct request object (the fake answers per+ // question, so a counter would run several times per item).+ const indexOfRequest = new Map<DecisionRequest, number>();+ const provider = new FakeDecisionProvider({+ answer: (id, req) => {+ let i = indexOfRequest.get(req);+ if (i === undefined) {+ i = indexOfRequest.size;+ indexOfRequest.set(req, i);+ }+ return countedIndexes.has(i) ? INVERTED(id, req) : byLabelRule(id, req);+ },+ });+ const result = await runDecisionModelEval("rerank", {+ config: evalConfig(),+ provider,+ spec,+ markSource: stateEnv,+ });+ expect(result.dev.error).toBe(0);+ expect(result.counted.error).toBe(1);+ expect(result.counted.error!).toBeLessThanOrEqual(spec.ceiling);+ expect(result.baseline_error!).toBeLessThan(result.counted.error!);+ expect(result.verdict).toBe("hold");+ expect(result.mark_written).toBe(false);+ const { grades } = listDecisionModelEvalGrades(vault);+ expect(grades[0]!.verdict).toBe("hold");+ });++ test("a completed hold retracts the earlier promote's mark", async () => {+ const promoted = await runDecisionModelEval("rerank", {+ config: evalConfig(),+ provider: new FakeDecisionProvider({ answer: byLabelRule }),+ markSource: stateEnv,+ });+ expect(promoted.mark_written).toBe(true);+ expect(promoted.mark_retracted).toBe(false);+ expect(validatedTuningMark("laya", "rerank", stateEnv)).not.toBeNull();+ // The later hold is a completed measurement that missed its own bar:+ // the earlier mark is withdrawn, not left armed beside it.+ const held = await runDecisionModelEval("rerank", {+ config: evalConfig(),+ provider: new FakeDecisionProvider({ answer: INVERTED }),+ markSource: stateEnv,+ });+ expect(held.verdict).toBe("hold");+ expect(held.mark_written).toBe(false);+ expect(held.mark_retracted).toBe(true);+ expect(held.mark_note).toMatch(/retracted/);+ expect(validatedTuningMark("laya", "rerank", stateEnv)).toBeNull();+ });++ test("not enough evidence retracts too, a degraded run included", async () => {+ const promote = () =>+ runDecisionModelEval("rerank", {+ config: evalConfig(),+ provider: new FakeDecisionProvider({ answer: byLabelRule }),+ markSource: stateEnv,+ });+ await promote();+ // A run under the same spec whose usable answers shrink the counted+ // n below the minimum is still a completed measurement: its verdict+ // is no verdict, and the mark it would have refreshed is withdrawn.+ const starved = new FakeDecisionProvider({+ answer: (id, req) => {+ const query = (req.state as { query?: string }).query ?? "";+ // rk-001, rk-016 and rk-031 share this query - three counted+ // items whose every answer is unusable (27 counted remain).+ return query === "How do I look after the kubernetes?" && id.startsWith("rel_")+ ? { invalid: true }+ : byLabelRule(id, req);+ },+ });+ const shortRun = await runDecisionModelEval("rerank", {+ config: evalConfig(),+ provider: starved,+ markSource: stateEnv,+ });+ expect(shortRun.verdict).toBe("not_enough_evidence");+ expect(shortRun.counted.n).toBe(27);+ expect(shortRun.mark_retracted).toBe(true);+ expect(validatedTuningMark("laya", "rerank", stateEnv)).toBeNull();++ // A run where nothing usable came back measures nothing about+ // quality either: the verdict still completes, and the mark goes.+ await promote();+ const degraded = await runDecisionModelEval("rerank", {+ config: evalConfig(),+ provider: new FakeDecisionProvider({ fail: "timeout" }),+ markSource: stateEnv,+ });+ expect(degraded.verdict).toBe("not_enough_evidence");+ expect(degraded.degraded_n).toBe(43);+ expect(degraded.mark_retracted).toBe(true);+ expect(validatedTuningMark("laya", "rerank", stateEnv)).toBeNull();+ });++ test("a refused run retracts nothing", async () => {+ await runDecisionModelEval("rerank", {+ config: evalConfig(),+ provider: new FakeDecisionProvider({ answer: byLabelRule }),+ markSource: stateEnv,+ });+ const registry = decisionEvalSpecFor("rerank")!;+ const tampered: DecisionEvalSpec = {+ ...registry,+ receipt: { dev: registry.receipt.dev, counted: registry.receipt.counted.slice(1) },+ };+ await expect(+ runDecisionModelEval("rerank", {+ config: evalConfig(),+ provider: new FakeDecisionProvider({ answer: byLabelRule }),+ spec: tampered,+ markSource: stateEnv,+ }),+ ).rejects.toThrow(/preregistration/);+ expect(validatedTuningMark("laya", "rerank", stateEnv)).not.toBeNull();+ });++ test("a non-promote run retracts only a mark its own spec earned", async () => {+ // The on-disk mark was earned by the registry spec. A hold measured+ // under a drifted spec speaks for the drifted spec, not for that+ // mark - which is already shadow anyway (its spec hash no longer+ // matches the drifted spec), so deleting it is neither owed nor done.+ await runDecisionModelEval("rerank", {+ config: evalConfig(),+ provider: new FakeDecisionProvider({ answer: byLabelRule }),+ markSource: stateEnv,+ });+ const registry = decisionEvalSpecFor("rerank")!;+ const drifted: DecisionEvalSpec = { ...registry, thresholds: { min_score: 0.5 } };+ const held = await runDecisionModelEval("rerank", {+ config: evalConfig(),+ provider: new FakeDecisionProvider({ answer: INVERTED }),+ spec: drifted,+ markSource: stateEnv,+ });+ expect(held.verdict).toBe("hold");+ expect(held.mark_retracted).toBe(false);+ const markPath = decisionModelTuningMarkPath(stateEnv, "laya", "rerank");+ expect(JSON.parse(readFileSync(markPath, "utf8"))).toMatchObject({+ spec_hash: decisionEvalSpecHash(registry),+ verdict: "promote",+ });+ });++ test("a hold with no state root retracts nothing", async () => {+ await runDecisionModelEval("rerank", {+ config: evalConfig(),+ provider: new FakeDecisionProvider({ answer: byLabelRule }),+ markSource: stateEnv,+ });+ const held = await runDecisionModelEval("rerank", {+ config: evalConfig(),+ provider: new FakeDecisionProvider({ answer: INVERTED }),+ markSource: null,+ });+ expect(held.verdict).toBe("hold");+ expect(held.mark_retracted).toBe(false);+ expect(validatedTuningMark("laya", "rerank", stateEnv)).not.toBeNull();+ });++ test("refuses a use with no preregistered spec and an inactive config", async () => {+ await expect(+ runDecisionModelEval("dedup", {+ config: evalConfig(),+ provider: new FakeDecisionProvider({ answer: byLabelRule }),+ }),+ ).rejects.toThrow(/no preregistered spec/);+ await expect(+ runDecisionModelEval("rerank", {+ config: evalConfig({ status: "no_key" }),+ provider: new FakeDecisionProvider({ answer: byLabelRule }),+ }),+ ).rejects.toThrow(/active/);+ });++ test("the runner verifies the preregistration before sending anything", async () => {+ const registry = decisionEvalSpecFor("rerank")!;+ const tampered: DecisionEvalSpec = {+ ...registry,+ receipt: { dev: registry.receipt.dev, counted: registry.receipt.counted.slice(1) },+ };+ const provider = new FakeDecisionProvider({ answer: byLabelRule });+ await expect(+ runDecisionModelEval("rerank", { config: evalConfig(), provider, spec: tampered }),+ ).rejects.toThrow(/preregistration/);+ expect(provider.requests).toHaveLength(0);+ expect(listDecisionModelCalls(vault)).toHaveLength(0);+ });+});++/** One gold-labeled recall note, for the scorer's regret-rule pins. */+const labeledNote = (useful: boolean) => ({ title: "n", text: "t", useful });++/**+ * Answers for the scorer's pins: one `helps_<k>` per slot, `undefined`+ * meaning the question went unanswered (helps null), plus `inject_any`.+ */+function recallAnswers(+ helps: ReadonlyArray<number | undefined>,+ injectAny: number | undefined,+): Record<string, { valid: boolean; value: number }> {+ const out: Record<string, { valid: boolean; value: number }> = {};+ helps.forEach((p, k) => {+ if (p !== undefined) out[`helps_${k}`] = { valid: true, value: p };+ });+ if (injectAny !== undefined) out["inject_any"] = { valid: true, value: injectAny };+ return out;+}++/** One recall item with the given gold labels, for the scorer's pins. */+const recallItem = (useful: ReadonlyArray<boolean>) => ({+ id: "it",+ kind: "recall_inject" as const,+ prompt: "What should I know?",+ notes: useful.map(labeledNote),+});++describe("scoreRecall's abstain regret rule", () => {+ // The committed fixture grammar requires every item to carry a useful+ // note, so the no-useful-note rule is pinned here, directly on the+ // scorer.++ test("an abstain over an item with no useful note is not a regret", () => {+ // inject_any below the pinned any_min abstains the whole brief - but+ // nothing in it is gold-useful, so withholding loses nothing and the+ // item must not count as a failure.+ const scored = scoreRecall(recallItem([false, false]), recallAnswers([0.01, 0.01], 0.01));+ expect(scored).toEqual({ verdict: true, baseline: true, degraded: false });+ });++ test("a withheld brief over an item with no useful note is not a regret", () => {+ // The other withholding arm: every helps below the pinned note_min,+ // so enforce drops the whole brief. No gold-useful note is lost.+ const scored = scoreRecall(recallItem([false, false]), recallAnswers([0.01, 0.01], 0.99));+ expect(scored).toEqual({ verdict: true, baseline: true, degraded: false });+ });++ test("a kept brief over an item with no useful note is not a regret", () => {+ // Sanity on the same labels: a kept note and no abstain stays a pass.+ const scored = scoreRecall(recallItem([false, false]), recallAnswers([0.9, 0.01], 0.99));+ expect(scored).toEqual({ verdict: true, baseline: true, degraded: false });+ });++ test("an abstain over an item with a useful note is still a failure", () => {+ // The useful note would be withheld with the brief: a real regret.+ const scored = scoreRecall(recallItem([true, false]), recallAnswers([0.99, 0.01], 0.01));+ expect(scored).toEqual({ verdict: false, baseline: true, degraded: false });+ });++ test("a dropped useful note is still a failure", () => {+ const scored = scoreRecall(recallItem([true, false]), recallAnswers([0.01, 0.9], 0.99));+ expect(scored).toEqual({ verdict: false, baseline: true, degraded: false });+ });+});++describe("listDecisionModelEvalGrades", () => {+ test("skips a malformed grade record with a named note", async () => {+ await runDecisionModelEval("rerank", {+ config: evalConfig(),+ provider: new FakeDecisionProvider({ answer: byLabelRule }),+ });+ // A hand-written record that claims a measurement but lacks the+ // fields every real grade carries.+ appendContinuityRecord(vault, {+ kind: "decision_model_eval_grade",+ createdAt: new Date().toISOString(),+ sourceRefs: [],+ payload: { use: "rerank", verdict: "promote" },+ });+ const { grades, skipped } = listDecisionModelEvalGrades(vault);+ expect(grades).toHaveLength(1);+ expect(skipped).toHaveLength(1);+ expect(skipped[0]).toMatch(/decision_model_eval_grade/);+ expect(skipped[0]).toMatch(/spec_hash/);+ });+});diff --git a/tests/core/decision-model/eval-mark.test.ts b/tests/core/decision-model/eval-mark.test.tsnew file mode 100644index 00000000..4515ec6a--- /dev/null+++ b/tests/core/decision-model/eval-mark.test.ts@@ -0,0 +1,651 @@+/**+ * The machine-side tuning mark and the measured gate (cycle 20261020,+ * card t_4e1681b3, task C3).+ *+ * The mark is the one machine-consumed summary the config resolver+ * consults when the source table says a use is untuned. It is accepted+ * ONLY when its spec hash, fixture hash and pinned threshold values+ * match the installed spec, and when its recorded endpoint - the+ * provider id, the pinned model id and the base-URL hash of the config+ * that earned it - matches the config being resolved; anything else+ * fails closed to shadow, and a mark written before the endpoint+ * binding (no endpoint fields) is no mark at all. With no mark file+ * everything behaves exactly as the hand-edit path always did. The+ * vault's grade records are review evidence; this file is the gate+ * input, and it is written solely by the eval runner, and only on a+ * promote verdict.+ */++import { afterEach, beforeEach, describe, expect, test } from "bun:test";+import { mkdirSync, mkdtempSync, readFileSync, rmSync, writeFileSync } from "node:fs";+import { tmpdir } from "node:os";+import { dirname, join } from "node:path";++import { sha256Hex } from "../../../src/core/integrity/digest.ts";++import type { DecisionRequest } from "../../../src/core/decision-model/contract.ts";+import {+ decisionModelModeFor,+ type ResolvedDecisionModelConfig,+ resolveDecisionModelConfig,+} from "../../../src/core/decision-model/config.ts";+import {+ decisionEvalSpecFor,+ decisionEvalSpecHash,+ type DecisionEvalSpec,+} from "../../../src/core/decision-model/eval-spec.ts";+import { runDecisionModelEval } from "../../../src/core/decision-model/eval/grade.ts";+import {+ decisionModelTuningMarkPath,+ machineTunedMarkReader,+ readTuningMark,+ resetTuningMarkCache,+ retractTuningMark,+ validatedTuningMark,+ writeTuningMark,+} from "../../../src/core/decision-model/eval/mark.ts";+import type { PlatformDirsEnv } from "../../../src/core/platform-dirs.ts";+import { decisionModelStateDir } from "../../../src/core/platform-dirs.ts";+import { FakeDecisionProvider } from "../../helpers/fake-decision-provider.ts";++let tmp: string;+let vault: string;+let stateEnv: PlatformDirsEnv;++beforeEach(() => {+ tmp = mkdtempSync(join(tmpdir(), "osb-dm-eval-mark-"));+ vault = join(tmp, "vault");+ mkdirSync(join(vault, "Brain"), { recursive: true });+ stateEnv = { platform: "linux", home: tmp, env: { XDG_STATE_HOME: join(tmp, "state") } };+ resetTuningMarkCache();+});+afterEach(() => {+ rmSync(tmp, { recursive: true, force: true });+ resetTuningMarkCache();+});++/** Answers relevance/helps by the fixtures' labeling rule: on-topic helps. */+function byLabelRule(id: string, req: DecisionRequest): number {+ const state = req.state as {+ query?: string;+ prompt?: string;+ passages?: Record<string, string>;+ notes?: Record<string, string>;+ };+ const subject = /the (.+)\?/.exec(state.query ?? state.prompt ?? "")![1]!;+ const key = id.startsWith("rel_")+ ? `P${id.slice(4)}`+ : id.startsWith("helps_")+ ? `N${id.slice(6)}`+ : null;+ if (key === null) return 0.5;+ const text = state.passages?.[key] ?? state.notes?.[key] ?? "";+ return text.includes(subject) ? 0.99 : 0.01;+}++const INVERTED = (id: string, req: DecisionRequest): number =>+ byLabelRule(id, req) > 0.5 ? 0.01 : 0.99;++function evalConfig(profile: string | null = "laya"): ResolvedDecisionModelConfig {+ return {+ status: "active",+ errors: [],+ notes: [],+ enabled: true,+ provider: "compatible",+ adapter: "systemone",+ baseUrl: "http://127.0.0.1:9",+ model: "fake-model-1",+ envKey: "FAKE_DECISION_KEY_UNUSED",+ keyPresent: true,+ allowInsecureHttp: false,+ timeoutMs: 3000,+ hookBudgetMs: 700,+ maxStateTokens: 32_000,+ uses: {+ rerank: "shadow",+ answerable: "off",+ skills: "off",+ extract_prefilter: "off",+ dedup: "off",+ tension: "off",+ labels: "off",+ recall_inject: "off",+ },+ configuredUses: {+ rerank: "shadow",+ answerable: "off",+ skills: "off",+ extract_prefilter: "off",+ dedup: "off",+ tension: "off",+ labels: "off",+ recall_inject: "off",+ },+ dailyCostGateUsd: 0.5,+ inputPriceUsdPerMtok: 0.042,+ allowUncalibrated: false,+ calibrated: true,+ thresholdProfile: profile,+ shadowOnlyUses: ["rerank"],+ processor: null,+ vault,+ };+}++describe("the machine-side mark file", () => {+ test("lives under the decision-model state directory, keyed by profile and use", () => {+ const path = decisionModelTuningMarkPath(stateEnv, "laya", "rerank");+ expect(path.startsWith(decisionModelStateDir(stateEnv))).toBe(true);+ expect(path).toContain(join("tuning-marks", "laya", "rerank.json"));+ });++ test("write and read round-trip; malformed content reads as null", () => {+ const path = decisionModelTuningMarkPath(stateEnv, "laya", "rerank");+ const spec = decisionEvalSpecFor("rerank")!;+ writeTuningMark(path, {+ profile: "laya",+ use: "rerank",+ spec_hash: "a".repeat(64),+ fixture_hash: spec.fixture_hash,+ thresholds: {},+ metric: "counted_error_rate",+ counted_n: 30,+ counted_error: 0,+ baseline_error: 0.5,+ verdict: "promote",+ created_at: "2026-10-20T00:00:00.000Z",+ provider: "compatible",+ model: "fake-model-1",+ base_url_hash: sha256Hex("http://127.0.0.1:9"),+ });+ const mark = readTuningMark(path);+ expect(mark?.profile).toBe("laya");+ expect(mark?.verdict).toBe("promote");+ expect(mark?.model).toBe("fake-model-1");+ expect(mark?.base_url_hash).toBe(sha256Hex("http://127.0.0.1:9"));+ const broken = join(tmp, "broken.json");+ writeFileSync(broken, "{not json", "utf8");+ expect(readTuningMark(broken)).toBeNull();+ });++ test("the TTL cache serves reads without re-reading, until reset", () => {+ const path = decisionModelTuningMarkPath(stateEnv, "laya", "rerank");+ const spec = decisionEvalSpecFor("rerank")!;+ const base = {+ profile: "laya",+ use: "rerank" as const,+ spec_hash: "a".repeat(64),+ fixture_hash: spec.fixture_hash,+ thresholds: {},+ metric: "counted_error_rate",+ counted_n: 30,+ counted_error: 0,+ baseline_error: 0.5,+ verdict: "promote" as const,+ provider: "compatible",+ model: "fake-model-1",+ base_url_hash: sha256Hex("http://127.0.0.1:9"),+ };+ writeTuningMark(path, { ...base, created_at: "2026-10-20T00:00:00.000Z" });+ expect(readTuningMark(path)?.created_at).toBe("2026-10-20T00:00:00.000Z");+ writeFileSync(+ path,+ JSON.stringify({ ...base, created_at: "2026-10-21T00:00:00.000Z" }),+ "utf8",+ );+ expect(readTuningMark(path)?.created_at).toBe("2026-10-20T00:00:00.000Z");+ resetTuningMarkCache();+ expect(readTuningMark(path)?.created_at).toBe("2026-10-21T00:00:00.000Z");+ });+});++describe("retractTuningMark", () => {+ const registry = decisionEvalSpecFor("rerank")!;++ function markOnDisk(specHash: string): void {+ writeTuningMark(decisionModelTuningMarkPath(stateEnv, "laya", "rerank"), {+ profile: "laya",+ use: "rerank",+ spec_hash: specHash,+ fixture_hash: registry.fixture_hash,+ thresholds: {},+ metric: "counted_error_rate",+ counted_n: 30,+ counted_error: 0,+ baseline_error: 0.5,+ verdict: "promote",+ created_at: "2026-10-20T00:00:00.000Z",+ provider: "compatible",+ model: "fake-model-1",+ base_url_hash: sha256Hex("http://127.0.0.1:9"),+ });+ }++ test("deletes a spec-matched mark, and the deletion is visible immediately", () => {+ const specHash = decisionEvalSpecHash(registry);+ markOnDisk(specHash);+ expect(readTuningMark(decisionModelTuningMarkPath(stateEnv, "laya", "rerank"))).not.toBeNull();+ expect(retractTuningMark(stateEnv, "laya", "rerank", specHash)).toBe(true);+ // No cache reset: a retraction must be seen by the very next read.+ expect(readTuningMark(decisionModelTuningMarkPath(stateEnv, "laya", "rerank"))).toBeNull();+ });++ test("keeps a foreign-spec mark, and reports false when there is nothing to retract", () => {+ markOnDisk("a".repeat(64));+ // A hold under another spec does not speak for this mark.+ expect(retractTuningMark(stateEnv, "laya", "rerank", "b".repeat(64))).toBe(false);+ expect(readTuningMark(decisionModelTuningMarkPath(stateEnv, "laya", "rerank"))).not.toBeNull();+ // Retracting the matching mark twice: the second is a no-op.+ expect(retractTuningMark(stateEnv, "laya", "rerank", "a".repeat(64))).toBe(true);+ expect(retractTuningMark(stateEnv, "laya", "rerank", "a".repeat(64))).toBe(false);+ // No state root, or no profile: there is no (profile, use) pair.+ expect(retractTuningMark(null, "laya", "rerank", "a".repeat(64))).toBe(false);+ expect(retractTuningMark(stateEnv, null, "rerank", "a".repeat(64))).toBe(false);+ });+});++describe("validatedTuningMark", () => {+ test("accepts a mark that matches the installed spec on every axis", async () => {+ await runDecisionModelEval("rerank", {+ config: evalConfig(),+ provider: new FakeDecisionProvider({ answer: byLabelRule }),+ markSource: stateEnv,+ });+ const mark = validatedTuningMark("laya", "rerank", stateEnv);+ expect(mark?.use).toBe("rerank");+ expect(mark?.counted_n).toBe(30);+ expect(mark?.thresholds).toEqual({});+ });++ test("fails closed on a foreign spec hash, a changed fixture hash or drifted thresholds", async () => {+ await runDecisionModelEval("rerank", {+ config: evalConfig(),+ provider: new FakeDecisionProvider({ answer: byLabelRule }),+ markSource: stateEnv,+ });+ const path = decisionModelTuningMarkPath(stateEnv, "laya", "rerank");+ const valid = JSON.parse(readFileSync(path, "utf8")) as Record<string, unknown>;++ const foreign = { ...valid, spec_hash: "f".repeat(64) };+ writeFileSync(path, JSON.stringify(foreign), "utf8");+ resetTuningMarkCache();+ expect(validatedTuningMark("laya", "rerank", stateEnv)).toBeNull();++ const refixtured = { ...valid, fixture_hash: "e".repeat(64) };+ writeFileSync(path, JSON.stringify(refixtured), "utf8");+ resetTuningMarkCache();+ expect(validatedTuningMark("laya", "rerank", stateEnv)).toBeNull();++ // A mark is only as good as the thresholds it was measured against.+ // The on-disk mark here names the drifted spec's own hash and+ // fixture hash, so the pinned-threshold comparison is the only check+ // that can refuse it.+ const registry = decisionEvalSpecFor("rerank")!;+ const drifted: DecisionEvalSpec = { ...registry, thresholds: { min_score: 0.5 } };+ writeFileSync(+ path,+ JSON.stringify({+ ...valid,+ spec_hash: decisionEvalSpecHash(drifted),+ fixture_hash: drifted.fixture_hash,+ thresholds: registry.thresholds,+ }),+ "utf8",+ );+ resetTuningMarkCache();+ expect(validatedTuningMark("laya", "rerank", stateEnv, drifted)).toBeNull();++ // The control: a mark that matches the drifted spec on every axis -+ // including its thresholds - validates, so the refusal above is the+ // threshold comparison's and nothing else's.+ writeFileSync(+ path,+ JSON.stringify({+ ...valid,+ spec_hash: decisionEvalSpecHash(drifted),+ fixture_hash: drifted.fixture_hash,+ thresholds: drifted.thresholds,+ }),+ "utf8",+ );+ resetTuningMarkCache();+ expect(validatedTuningMark("laya", "rerank", stateEnv, drifted)).not.toBeNull();+ });++ test("fails closed on a mark keyed for another profile or use, or written by a hold", async () => {+ // A real promote mark for (laya, rerank) is on disk; every refusal+ // below is the acceptance check's, not the mere absence of a file.+ await runDecisionModelEval("rerank", {+ config: evalConfig(),+ provider: new FakeDecisionProvider({ answer: byLabelRule }),+ markSource: stateEnv,+ });+ const path = decisionModelTuningMarkPath(stateEnv, "laya", "rerank");+ const valid = JSON.parse(readFileSync(path, "utf8")) as Record<string, unknown>;+ expect(validatedTuningMark("laya", "rerank", stateEnv)).not.toBeNull();++ // The same mark dropped under another profile's path (or asked for+ // under another profile) is refused: a mark tuned for one provider+ // family says nothing about another.+ const foreignProfilePath = decisionModelTuningMarkPath(stateEnv, "openjev", "rerank");+ mkdirSync(dirname(foreignProfilePath), { recursive: true });+ writeFileSync(foreignProfilePath, JSON.stringify(valid), "utf8");+ resetTuningMarkCache();+ expect(validatedTuningMark("openjev", "rerank", stateEnv)).toBeNull();++ // ...and under another use's path: recall_inject was never measured.+ const foreignUsePath = decisionModelTuningMarkPath(stateEnv, "laya", "recall_inject");+ mkdirSync(dirname(foreignUsePath), { recursive: true });+ writeFileSync(foreignUsePath, JSON.stringify(valid), "utf8");+ resetTuningMarkCache();+ expect(validatedTuningMark("laya", "recall_inject", stateEnv)).toBeNull();++ // A hold verdict never tunes, whatever the file claims.+ writeFileSync(path, JSON.stringify({ ...valid, verdict: "hold" }), "utf8");+ resetTuningMarkCache();+ expect(validatedTuningMark("laya", "rerank", stateEnv)).toBeNull();+ });+});++describe("the eval runner writes the mark only on a promote", () => {+ test("a promote writes a validating mark", async () => {+ const result = await runDecisionModelEval("rerank", {+ config: evalConfig(),+ provider: new FakeDecisionProvider({ answer: byLabelRule }),+ markSource: stateEnv,+ });+ expect(result.verdict).toBe("promote");+ expect(result.mark_written).toBe(true);+ expect(validatedTuningMark("laya", "rerank", stateEnv)).not.toBeNull();+ });++ test("the mark records the provider, model and base-URL hash that earned it", async () => {+ await runDecisionModelEval("rerank", {+ config: evalConfig(),+ provider: new FakeDecisionProvider({ answer: byLabelRule }),+ markSource: stateEnv,+ });+ const raw = JSON.parse(+ readFileSync(decisionModelTuningMarkPath(stateEnv, "laya", "rerank"), "utf8"),+ ) as Record<string, unknown>;+ expect(raw["provider"]).toBe("compatible");+ expect(raw["model"]).toBe("fake-model-1");+ // A hash, never the URL itself.+ expect(raw["base_url_hash"]).toBe(sha256Hex("http://127.0.0.1:9"));+ expect(JSON.stringify(raw)).not.toContain("127.0.0.1");+ });++ test("a hold writes nothing", async () => {+ const result = await runDecisionModelEval("rerank", {+ config: evalConfig(),+ provider: new FakeDecisionProvider({ answer: INVERTED }),+ markSource: stateEnv,+ });+ expect(result.verdict).toBe("hold");+ expect(result.mark_written).toBe(false);+ expect(validatedTuningMark("laya", "rerank", stateEnv)).toBeNull();+ });++ test("not enough evidence writes nothing, and neither does a profileless config", async () => {+ const registry = decisionEvalSpecFor("rerank")!;+ const spec: DecisionEvalSpec = {+ ...registry,+ min_counted: registry.receipt.counted.length + 1,+ };+ const short = await runDecisionModelEval("rerank", {+ config: evalConfig(),+ provider: new FakeDecisionProvider({ answer: byLabelRule }),+ markSource: stateEnv,+ spec,+ });+ expect(short.verdict).toBe("not_enough_evidence");+ expect(short.mark_written).toBe(false);++ const profileless = await runDecisionModelEval("rerank", {+ config: evalConfig(null),+ provider: new FakeDecisionProvider({ answer: byLabelRule }),+ markSource: stateEnv,+ });+ expect(profileless.verdict).toBe("promote");+ expect(profileless.mark_written).toBe(false);+ });+});++describe("the measured gate", () => {+ /** The endpoint `evalConfig` measures on - what a mark gets bound to. */+ const ENDPOINT = {+ provider: "compatible",+ model: "fake-model-1",+ baseUrl: "http://127.0.0.1:9",+ };+ const ENV = { O2B_TEST_EVAL_MARK_KEY: "unused" };+ // Resolves to exactly the endpoint the measurement ran on (and a key,+ // since the compatible provider always needs one).+ const CONFIG = {+ decision_model_enabled: "true",+ decision_model_provider: "compatible",+ decision_model_base_url: "http://127.0.0.1:9",+ decision_model_id: "fake-model-1",+ decision_model_env_key: "O2B_TEST_EVAL_MARK_KEY",+ decision_model_threshold_profile: "laya",+ decision_model_uses: "rerank:enforce",+ };++ test("with no mark the use stays shadow exactly as today", () => {+ const cfg = resolveDecisionModelConfig({+ env: ENV,+ config: CONFIG,+ vault,+ measuredTunedMark: machineTunedMarkReader(ENDPOINT, stateEnv),+ });+ expect(cfg.status).toBe("active");+ expect(cfg.shadowOnlyUses).toEqual(["rerank"]);+ expect(cfg.uses["rerank"]).toBe("shadow");+ expect(decisionModelModeFor(cfg, "rerank")).toBe("shadow");+ });++ test("a valid mark lets the previously shadow-only use run enforce", async () => {+ await runDecisionModelEval("rerank", {+ config: evalConfig(),+ provider: new FakeDecisionProvider({ answer: byLabelRule }),+ markSource: stateEnv,+ });+ const reader = machineTunedMarkReader(ENDPOINT, stateEnv);+ const cfg = resolveDecisionModelConfig({+ env: ENV,+ config: CONFIG,+ vault,+ measuredTunedMark: reader,+ });+ expect(cfg.shadowOnlyUses).toEqual([]);+ expect(cfg.uses["rerank"]).toBe("enforce");+ expect(decisionModelModeFor(cfg, "rerank")).toBe("enforce");+ // Only the marked use is measured: an untuned use without a mark+ // stays shadow.+ const both = resolveDecisionModelConfig({+ env: ENV,+ config: { ...CONFIG, decision_model_uses: "rerank:enforce,dedup:enforce" },+ vault,+ measuredTunedMark: reader,+ });+ expect(both.shadowOnlyUses).toEqual(["dedup"]);+ });++ test("a mark measured on one endpoint arms enforce only for that provider, model and base URL", async () => {+ // Measure with one model, then resolve the config as if the operator+ // had switched the pinned model, the base URL, or the whole provider:+ // none of those may inherit the mark, and switching back re-arms it.+ // The default reader path is the point: config.ts must bind the+ // reader to the endpoint it just resolved.+ await runDecisionModelEval("rerank", {+ config: evalConfig(),+ provider: new FakeDecisionProvider({ answer: byLabelRule }),+ markSource: stateEnv,+ });+ const previous = process.env["XDG_STATE_HOME"];+ process.env["XDG_STATE_HOME"] = stateEnv.env["XDG_STATE_HOME"]!;+ try {+ const resolve = (config: Record<string, string>) =>+ resolveDecisionModelConfig({ env: ENV, config, vault });+ expect(resolve(CONFIG).uses["rerank"]).toBe("enforce");++ // A model that was never measured runs shadow.+ expect(resolve({ ...CONFIG, decision_model_id: "tiny-0.5b-q2" }).uses["rerank"]).toBe(+ "shadow",+ );+ // So does the same model at another base URL - a different deployment.+ expect(+ resolve({ ...CONFIG, decision_model_base_url: "http://127.0.0.1:10" }).uses["rerank"],+ ).toBe("shadow");+ // And another provider id is a different decision surface outright.+ expect(resolve({ ...CONFIG, decision_model_provider: "laya" }).uses["rerank"]).toBe("shadow");++ // Switching back to the measured endpoint re-arms enforce.+ expect(resolve(CONFIG).uses["rerank"]).toBe("enforce");+ } finally {+ if (previous === undefined) delete process.env["XDG_STATE_HOME"];+ else process.env["XDG_STATE_HOME"] = previous;+ }+ });++ test("a mark written before the endpoint binding fails closed to shadow", async () => {+ // A pre-binding mark carries no provider/model/base-URL hash: it+ // cannot prove which endpoint earned it, so it is no mark at all.+ await runDecisionModelEval("rerank", {+ config: evalConfig(),+ provider: new FakeDecisionProvider({ answer: byLabelRule }),+ markSource: stateEnv,+ });+ const path = decisionModelTuningMarkPath(stateEnv, "laya", "rerank");+ const legacy = JSON.parse(readFileSync(path, "utf8")) as Record<string, unknown>;+ delete legacy["provider"];+ delete legacy["model"];+ delete legacy["base_url_hash"];+ writeFileSync(path, JSON.stringify(legacy), "utf8");+ resetTuningMarkCache();+ expect(validatedTuningMark("laya", "rerank", stateEnv)).toBeNull();+ const cfg = resolveDecisionModelConfig({+ env: ENV,+ config: CONFIG,+ vault,+ measuredTunedMark: machineTunedMarkReader(ENDPOINT, stateEnv),+ });+ expect(cfg.uses["rerank"]).toBe("shadow");+ });++ test("a completed hold retracts the mark; a refused run keeps it", async () => {+ const run = (provider: FakeDecisionProvider, spec?: DecisionEvalSpec) =>+ runDecisionModelEval("rerank", {+ config: evalConfig(),+ provider,+ markSource: stateEnv,+ ...(spec !== undefined ? { spec } : {}),+ });+ const reader = machineTunedMarkReader(ENDPOINT, stateEnv);+ const gated = () =>+ resolveDecisionModelConfig({ env: ENV, config: CONFIG, vault, measuredTunedMark: reader });++ // Run 1 promotes: the gate arms enforce.+ const first = await run(new FakeDecisionProvider({ answer: byLabelRule }));+ expect(first.mark_written).toBe(true);+ expect(gated().uses["rerank"]).toBe("enforce");++ // Run 2 holds: the mark is gone and the gate falls back to shadow -+ // the run says so, instead of printing that no mark was written.+ const second = await run(new FakeDecisionProvider({ answer: INVERTED }));+ expect(second.verdict).toBe("hold");+ expect(second.mark_retracted).toBe(true);+ expect(second.mark_note).toMatch(/retracted/);+ expect(gated().uses["rerank"]).toBe("shadow");++ // Run 3 promotes again: re-arming after a retraction works.+ const third = await run(new FakeDecisionProvider({ answer: byLabelRule }));+ expect(third.mark_written).toBe(true);+ expect(gated().uses["rerank"]).toBe("enforce");++ // Run 4 is refused before any measurement: the mark survives.+ const registry = decisionEvalSpecFor("rerank")!;+ const tampered: DecisionEvalSpec = {+ ...registry,+ receipt: { dev: registry.receipt.dev, counted: registry.receipt.counted.slice(1) },+ };+ await expect(run(new FakeDecisionProvider({ answer: byLabelRule }), tampered)).rejects.toThrow(+ /preregistration/,+ );+ expect(gated().uses["rerank"]).toBe("enforce");+ });++ test("a tampered mark fails closed to shadow", async () => {+ await runDecisionModelEval("rerank", {+ config: evalConfig(),+ provider: new FakeDecisionProvider({ answer: byLabelRule }),+ markSource: stateEnv,+ });+ const path = decisionModelTuningMarkPath(stateEnv, "laya", "rerank");+ const valid = JSON.parse(readFileSync(path, "utf8")) as Record<string, unknown>;+ writeFileSync(path, JSON.stringify({ ...valid, spec_hash: "0".repeat(64) }), "utf8");+ resetTuningMarkCache();+ const cfg = resolveDecisionModelConfig({+ env: ENV,+ config: CONFIG,+ vault,+ measuredTunedMark: machineTunedMarkReader(ENDPOINT, stateEnv),+ });+ expect(cfg.shadowOnlyUses).toEqual(["rerank"]);+ expect(cfg.uses["rerank"]).toBe("shadow");+ });++ test("the default reader is the machine-side one", async () => {+ const previous = process.env["XDG_STATE_HOME"];+ process.env["XDG_STATE_HOME"] = stateEnv.env["XDG_STATE_HOME"]!;+ try {+ const before = resolveDecisionModelConfig({ env: ENV, config: CONFIG, vault });+ expect(before.shadowOnlyUses).toEqual(["rerank"]);+ await runDecisionModelEval("rerank", {+ config: evalConfig(),+ provider: new FakeDecisionProvider({ answer: byLabelRule }),+ markSource: stateEnv,+ });+ resetTuningMarkCache();+ const after = resolveDecisionModelConfig({ env: ENV, config: CONFIG, vault });+ expect(after.shadowOnlyUses).toEqual([]);+ expect(after.uses["rerank"]).toBe("enforce");+ // An explicit null reader is today's hand-edit behavior.+ const disabled = resolveDecisionModelConfig({+ env: ENV,+ config: CONFIG,+ vault,+ measuredTunedMark: null,+ });+ expect(disabled.shadowOnlyUses).toEqual(["rerank"]);+ } finally {+ if (previous === undefined) delete process.env["XDG_STATE_HOME"];+ else process.env["XDG_STATE_HOME"] = previous;+ }+ });++ test("the uncalibrated-provider refusal stands even with a valid mark", async () => {+ await runDecisionModelEval("rerank", {+ config: evalConfig(),+ provider: new FakeDecisionProvider({ answer: byLabelRule }),+ markSource: stateEnv,+ });+ const cfg = resolveDecisionModelConfig({+ env: ENV,+ config: {+ decision_model_enabled: "true",+ decision_model_provider: "llm-emulation",+ decision_model_base_url: "http://127.0.0.1:9/v1",+ decision_model_id: "fake-chat-1",+ decision_model_env_key: "O2B_TEST_EVAL_MARK_KEY",+ decision_model_uses: "rerank:enforce",+ decision_model_threshold_profile: "laya",+ },+ vault,+ measuredTunedMark: machineTunedMarkReader(ENDPOINT, stateEnv),+ });+ expect(cfg.status).toBe("invalid");+ expect(cfg.errors.join(" ")).toContain("calibrated");+ });+});diff --git a/tests/core/decision-model/eval-spec.test.ts b/tests/core/decision-model/eval-spec.test.tsnew file mode 100644index 00000000..9c5722a5--- /dev/null+++ b/tests/core/decision-model/eval-spec.test.ts@@ -0,0 +1,143 @@+/**+ * The preregistered eval spec registry (cycle 20261020, card t_4e1681b3,+ * task C1).+ *+ * A spec may only be called preregistered when it names everything the+ * measured decision needs: the fixture reference and its content hash,+ * the seed, the split rule and the frozen membership receipt, the metric,+ * the ceiling, the minimum counted n, and the exact threshold values the+ * use reads when it enforces. A spec missing any element is a+ * construction error, and the committed fixtures must still match their+ * frozen receipts and content hashes.+ */++import { describe, expect, test } from "bun:test";++import {+ DECISION_EVAL_DEV_FRACTION,+ DECISION_EVAL_METRIC,+ DECISION_EVAL_SPECS,+ DECISION_EVAL_SPLIT_RULE,+ decisionEvalSpecHash,+ decisionEvalSpecFor,+ validateDecisionEvalSpec,+ type DecisionEvalSpec,+} from "../../../src/core/decision-model/eval-spec.ts";+import {+ hashOrderSplit,+ loadDecisionEvalFixture,+} from "../../../src/core/decision-model/eval/take.ts";+import {+ RECALL_INJECT_ANY_MIN,+ RECALL_INJECT_NOTE_MIN,+} from "../../../src/core/decision-model/questions.ts";++function completeSpec(): DecisionEvalSpec {+ return {+ version: 1,+ use: "rerank",+ fixture: "tests/fixtures/decision-model/rerank-take.json",+ seed: "cycle-20261020",+ split: { rule: DECISION_EVAL_SPLIT_RULE, dev_fraction: DECISION_EVAL_DEV_FRACTION },+ receipt: { dev: ["rk-002"], counted: ["rk-001", "rk-003"] },+ fixture_hash: "a".repeat(64),+ metric: DECISION_EVAL_METRIC,+ ceiling: 0.05,+ min_counted: 2,+ thresholds: {},+ };+}++describe("validateDecisionEvalSpec", () => {+ test("a complete spec validates", () => {+ expect(() => validateDecisionEvalSpec(completeSpec())).not.toThrow();+ });++ const cases: ReadonlyArray<readonly [string, (s: DecisionEvalSpec) => unknown]> = [+ ["version", (s) => ({ ...s, version: 0 })],+ ["use", (s) => ({ ...s, use: "not-a-use" })],+ ["fixture", (s) => ({ ...s, fixture: "" })],+ ["seed", (s) => ({ ...s, seed: "" })],+ ["split rule", (s) => ({ ...s, split: { rule: "alternation", dev_fraction: 0.3 } })],+ [+ "dev fraction",+ (s) => ({ ...s, split: { rule: DECISION_EVAL_SPLIT_RULE, dev_fraction: 0.5 } }),+ ],+ ["receipt", (s) => ({ ...s, receipt: { dev: [], counted: [] } })],+ ["receipt overlap", (s) => ({ ...s, receipt: { dev: ["a"], counted: ["a"] } })],+ ["fixture hash", (s) => ({ ...s, fixture_hash: "xyz" })],+ ["metric", (s) => ({ ...s, metric: "vibes" })],+ ["ceiling", (s) => ({ ...s, ceiling: 1.5 })],+ ["minimum counted n", (s) => ({ ...s, min_counted: 0 })],+ ["thresholds", (s) => ({ ...s, thresholds: { note_min: Number.NaN } })],+ ];+ for (const [name, break_] of cases) {+ test(`a spec missing or breaking ${name} is a construction error`, () => {+ const broken = break_(completeSpec()) as DecisionEvalSpec;+ expect(() => validateDecisionEvalSpec(broken)).toThrow(new RegExp(name.split(" ")[0]!, "i"));+ });+ }+});++describe("decisionEvalSpecHash", () => {+ test("is stable for the same spec and changes when any registered element moves", () => {+ const spec = completeSpec();+ const hash = decisionEvalSpecHash(spec);+ expect(hash).toMatch(/^[0-9a-f]{64}$/);+ expect(decisionEvalSpecHash(completeSpec())).toBe(hash);+ const mutations: ReadonlyArray<(s: DecisionEvalSpec) => DecisionEvalSpec> = [+ (s) => ({ ...s, seed: "other" }),+ (s) => ({ ...s, ceiling: 0.06 }),+ (s) => ({ ...s, min_counted: s.min_counted + 1 }),+ (s) => ({ ...s, receipt: { dev: ["rk-009"], counted: s.receipt.counted } }),+ (s) => ({ ...s, fixture_hash: "b".repeat(64) }),+ (s) => ({ ...s, thresholds: { note_min: 0.2 } }),+ (s) => ({ ...s, version: 2 }),+ ];+ for (const mutate of mutations) {+ expect(decisionEvalSpecHash(mutate(spec))).not.toBe(hash);+ }+ });+});++describe("the committed registry", () => {+ test("carries a spec for rerank and recall_inject, each complete", () => {+ for (const use of ["rerank", "recall_inject"] as const) {+ const spec = decisionEvalSpecFor(use);+ expect(spec).not.toBeNull();+ expect(() => validateDecisionEvalSpec(spec!)).not.toThrow();+ }+ });++ test("holds no spec for extract_prefilter, whose zero-regret loop is the report path", () => {+ expect(decisionEvalSpecFor("extract_prefilter")).toBeNull();+ });++ test("each spec's fixture still matches its frozen content hash and receipt", () => {+ for (const spec of Object.values(DECISION_EVAL_SPECS)) {+ const { fixture, contentHash } = loadDecisionEvalFixture(spec.fixture, spec.use);+ const ids = fixture.items.map((item) => item.id);+ const split = hashOrderSplit(spec.seed, ids);+ expect(contentHash).toBe(spec.fixture_hash);+ expect(split.dev).toEqual([...spec.receipt.dev].toSorted());+ expect(split.counted).toEqual([...spec.receipt.counted].toSorted());+ }+ });++ test("each spec's counted take meets its own minimum counted n", () => {+ for (const spec of Object.values(DECISION_EVAL_SPECS)) {+ expect(spec.receipt.counted.length).toBeGreaterThanOrEqual(spec.min_counted);+ }+ });++ test("the recall_inject spec pins the enforce thresholds it is measured against", () => {+ const spec = decisionEvalSpecFor("recall_inject")!;+ expect(spec.thresholds["any_min"]).toBe(RECALL_INJECT_ANY_MIN);+ expect(spec.thresholds["note_min"]).toBe(RECALL_INJECT_NOTE_MIN);+ });++ test("the rerank spec pins the empty threshold set the reorder actually reads", () => {+ const spec = decisionEvalSpecFor("rerank")!;+ expect(spec.thresholds).toEqual({});+ });+});diff --git a/tests/core/decision-model/eval-surfaces.test.ts b/tests/core/decision-model/eval-surfaces.test.tsnew file mode 100644index 00000000..eee4845e--- /dev/null+++ b/tests/core/decision-model/eval-surfaces.test.ts@@ -0,0 +1,304 @@+/**+ * The eval surfaces (cycle 20261020, card t_4e1681b3, task C4): the+ * measured tuning state in `o2b decision-model check`, the eval section+ * of `report`, and the prose/JSON rendering the CLI shows for both.+ *+ * The check is where an untuned use's shadow hold is explained; with a+ * valid machine-side mark the same line names the spec hash the mark was+ * accepted under, and a tampered or stale mark reads as untuned again -+ * the fail-closed direction, visible on the surface.+ */++import { afterEach, beforeEach, describe, expect, test } from "bun:test";+import { mkdirSync, mkdtempSync, readFileSync, rmSync, writeFileSync } from "node:fs";+import { tmpdir } from "node:os";+import { join } from "node:path";++import type { DecisionRequest } from "../../../src/core/decision-model/contract.ts";+import {+ buildDecisionModelCheck,+ buildDecisionModelReport,+ renderDecisionModelCheck,+ renderDecisionModelReport,+} from "../../../src/core/decision-model/diagnostics.ts";+import {+ decisionEvalSpecFor,+ decisionEvalSpecHash,+} from "../../../src/core/decision-model/eval-spec.ts";+import { runDecisionModelEval } from "../../../src/core/decision-model/eval/grade.ts";+import {+ decisionModelTuningMarkPath,+ resetTuningMarkCache,+} from "../../../src/core/decision-model/eval/mark.ts";+import type { ResolvedDecisionModelConfig } from "../../../src/core/decision-model/config.ts";+import type { PlatformDirsEnv } from "../../../src/core/platform-dirs.ts";+import { appendContinuityRecord } from "../../../src/core/brain/continuity/store.ts";+import { resetDecisionSpendCache } from "../../../src/core/decision-model/record.ts";+import { FakeDecisionProvider } from "../../helpers/fake-decision-provider.ts";++let tmp: string;+let vault: string;+let stateEnv: PlatformDirsEnv;++beforeEach(() => {+ tmp = mkdtempSync(join(tmpdir(), "osb-dm-eval-surface-"));+ vault = join(tmp, "vault");+ mkdirSync(join(vault, "Brain"), { recursive: true });+ stateEnv = { platform: "linux", home: tmp, env: { XDG_STATE_HOME: join(tmp, "state") } };+ resetTuningMarkCache();+ resetDecisionSpendCache();+});+afterEach(() => {+ rmSync(tmp, { recursive: true, force: true });+ resetTuningMarkCache();+ resetDecisionSpendCache();+});++/** Answers by the fixtures' labeling rule: an on-topic passage helps. */+function byLabelRule(id: string, req: DecisionRequest): number {+ const state = req.state as {+ query?: string;+ prompt?: string;+ passages?: Record<string, string>;+ notes?: Record<string, string>;+ };+ const subject = /the (.+)\?/.exec(state.query ?? state.prompt ?? "")![1]!;+ const key = id.startsWith("rel_") ? `P${id.slice(4)}` : null;+ if (key === null) return 0.5;+ const text = state.passages?.[key] ?? "";+ return text.includes(subject) ? 0.99 : 0.01;+}++function evalConfig(): ResolvedDecisionModelConfig {+ const uses = {+ rerank: "shadow",+ answerable: "off",+ skills: "off",+ extract_prefilter: "off",+ dedup: "off",+ tension: "off",+ labels: "off",+ recall_inject: "off",+ } as ResolvedDecisionModelConfig["uses"];+ return {+ status: "active",+ errors: [],+ notes: [],+ enabled: true,+ provider: "compatible",+ adapter: "systemone",+ baseUrl: "http://127.0.0.1:9",+ model: "fake-model-1",+ envKey: "FAKE_DECISION_KEY_UNUSED",+ keyPresent: true,+ allowInsecureHttp: false,+ timeoutMs: 3000,+ hookBudgetMs: 700,+ maxStateTokens: 32_000,+ uses,+ configuredUses: uses,+ dailyCostGateUsd: 0.5,+ inputPriceUsdPerMtok: 0.042,+ allowUncalibrated: false,+ calibrated: true,+ thresholdProfile: "laya",+ shadowOnlyUses: ["rerank"],+ processor: null,+ vault,+ };+}++const CHECK_CONFIG = {+ decision_model_enabled: "true",+ decision_model_provider: "compatible",+ decision_model_base_url: "http://127.0.0.1:9",+ decision_model_id: "fake-model-1",+ decision_model_threshold_profile: "laya",+ decision_model_uses: "rerank:shadow",+} as const;++function checkWith(markSource: PlatformDirsEnv | null) {+ return buildDecisionModelCheck({ config: { ...CHECK_CONFIG }, vault, markSource });+}++describe("the check's measured tuning state", () => {+ test("no mark reads as untuned, on the record and in the prose", async () => {+ const report = await checkWith(stateEnv);+ expect(report.tuning).toMatchObject({ profile: "laya", state: "untuned", marked_uses: [] });+ const text = renderDecisionModelCheck(report);+ expect(text).toContain("tuning: profile 'laya' is untuned");+ expect(text).toContain("eval run");+ });++ test("a valid mark reads as measured under its spec hash, naming the uses", async () => {+ await runDecisionModelEval("rerank", {+ config: evalConfig(),+ provider: new FakeDecisionProvider({ answer: byLabelRule }),+ markSource: stateEnv,+ });+ const report = await checkWith(stateEnv);+ const spec = decisionEvalSpecFor("rerank")!;+ expect(report.tuning.state).toBe("measured");+ expect(report.tuning.marked_uses).toEqual([+ { use: "rerank", spec_hash: decisionEvalSpecHash(spec) },+ ]);+ const text = renderDecisionModelCheck(report);+ expect(text).toContain(+ `tuning: profile 'laya' measured under spec hash ${decisionEvalSpecHash(spec).slice(0, 12)}… (rerank)`,+ );+ });++ test("a mark measured on model A reads as measured elsewhere, not measured, on model B", async () => {+ // The mark is bound to the endpoint that earned it (provider, model,+ // base-url hash). The gate reader refuses it for another endpoint and+ // holds the use shadow - so the check must not claim measured-enforce+ // here either: it names the mark and why it does not arm.+ await runDecisionModelEval("rerank", {+ config: evalConfig(),+ provider: new FakeDecisionProvider({ answer: byLabelRule }),+ markSource: stateEnv,+ });+ const spec = decisionEvalSpecFor("rerank")!;+ const elsewhere = await buildDecisionModelCheck({+ config: { ...CHECK_CONFIG, decision_model_id: "fake-model-2" },+ vault,+ markSource: stateEnv,+ });+ expect(elsewhere.tuning.state).toBe("measured_elsewhere");+ expect(elsewhere.tuning.marked_uses).toEqual([]);+ expect(elsewhere.tuning.elsewhere_uses).toEqual([+ { use: "rerank", spec_hash: decisionEvalSpecHash(spec) },+ ]);+ const text = renderDecisionModelCheck(elsewhere);+ expect(text).toContain("on another endpoint (provider, model or base-url mismatch)");+ expect(text).toContain("enforce holds as shadow");+ // The same holds when only the base URL moved and the model stayed.+ const movedUrl = await buildDecisionModelCheck({+ config: { ...CHECK_CONFIG, decision_model_base_url: "http://127.0.0.1:10" },+ vault,+ markSource: stateEnv,+ });+ expect(movedUrl.tuning.state).toBe("measured_elsewhere");+ expect(renderDecisionModelCheck(movedUrl)).toContain("on another endpoint");+ });++ test("a tampered mark fails closed to untuned on the surface", async () => {+ await runDecisionModelEval("rerank", {+ config: evalConfig(),+ provider: new FakeDecisionProvider({ answer: byLabelRule }),+ markSource: stateEnv,+ });+ const path = decisionModelTuningMarkPath(stateEnv, "laya", "rerank");+ const valid = JSON.parse(readFileSync(path, "utf8")) as Record<string, unknown>;+ writeFileSync(path, JSON.stringify({ ...valid, fixture_hash: "0".repeat(64) }), "utf8");+ resetTuningMarkCache();+ const report = await checkWith(stateEnv);+ expect(report.tuning.state).toBe("untuned");+ });++ test("the baseline profile says baseline; no profile says none", async () => {+ // A hosted Jev-family route carries the baseline profile by preset.+ const baseline = await buildDecisionModelCheck({+ config: {+ decision_model_enabled: "true",+ decision_model_provider: "vercel",+ decision_model_uses: "rerank:shadow",+ },+ vault,+ markSource: stateEnv,+ env: { AI_GATEWAY_API_KEY: "unused" } as unknown as NodeJS.ProcessEnv,+ });+ expect(baseline.tuning).toMatchObject({ profile: "jev-1.13", state: "baseline" });+ expect(renderDecisionModelCheck(baseline)).toContain("is the baseline");++ const noProfile = await buildDecisionModelCheck({+ config: {+ decision_model_enabled: "true",+ decision_model_provider: "compatible",+ decision_model_base_url: "http://127.0.0.1:9",+ decision_model_id: "fake-model-1",+ decision_model_uses: "rerank:shadow",+ },+ vault,+ markSource: stateEnv,+ });+ expect(noProfile.tuning).toMatchObject({ profile: null, state: "none", marked_uses: [] });+ expect(renderDecisionModelCheck(noProfile)).toContain("no threshold profile resolves");+ });+});++describe("the check's cached eval grades", () => {+ test("lists cached grade records per use and skips malformed ones by count", async () => {+ await runDecisionModelEval("rerank", {+ config: evalConfig(),+ provider: new FakeDecisionProvider({ answer: byLabelRule }),+ markSource: stateEnv,+ });+ appendContinuityRecord(vault, {+ kind: "decision_model_eval_grade",+ createdAt: new Date().toISOString(),+ sourceRefs: [],+ payload: { use: "rerank", verdict: "promote" },+ });+ const report = await checkWith(stateEnv);+ expect(report.eval_grades.total).toBe(1);+ expect(report.eval_grades.skipped).toHaveLength(1);+ expect(report.eval_grades.uses[0]).toMatchObject({+ use: "rerank",+ runs: 1,+ last_verdict: "promote",+ });+ const text = renderDecisionModelCheck(report);+ expect(text).toContain("eval grades: 1 record(s)");+ expect(text).toContain("rerank: 1 run(s), last promote");+ expect(text).toContain("1 skipped");+ });++ test("no grades at all reads as none cached", async () => {+ const report = await checkWith(stateEnv);+ expect(report.eval_grades.total).toBe(0);+ expect(renderDecisionModelCheck(report)).toContain("eval grades: none cached");+ });+});++describe("the report's eval section", () => {+ test("carries the cached grades, oldest first, and skips malformed by note", async () => {+ await runDecisionModelEval("rerank", {+ config: evalConfig(),+ provider: new FakeDecisionProvider({ answer: byLabelRule }),+ markSource: stateEnv,+ });+ await runDecisionModelEval("rerank", {+ config: evalConfig(),+ provider: new FakeDecisionProvider({ answer: () => 0.01 }),+ markSource: stateEnv,+ });+ appendContinuityRecord(vault, {+ kind: "decision_model_eval_grade",+ createdAt: new Date().toISOString(),+ sourceRefs: [],+ payload: { verdict: "promote" },+ });+ const report = buildDecisionModelReport(vault);+ expect(report.eval).toBeDefined();+ expect(report.eval!.grades).toHaveLength(2);+ expect(report.eval!.grades[0]!.verdict).toBe("promote");+ expect(report.eval!.grades[1]!.verdict).toBe("hold");+ expect(report.eval!.skipped).toHaveLength(1);+ expect(report.eval!.skipped[0]).toMatch(/decision_model_eval_grade record .+ skipped:/);++ const text = renderDecisionModelReport(report);+ expect(text).toContain("eval grades: 2 record(s)");+ expect(text).toContain("rerank (laya) promote: counted error 0.000 over n=30");+ // A constant answer leaves the input order in place: the counted+ // error is exactly the input-order baseline's, and the verdict holds.+ expect(text).toContain("rerank (laya) hold: counted error 0.733 over n=30");+ expect(text).toContain("skipped: decision_model_eval_grade record");+ });++ test("a vault with no grades renders no eval section", () => {+ const report = buildDecisionModelReport(vault);+ expect(report.eval).toBeUndefined();+ expect(renderDecisionModelReport(report)).not.toContain("eval grades:");+ });+});diff --git a/tests/core/decision-model/eval-take.test.ts b/tests/core/decision-model/eval-take.test.tsnew file mode 100644index 00000000..2d0ffdf7--- /dev/null+++ b/tests/core/decision-model/eval-take.test.ts@@ -0,0 +1,372 @@+/**+ * The seeded take and the hash-order dev/counted split (cycle 20261020,+ * card t_4e1681b3, task C1).+ *+ * The split rule is the preregistration contract: `sha256Hex(seed + ":" + id)`+ * ranks the take ids, the first `ceil(0.3 n)` are dev, the rest counted.+ * The tests below re-derive the ranking from `sha256Hex` directly so a+ * broken implementation cannot pass by agreeing with itself.+ */++import { describe, expect, test } from "bun:test";+import { mkdirSync, mkdtempSync, rmSync, writeFileSync } from "node:fs";+import { tmpdir } from "node:os";+import { join, resolve } from "node:path";++import { sha256Hex } from "../../../src/core/integrity/digest.ts";+import {+ hashOrderSplit,+ parseDecisionEvalFixture,+ loadDecisionEvalFixture,+ resolveEvalFixturePath,+ verifyEvalTake,+} from "../../../src/core/decision-model/eval/take.ts";+import {+ DECISION_EVAL_DEV_FRACTION,+ type DecisionEvalSpec,+} from "../../../src/core/decision-model/eval-spec.ts";++const IDS = ["rk-001", "rk-002", "rk-003", "rk-004", "rk-005", "rk-006", "rk-007", "rk-008"];++function expectedDevFirst(seed: string, ids: ReadonlyArray<string>): string[] {+ return ids+ .map((id) => ({ id, h: sha256Hex(`${seed}:${id}`) }))+ .toSorted((a, b) => (a.h < b.h ? -1 : a.h > b.h ? 1 : a.id.localeCompare(b.id)))+ .slice(0, Math.ceil(ids.length * DECISION_EVAL_DEV_FRACTION))+ .map((e) => e.id)+ .toSorted();+}++describe("hashOrderSplit", () => {+ test("is deterministic and follows the sha256Hex(seed:id) ranking", () => {+ const seed = "cycle-20261020";+ const a = hashOrderSplit(seed, IDS);+ const b = hashOrderSplit(seed, IDS);+ expect(a).toEqual(b);+ expect(a.dev).toEqual(expectedDevFirst(seed, IDS));+ expect(a.dev).toHaveLength(Math.ceil(IDS.length * 0.3));+ expect(a.counted).toHaveLength(IDS.length - Math.ceil(IDS.length * 0.3));+ });++ test("is stable under input reorder and returns lexicographically sorted lists", () => {+ const seed = "cycle-20261020";+ const forward = hashOrderSplit(seed, IDS);+ const reversed = hashOrderSplit(seed, [...IDS].reverse());+ expect(reversed.dev).toEqual(forward.dev);+ expect(reversed.counted).toEqual(forward.counted);+ for (const list of [forward.dev, forward.counted]) {+ expect([...list].toSorted()).toEqual([...list]);+ }+ });++ test("dev and counted are disjoint and their union is the take", () => {+ const split = hashOrderSplit("another-seed", IDS);+ const union = [...split.dev, ...split.counted].toSorted();+ expect(union).toEqual([...IDS].toSorted());+ expect(split.dev.filter((id) => split.counted.includes(id))).toEqual([]);+ });++ test("a different seed moves the boundary", () => {+ expect(hashOrderSplit("seed-a", IDS)).not.toEqual(hashOrderSplit("seed-b", IDS));+ });++ test("empty and single-id takes split sanely", () => {+ expect(hashOrderSplit("s", [])).toEqual({ dev: [], counted: [] });+ expect(hashOrderSplit("s", ["only"])).toEqual({ dev: ["only"], counted: [] });+ });+});++describe("parseDecisionEvalFixture", () => {+ const rerankFixture = {+ use: "rerank",+ items: [+ {+ id: "rk-001",+ query: "How do I look after the bonsai?",+ candidates: [+ {+ title: "Potting diary",+ text: "The bonsai fig drops leaves when moved.",+ relevant: true,+ },+ {+ title: "Cluster notes",+ text: "The kubernetes cluster autoscaler adds nodes.",+ relevant: false,+ },+ ],+ },+ ],+ };++ test("accepts a well-formed rerank fixture", () => {+ const fixture = parseDecisionEvalFixture(rerankFixture, "rerank");+ expect(fixture.items).toHaveLength(1);+ expect(fixture.items[0]!.kind).toBe("rerank");+ });++ test("rejects a fixture whose use does not match the spec's use", () => {+ expect(() => parseDecisionEvalFixture(rerankFixture, "recall_inject")).toThrow(/use/);+ });++ test("rejects duplicate item ids, empty candidates and gold-less items", () => {+ const dup = {+ use: "rerank",+ items: [rerankFixture.items[0], rerankFixture.items[0]],+ };+ expect(() => parseDecisionEvalFixture(dup, "rerank")).toThrow(/rk-001/);+ expect(() =>+ parseDecisionEvalFixture(+ { use: "rerank", items: [{ id: "rk-002", query: "q", candidates: [] }] },+ "rerank",+ ),+ ).toThrow(/rk-002/);+ expect(() =>+ parseDecisionEvalFixture(+ {+ use: "rerank",+ items: [+ {+ id: "rk-003",+ query: "q",+ candidates: [+ { title: "t", text: "x", relevant: false },+ { title: "u", text: "y", relevant: false },+ ],+ },+ ],+ },+ "rerank",+ ),+ ).toThrow(/rk-003/);+ });++ test("rejects non-boolean gold labels and blank text", () => {+ expect(() =>+ parseDecisionEvalFixture(+ {+ use: "rerank",+ items: [+ {+ id: "rk-004",+ query: "q",+ candidates: [+ { title: "t", text: "x", relevant: "yes" },+ { title: "u", text: "y", relevant: false },+ ],+ },+ ],+ },+ "rerank",+ ),+ ).toThrow(/rk-004/);+ });++ test("accepts a well-formed recall_inject fixture and rejects a gold-less one", () => {+ const good = {+ use: "recall_inject",+ items: [+ {+ id: "ri-001",+ prompt: "What should I know about the glacier?",+ notes: [+ { title: "Field survey", text: "The glacier terminus retreated.", useful: true },+ { title: "Baking log", text: "The sourdough starter doubles.", useful: false },+ ],+ },+ ],+ };+ expect(parseDecisionEvalFixture(good, "recall_inject").items).toHaveLength(1);+ expect(() =>+ parseDecisionEvalFixture(+ {+ use: "recall_inject",+ items: [+ {+ id: "ri-002",+ prompt: "p",+ notes: [+ { title: "a", text: "x", useful: false },+ { title: "b", text: "y", useful: false },+ ],+ },+ ],+ },+ "recall_inject",+ ),+ ).toThrow(/ri-002/);+ });+});++describe("committed take fixtures", () => {+ test("load from their repo-relative spec reference", () => {+ const loaded = loadDecisionEvalFixture(+ "tests/fixtures/decision-model/rerank-take.json",+ "rerank",+ );+ expect(loaded.fixture.items).toHaveLength(43);+ expect(loaded.contentHash).toMatch(/^[0-9a-f]{64}$/);+ });++ test("an absolute path loads as is; a wrong use is refused", () => {+ const abs = join(+ import.meta.dir,+ "..",+ "..",+ "..",+ "tests/fixtures/decision-model/rerank-take.json",+ );+ expect(loadDecisionEvalFixture(abs, "rerank").fixture.items).toHaveLength(43);+ expect(() =>+ loadDecisionEvalFixture("tests/fixtures/decision-model/rerank-take.json", "dedup"),+ ).toThrow(/use/);+ });++ test("resolution stays package-rooted: the take loads from a bare working directory", () => {+ // The installed package has no caller working directory to lean on:+ // the repo-relative reference must resolve against the package root,+ // wherever the process happens to run - there is no working-directory+ // fallback, so a bare reference resolves there or raises a named+ // read error, never content from cwd.+ const repoRoot = resolve(join(import.meta.dir, "..", "..", ".."));+ const previous = process.cwd();+ const bare = mkdtempSync(join(tmpdir(), "osb-dm-take-bare-"));+ process.chdir(bare);+ try {+ const ref = "tests/fixtures/decision-model/rerank-take.json";+ expect(resolveEvalFixturePath(ref).startsWith(repoRoot)).toBe(true);+ const loaded = loadDecisionEvalFixture(ref, "rerank");+ expect(loaded.fixture.items).toHaveLength(43);+ } finally {+ process.chdir(previous);+ rmSync(bare, { recursive: true, force: true });+ }+ });++ test("a look-alike file in the working directory is never hashed", () => {+ // The installed-package failure mode: a cwd-relative fallback would+ // read whatever sits at ./tests/fixtures/... and hash it into a+ // preregistration claim. A repo-relative reference resolves against+ // the package root or nowhere; a look-alike only the working+ // directory holds is a named read error, never content.+ const repoRoot = resolve(join(import.meta.dir, "..", "..", ".."));+ const previous = process.cwd();+ const decoy = mkdtempSync(join(tmpdir(), "osb-dm-take-decoy-"));+ mkdirSync(join(decoy, "tests", "fixtures", "decision-model"), { recursive: true });+ const ref = "tests/fixtures/decision-model/lookalike-take.json";+ writeFileSync(join(decoy, ref), JSON.stringify({ use: "rerank", items: [] }), "utf8");+ process.chdir(decoy);+ try {+ const resolved = resolveEvalFixturePath(ref);+ expect(resolved.startsWith(decoy)).toBe(false);+ expect(resolved).toBe(join(repoRoot, ref));+ expect(() => loadDecisionEvalFixture(ref, "rerank")).toThrow(/cannot read/);+ } finally {+ process.chdir(previous);+ rmSync(decoy, { recursive: true, force: true });+ }+ });+});++describe("verifyEvalTake", () => {+ const spec: DecisionEvalSpec = {+ version: 1,+ use: "rerank",+ fixture: "tests/fixtures/decision-model/rerank-take.json",+ seed: "cycle-20261020",+ split: { rule: "hash-order-30-70", dev_fraction: 0.3 },+ receipt: { dev: ["rk-002"], counted: ["rk-001"] },+ fixture_hash: "0".repeat(64),+ metric: "counted_error_rate",+ ceiling: 0.05,+ min_counted: 1,+ thresholds: {},+ };++ test("a hand-built two-item spec verifies when the receipt matches the derivation", () => {+ const doc = {+ use: "rerank",+ items: [+ {+ id: "rk-001",+ query: "q1",+ candidates: [+ { title: "t", text: "bonsai drops leaves", relevant: false },+ { title: "u", text: "kubernetes autoscaler", relevant: true },+ ],+ },+ {+ id: "rk-002",+ query: "q2",+ candidates: [+ { title: "t", text: "kubernetes autoscaler", relevant: true },+ { title: "u", text: "bonsai drops leaves", relevant: false },+ ],+ },+ ],+ };+ const fixture = parseDecisionEvalFixture(doc, "rerank");+ const split = hashOrderSplit(spec.seed, ["rk-001", "rk-002"]);+ expect(split.dev).toHaveLength(1);+ verifyEvalTake({ ...spec, receipt: split }, fixture, spec.fixture_hash);+ });++ test("a receipt that does not match the derivation is a named preregistration error", () => {+ const doc = {+ use: "rerank",+ items: [+ {+ id: "rk-001",+ query: "q1",+ candidates: [+ { title: "t", text: "bonsai drops leaves", relevant: false },+ { title: "u", text: "kubernetes autoscaler", relevant: true },+ ],+ },+ {+ id: "rk-002",+ query: "q2",+ candidates: [+ { title: "t", text: "kubernetes autoscaler", relevant: true },+ { title: "u", text: "bonsai drops leaves", relevant: false },+ ],+ },+ ],+ };+ const fixture = parseDecisionEvalFixture(doc, "rerank");+ const derived = hashOrderSplit(spec.seed, ["rk-001", "rk-002"]);+ const inverted = { dev: derived.counted, counted: derived.dev };+ expect(() =>+ verifyEvalTake({ ...spec, receipt: inverted }, fixture, spec.fixture_hash),+ ).toThrow(/preregistration/);+ });++ test("a fixture content hash that differs from the spec is refused", () => {+ const doc = {+ use: "rerank",+ items: [+ {+ id: "rk-001",+ query: "q1",+ candidates: [+ { title: "t", text: "bonsai drops leaves", relevant: false },+ { title: "u", text: "kubernetes autoscaler", relevant: true },+ ],+ },+ {+ id: "rk-002",+ query: "q2",+ candidates: [+ { title: "t", text: "kubernetes autoscaler", relevant: true },+ { title: "u", text: "bonsai drops leaves", relevant: false },+ ],+ },+ ],+ };+ const fixture = parseDecisionEvalFixture(doc, "rerank");+ const split = hashOrderSplit(spec.seed, ["rk-001", "rk-002"]);+ expect(() => verifyEvalTake({ ...spec, receipt: split }, fixture, "9".repeat(64))).toThrow(+ /fixture/,+ );+ });+});diff --git a/tests/core/search/behind-count.test.ts b/tests/core/search/behind-count.test.tsnew file mode 100644index 00000000..0d941610--- /dev/null+++ b/tests/core/search/behind-count.test.ts@@ -0,0 +1,95 @@+/**+ * The measured index-behind count (t_e4438152): a stat-only walk diffed+ * against the stored documents classifies what the next incremental run+ * would add, update or delete - measured live, before that run happens.+ *+ * Deliberate upper-bound semantics pinned here: a touch-only file (same+ * bytes, bumped mtime) counts as changed, because the walk never reads+ * content - it replicates the incremental fastpath's mtime+size+ * comparison, not the hash fallback.+ */+import { afterEach, beforeEach, expect, test } from "bun:test";+import { mkdtempSync, rmSync, utimesSync } from "node:fs";+import { tmpdir } from "node:os";+import { join } from "node:path";++import { indexBehindCount, indexVault } from "../../../src/core/search/indexer.ts";+import type { ResolvedSearchConfig } from "../../../src/core/search/types.ts";+import { createTempVault, makeConfig, writeMd } from "../../helpers/search-fixtures.ts";++let vault: string;+let dbPath: string;+let cleanup: () => void;+let config: ResolvedSearchConfig;++/** A fixed past instant, so stored and on-disk mtimes never race the clock. */+const T0 = Date.now() - 60_000;+/** A distinct second, so a stat-only comparison sees the change. */+const T1 = new Date(T0 + 10_000);+const T0_DATE = new Date(T0);++beforeEach(async () => {+ const v = createTempVault("behind-count");+ vault = v.vault;+ dbPath = v.dbPath;+ cleanup = v.cleanup;+ config = makeConfig({ vault, dbPath });+ for (const rel of ["notes/heron.md", "notes/second.md", "notes/third.md"]) {+ utimesSync(writeMd(vault, rel, `# ${rel}\n\nseed body.\n`), T0_DATE, T0_DATE);+ }+ await indexVault(config);+});++afterEach(() => cleanup());++test("a freshly indexed vault measures zero behind", async () => {+ expect(await indexBehindCount(config)).toEqual({+ behind: 0,+ unindexed: 0,+ changed: 0,+ deleted: 0,+ });+});++test("added, edited, touch-only and deleted files classify exactly", async () => {+ // Edited: new bytes AND a bumped mtime - the file the next run must read.+ utimesSync(writeMd(vault, "notes/heron.md", "# heron\n\nedited body.\n"), T1, T1);+ // Touch-only: same bytes, bumped mtime. Counts as changed - the walk is+ // stat-only, so this is an upper bound on what the run would spend.+ utimesSync(join(vault, "notes", "second.md"), T1, T1);+ // Deleted from disk; the index still holds the row.+ rmSync(join(vault, "notes", "third.md"));+ // Added: on disk, never indexed.+ writeMd(vault, "notes/fresh.md", "# fresh\n\nnew body.\n");++ expect(await indexBehindCount(config)).toEqual({+ behind: 4,+ unindexed: 1,+ changed: 2,+ deleted: 1,+ });+});++test("ignored paths and admission-lane paths are not counted", async () => {+ writeMd(vault, "node_modules/leak.md", "# leak\n");+ writeMd(vault, "Brain/state/ledger.md", "# ledger\n");+ expect(await indexBehindCount(config)).toEqual({+ behind: 0,+ unindexed: 0,+ changed: 0,+ deleted: 0,+ });+});++test("a missing index is not measured, not zero", async () => {+ const bare = mkdtempSync(join(tmpdir(), "osb-behind-bare-"));+ try {+ const bareConfig = makeConfig({+ vault: bare,+ dbPath: join(bare, ".open-second-brain", "brain.sqlite"),+ });+ expect(await indexBehindCount(bareConfig)).toBeNull();+ } finally {+ rmSync(bare, { recursive: true, force: true });+ }+});diff --git a/tests/core/search/freshen-search.test.ts b/tests/core/search/freshen-search.test.tsindex 432459ca..ef081f38 100644--- a/tests/core/search/freshen-search.test.ts+++ b/tests/core/search/freshen-search.test.ts@@ -5,21 +5,49 @@* named on the trail as `index-stale` whatever the freshen setting. The* query cache stores answers without that code and the trail gains it at* read time, so a cache hit names the index age it is served at.+ *+ * The stale note also carries the measured behind count (t_e4438152):+ * computed only when the note fires, so a fresh index performs no walk;+ * a failed measurement leaves the age alone on the note.*/-import { afterEach, beforeEach, expect, test } from "bun:test";+import { afterEach, beforeEach, expect, mock, test } from "bun:test";import { Database } from "bun:sqlite";-import { indexVault } from "../../../src/core/search/indexer.ts";+import { createNote } from "../../../src/core/brain/notes/create-note.ts";+import { claimNoteWriteRefresh } from "../../../src/core/brain/notes/index-refresh.ts";+import { indexBehindCount, indexVault } from "../../../src/core/search/indexer.ts";import { RETRIEVAL_DEGRADATION } from "../../../src/core/search/retrieval-trail.ts";-import { search } from "../../../src/core/search/search.ts";+import {+ INDEX_BEHIND_MEMO_TTL_MS,+ measureIndexBehind,+ search,+} from "../../../src/core/search/search.ts";import { LAST_INDEXED_AT_STATE_KEY } from "../../../src/core/search/store/state.ts";-import type { ResolvedSearchConfig } from "../../../src/core/search/types.ts";+import type { SearchOutcome, ResolvedSearchConfig } from "../../../src/core/search/types.ts";+import * as walkerModule from "../../../src/core/search/walker.ts";+import { withIndexStale } from "../../../src/core/search/pipeline/outcome.ts";import { createTempVault, makeConfig, writeMd } from "../../helpers/search-fixtures.ts";let vault: string;let dbPath: string;let cleanup: () => void;let calls: string[][];+let walks = 0;+let failWalk = false;+const realWalkVault = walkerModule.walkVault;++// Count the vault walks every consumer of the shared walker performs,+// and allow a test to fail one, so "no walk" and "null measurement" are+// observed rather than inferred.+mock.module("../../../src/core/search/walker.ts", () => ({+ ...walkerModule,+ walkVault: (config: ResolvedSearchConfig) => {+ if (failWalk) throw new Error("walk refused");+ walks++;+ return realWalkVault(config);+ },+}));+const spawn = (argv: string[]): void => {calls.push(argv);};@@ -34,7 +62,10 @@ beforeEach(async () => {await indexVault(config(60));});-afterEach(() => cleanup());+afterEach(() => {+ failWalk = false;+ cleanup();+});function config(intervalSeconds: number, cacheEnabled = false): ResolvedSearchConfig {return Object.freeze({@@ -151,3 +182,165 @@ test("a cache hit over a fresh index carries no stale code", async () => {expect(staleCodes(outcome)).toEqual([]);expect(outcome.retrievalTrail).toBeUndefined();});++test("a stale index names the measured behind count beside its age", async () => {+ writeMd(vault, "notes/kestrel.md", "# Kestrel\n\nThe kestrel hovers over the verge.\n");+ setIndexAge(11 * 60);+ const outcome = await search(config(0), { query: "heron", freshenSpawn: spawn });+ const stale = staleCodes(outcome);+ expect(stale).toHaveLength(1);+ expect(stale[0]!.detail?.["behindCount"]).toBe(1);+ expect(stale[0]!.detail?.["ageSeconds"]).toBeGreaterThanOrEqual(660);+});++test("a fresh index emits no stale code and performs no walk", async () => {+ writeMd(vault, "notes/kestrel.md", "# Kestrel\n\nThe kestrel hovers over the verge.\n");+ const before = walks;+ const outcome = await search(config(0), { query: "heron", freshenSpawn: spawn });+ expect(staleCodes(outcome)).toEqual([]);+ expect(walks).toBe(before);+});++test("a stale search performs exactly one walk", async () => {+ setIndexAge(11 * 60);+ const before = walks;+ await search(config(0), { query: "heron", freshenSpawn: spawn });+ expect(walks).toBe(before + 1);+});++test("repeated stale searches inside the behind-count memo window walk once", async () => {+ // Finding 24: on a permanently-stale origin (freshening off here; a+ // read-only cross-vault origin is the other case) every search used to+ // pay the full synchronous stat walk plus a vec-loading store open all+ // over again, forever. Inside the memo window the measurement is+ // reused, so the second stale search walks nothing.+ setIndexAge(11 * 60);+ const before = walks;+ await search(config(0), { query: "heron", freshenSpawn: spawn });+ await search(config(0), { query: "heron", freshenSpawn: spawn });+ expect(walks).toBe(before + 1);+});++test("the behind-count memo serves the TTL window and expires with the injected clock", async () => {+ setIndexAge(11 * 60);+ const before = walks;+ const cfg = config(0);+ const stamp = "2026-06-03T12:00:00.000Z";+ // First measurement under the memo: one walk.+ expect(await measureIndexBehind(cfg, stamp, 1_000_000)).toBe(0);+ expect(walks).toBe(before + 1);+ // Inside the window: served from the memo, no walk.+ expect(await measureIndexBehind(cfg, stamp, 1_000_000 + INDEX_BEHIND_MEMO_TTL_MS - 1)).toBe(0);+ expect(walks).toBe(before + 1);+ // At/after the window: measured again.+ expect(await measureIndexBehind(cfg, stamp, 1_000_000 + INDEX_BEHIND_MEMO_TTL_MS)).toBe(0);+ expect(walks).toBe(before + 2);+});++test("a re-stamped index invalidates the behind-count memo inside the window", async () => {+ setIndexAge(11 * 60);+ const before = walks;+ const cfg = config(0);+ expect(await measureIndexBehind(cfg, "2026-06-03T12:00:00.000Z", 1_000_000)).toBe(0);+ expect(walks).toBe(before + 1);+ // A freshen run re-stamped the index: the memo must not outlive the+ // index generation it measured, even inside the TTL.+ expect(await measureIndexBehind(cfg, "2026-06-03T12:00:05.000Z", 1_000_001)).toBe(0);+ expect(walks).toBe(before + 2);+});++test("an in-process note write invalidates the served behind count inside the window", async () => {+ // M9: the memo was keyed by the TTL and the index stamp alone, so on an+ // origin where nothing freshens (freshening off here; read-only+ // cross-vault recall is the other case) a search memoized 0 and every+ // later search inside the window served it - including over notes this+ // process had just written. The applied write path must drop the+ // entry, so the next search re-measures instead of serving a+ // confident 0 across an edit. A write from a DIFFERENT process still+ // reaches nothing here - the memo is per-process state - and the TTL+ // alone bounds that residual: past the window the entry expires and+ // the next search re-measures, which the window test above pins.+ setIndexAge(11 * 60);+ const before = walks;+ const cfg = config(0);+ // Prime the memo: the first stale search measures 0 behind, one walk.+ const primed = await search(cfg, { query: "heron", freshenSpawn: spawn });+ expect(staleCodes(primed)[0]!.detail?.["behindCount"]).toBe(0);+ expect(walks).toBe(before + 1);+ // Three notes land through the in-process write seam - the same+ // create-then-claim sequence the MCP note tools drive after an+ // applied create, one claim per write. The spawn seam stays a no-op:+ // the claim's detached child is not what retires the memo, the write+ // is.+ const memoOne = createNote(vault, {+ path: "notes/memo-one.md",+ content: "# Memo one\n\nwritten after the measurement.\n",+ });+ expect(memoOne.outcome).toBe("created");+ await claimNoteWriteRefresh(vault, () => {});+ const memoTwo = createNote(vault, {+ path: "notes/memo-two.md",+ content: "# Memo two\n\nwritten after the measurement.\n",+ });+ expect(memoTwo.outcome).toBe("created");+ await claimNoteWriteRefresh(vault, () => {});+ const memoThree = createNote(vault, {+ path: "notes/memo-three.md",+ content: "# Memo three\n\nwritten after the measurement.\n",+ });+ expect(memoThree.outcome).toBe("created");+ await claimNoteWriteRefresh(vault, () => {});+ // Still inside the TTL: the count is re-measured, not served. The+ // three notes ride with the write path's own audit log (createNote+ // appends Brain/log), so the exact number is whatever a live census+ // measures at this instant - the pin is that the served count EQUALS+ // that fresh measurement and is not the memoized 0, which only the+ // invalidation can produce.+ const served = await search(cfg, { query: "heron", freshenSpawn: spawn });+ const live = await indexBehindCount(cfg);+ expect(live).not.toBeNull();+ expect(live!.behind).toBeGreaterThanOrEqual(3);+ expect(staleCodes(served)[0]!.detail?.["behindCount"]).toBe(live!.behind);+ // One walk each: the priming search, the re-measure after the writes+ // (the invalidation fired; the memo served nothing), and the live+ // census above through the same mocked walker.+ expect(walks).toBe(before + 3);+});++test("a failed behind-count measurement is not memoized", async () => {+ setIndexAge(11 * 60);+ const before = walks;+ const cfg = config(0);+ failWalk = true;+ expect(await measureIndexBehind(cfg, "2026-06-03T12:00:00.000Z", 1_000_000)).toBeNull();+ expect(walks).toBe(before);+ failWalk = false;+ // The next search retries: null was never a measurement.+ expect(await measureIndexBehind(cfg, "2026-06-03T12:00:00.000Z", 1_000_001)).toBe(0);+ expect(walks).toBe(before + 1);+});++test("a failed measurement leaves the age alone on the stale note", async () => {+ failWalk = true;+ setIndexAge(11 * 60);+ const outcome = await search(config(0), { query: "heron", freshenSpawn: spawn });+ const stale = staleCodes(outcome);+ expect(stale).toHaveLength(1);+ expect(Object.keys(stale[0]!.detail ?? {})).toEqual(["ageSeconds"]);+});++test("the stale detail carries behindCount only when one was measured", () => {+ const base = {+ results: [],+ warnings: [],+ total: 0,+ idfWeightedCoverage: 0,+ } as unknown as SearchOutcome;+ const measured = withIndexStale(base, 100_000, 4);+ expect(measured.retrievalTrail?.degraded[0]?.detail).toEqual({+ ageSeconds: 100_000,+ behindCount: 4,+ });+ const unmeasured = withIndexStale(base, 100_000, null);+ expect(unmeasured.retrievalTrail?.degraded[0]?.detail).toEqual({ ageSeconds: 100_000 });+});diff --git a/tests/core/search/search-query-schema-artifact.test.ts b/tests/core/search/search-query-schema-artifact.test.tsnew file mode 100644index 00000000..85f53f98--- /dev/null+++ b/tests/core/search/search-query-schema-artifact.test.ts@@ -0,0 +1,397 @@+/**+ * The search-query schema artifact guard (t_50c81d5c substrate): the+ * served `brain_search` input schema is DERIVED from the search-options+ * descriptor, and this suite proves the derivation changed nothing.+ *+ * `LEGACY_SEARCH_INPUT_SCHEMA` below is the literal object that lived in+ * `src/mcp/search-tools.ts` before the descriptor existed, pasted+ * verbatim: the numeric bounds are inlined (they are the frozen baseline+ * - importing the live constants would let the expected value drift with+ * the code), while the enum vocabularies are imported exactly as the old+ * literal spelled them, each frozen and pinned by its own suite. The+ * served constant must deep-equal the literal AND serialize to the same+ * JSON bytes: the vendored Hermes projection and every `tool.inputSchema`+ * reader depend on the shape, and the day-one contract is identity.+ *+ * The reverse-direction tests hold the descriptor to its own story:+ * every mcp row is served and nothing else is, every cli row carries its+ * flag spelling, and the descriptor's `option` spellings are checked+ * against a key-for-key enumeration of `SearchOptions` - the runtime+ * anchor for the compile-time assertion the row type itself makes+ * (`option: keyof SearchOptions | null` refuses a phantom key to tsc).+ * The walk runs BOTH ways: every `SearchOptions` field must be served by+ * a row or named in the documented non-surface list, so the+ * descriptor's claim - no caller-facing field missing a row - cannot rot.+ */++import { describe, expect, test } from "bun:test";++import { SEARCH_INPUT_SCHEMA } from "../../../src/mcp/search-tools.ts";+import {+ deriveSearchInputSchema,+ SEARCH_OPTION_ROWS,+} from "../../../src/core/search/search-options-descriptor.ts";+import { DISCLOSURE_MODES } from "../../../src/core/search/disclosure-mode.ts";+import { FTS_MATCH_MODES } from "../../../src/core/search/fts-match-mode.ts";+import { RECALL_PROFILE_NAMES } from "../../../src/core/search/profiles.ts";+import { SEARCH_KINDS } from "../../../src/core/search/property-pushdown.ts";+import type { SearchOptions } from "../../../src/core/search/types.ts";++/**+ * The pre-derivation literal, frozen. If this object and the served+ * schema ever disagree, the served schema moved first and this suite is+ * the tripwire.+ */+const LEGACY_SEARCH_INPUT_SCHEMA: Record<string, unknown> = {+ type: "object",+ properties: {+ query: {+ type: "string",+ minLength: 1,+ maxLength: 2000,+ description:+ "What to recall from the vault. Matched against the index by keyword, semantics, or both.",+ },+ query_document: {+ type: "string",+ minLength: 1,+ maxLength: 4000,+ description:+ "Line-oriented query program with intent:, lex:, vec: and hyde: lanes, steering each retrieval layer separately. Absent means 'query' drives every lane.",+ },+ focus_query: {+ type: "string",+ minLength: 1,+ maxLength: 1000,+ description:+ "Steer this one call towards a working-set topic without persisting a session focus.",+ },+ focus_path_prefix: {+ type: "string",+ minLength: 1,+ maxLength: 256,+ description:+ "Steer this one call towards a vault subtree, paired with focus_query as a transient focus.",+ },+ focus_session: {+ type: "string",+ minLength: 1,+ maxLength: 128,+ description: "Session id whose bound focus applies (falls back to the global focus).",+ },+ evidence_pack: {+ type: "boolean",+ description:+ "Return the evidence pack: matched/missing terms, coverage, abstention text and the false-absence guard. Default false.",+ },+ include_superseded: {+ type: "boolean",+ description:+ "History mode for relation polarity: keep matched superseded predecessors undemoted and skip successor pull-in. Default false.",+ },+ since: {+ type: "string",+ maxLength: 64,+ description:+ "Hard filter on event time (validity, body anchor, mtime last): at/after this point. ISO date/datetime, today, yesterday, last week, last month, <n>h/<n>d/<n>w.",+ },+ until: {+ type: "string",+ maxLength: 64,+ description:+ "Hard filter on event time (validity, body anchor, mtime last): at/before this point. Same forms as 'since'.",+ },+ limit: {+ type: "integer",+ minimum: 1,+ maximum: 50,+ description: "How many ranked results to return. Default 10.",+ },+ semantic: {+ type: "boolean",+ description:+ "Force the semantic lane on or off. Absent lets the configured hybrid strategy decide.",+ },+ keyword_only: {+ type: "boolean",+ description: "Skip the semantic lane entirely, so no embedding is needed. Default false.",+ },+ match_mode: {+ type: "string",+ enum: [...FTS_MATCH_MODES],+ description:+ "FTS match breadth: 'all' (default) requires every term; 'any' matches a document carrying any one term. Absent leaves the implicit AND.",+ },+ disclosure: {+ type: "string",+ enum: [...DISCLOSURE_MODES],+ description:+ "Result depth: 'full' (default) returns full chunk content; 'cards' returns token-cheap layer-1 cards — drill a hit with brain_search_expand.",+ },+ profile: {+ type: "string",+ enum: [...RECALL_PROFILE_NAMES],+ description:+ "Named recall profile (fast|balanced|thorough): a fixed knob preset, preferred over persisted self-tuning. Absent leaves ranking unchanged.",+ },+ explain: {+ type: "boolean",+ description:+ "Add a per-result score_breakdown plus the retrieval_decision_trace and memory_trust_assessment receipts. Default false.",+ },+ trust: {+ type: "boolean",+ description:+ "Stamp each result with inline trust metadata (age_days, superseded, conflict), computed at read time. Default false.",+ },+ threshold: {+ type: "number",+ minimum: 0,+ maximum: 1,+ description:+ "Relevance floor in [0,1] on the final score; drops weaker hits so an irrelevant query returns no match. Default 0 (disabled).",+ },+ rerank: {+ type: "boolean",+ description:+ "Re-order the threshold-qualified results by core textual relevance (keyword + semantic). Default false.",+ },+ reinforce: {+ type: "array",+ maxItems: 50,+ items: { type: "string", minLength: 1, maxLength: 512 },+ description:+ "Paths proven useful: recorded to the reinforce ledger and lifted (bounded) before the top_k cut. Default absent.",+ },+ record_access: {+ type: "boolean",+ description:+ "Record the surfaced paths as one activation access event (feeds the usage-aware ranking layer). Default true; never recorded for global searches.",+ },+ global: {+ type: "boolean",+ description:+ "Cross-vault union: search profile vaults and read-only recall sources too, merging results with origin labels. Default false (active vault only).",+ },+ path_prefix: {+ type: "string",+ maxLength: 256,+ description: "Restrict results to this vault subtree. Absent searches the whole vault.",+ },+ telemetry: {+ type: "boolean",+ description: "Emit one recall-telemetry continuity record for this call. Default false.",+ },+ telemetry_host: {+ type: "string",+ maxLength: 200,+ description: "Optional host/client label recorded on the telemetry record.",+ },+ session_id: {+ type: "string",+ maxLength: 512,+ description: "Optional session correlation id recorded on the telemetry record.",+ },+ turn_id: {+ type: "string",+ maxLength: 512,+ description: "Optional turn correlation id recorded on the telemetry record.",+ },+ properties: {+ type: "object",+ description:+ "Optional frontmatter filter; values within a key OR, keys AND. type, pinned, visibility as indexed; other keys narrow on the attribute snapshot, judged live.",+ additionalProperties: {+ type: "array",+ items: { type: "string" },+ },+ },+ kind: {+ type: "string",+ enum: [...SEARCH_KINDS],+ description:+ "Restrict candidates by chunk kind: 'page' matches each document's frontmatter/head chunk (chunk 0), 'section' everything after it. Absent searches all chunks.",+ },+ degree: {+ type: "array",+ description:+ "Graph-degree predicates over backlink/outlink counts, e.g. 'backlinks=0' (orphans) or 'outlinks>=5' (hubs); ANDed. Absent = no filter.",+ items: { type: "string" },+ },+ visibility: {+ type: "array",+ description:+ "Optional content-visibility scope; untagged pages always match, tagged pages only when this scope includes one of their values.",+ items: { type: "string" },+ },+ agent_scope: {+ type: "string",+ description:+ "Optional agent-ownership scope; shared (ownerless) pages always match, owner-tagged pages only their owner. Absent = no ownership filtering.",+ },+ session_scope: {+ type: "string",+ description:+ "Optional session-scope filter; pages with no session always match, session-tagged pages only this session. Absent = no session filtering.",+ },+ project_scope: {+ type: "string",+ description:+ "Optional project-scope filter; pages with no project always match, project-tagged pages only this project. Absent = no project filtering.",+ },+ iterative: {+ type: "boolean",+ description:+ "Opt in to the bounded iterative recall loop (default off). Surviving gaps pause with a plan; resume via iterative_payload. Inert unless the knob is on.",+ },+ iterative_token: {+ type: "string",+ maxLength: 128,+ description:+ "The round token from a plan-phase response, submitted beside iterative_payload. Requires iterative: true; single use - a replayed token is refused by name.",+ },+ iterative_payload: {+ type: "object",+ description:+ "Decider payload answering a plan-phase envelope: { evidence: [chunkId, ...], subQueries: [...] }, validated before any pull runs. Requires iterative_token.",+ },+ },+ required: ["query"],+ additionalProperties: false,+};++/**+ * Every `SearchOptions` key, enumerated. A missing or stale entry is a+ * COMPILE error here (the record type demands completeness), so the+ * enumeration cannot silently rot - which is what makes the runtime+ * phantom-key check below mean something.+ */+const SEARCH_OPTIONS_KEY_PROBE: Record<keyof SearchOptions, true> = {+ query: true,+ limit: true,+ semantic: true,+ keywordOnly: true,+ pathPrefix: true,+ keywordWeight: true,+ semanticWeight: true,+ matchMode: true,+ properties: true,+ kind: true,+ degreeFilters: true,+ mmrLambda: true,+ maxHops: true,+ poolMaxPerSession: true,+ visibility: true,+ transportReach: true,+ agentScope: true,+ scope: true,+ relationalArm: true,+ structuredQuery: true,+ expand: true,+ disclosure: true,+ profile: true,+ sessionFocus: true,+ focusSession: true,+ evidencePack: true,+ iterative: true,+ iterativeToken: true,+ iterativePayload: true,+ recordAccess: true,+ includeSuperseded: true,+ since: true,+ until: true,+ trust: true,+ threshold: true,+ rerank: true,+ reinforce: true,+ selfHeal: true,+ freshenSpawn: true,+ laneTiming: true,+ skipDecisionModelRerank: true,+};++/**+ * The `SearchOptions` fields that deliberately carry NO descriptor row:+ * they are not part of the caller-facing query language, so no mcp+ * argument and no CLI flag exists for them. This list is the ONLY way a+ * `SearchOptions` key skips the reverse-direction walk below, which is+ * what makes the walk able to fail: a NEW caller-facing field without a+ * row fails it, and demoting a field to non-surface is a documented,+ * reviewable edit here - never a silent gap. Compile-time anchored like+ * the probe above: a misspelled name is a `tsc` error.+ */+const NON_SURFACE_SEARCH_OPTIONS: ReadonlyArray<keyof SearchOptions> = [+ // Self-tuning knobs: resolved from config per query by the grid, no+ // surface argument reaches them.+ "mmrLambda",+ "maxHops",+ "poolMaxPerSession",+ "relationalArm",+ // Minted by the surface that accepted the call (the CLI's local reach,+ // the MCP server's transport), never spelled by a caller argument.+ "transportReach",+ // Routing policy: cross-vault traversal pins this false on non-active+ // origins so a read-only vault is never written to.+ "selfHeal",+ // Callback seams: the background-freshen spawn (tests), the per-call+ // lane-timing sink (the CLI and the bench project the timing+ // themselves), and the hook surfaces' decision-rerank skip.+ "freshenSpawn",+ "laneTiming",+ "skipDecisionModelRerank",+];++describe("search input schema derivation (t_50c81d5c substrate)", () => {+ test("the derived SEARCH_INPUT_SCHEMA deep-equals the pre-derivation literal", () => {+ expect(SEARCH_INPUT_SCHEMA).toEqual(LEGACY_SEARCH_INPUT_SCHEMA);+ });++ test("and serializes to identical JSON bytes, so tools/list and the vendored projection are untouched", () => {+ expect(JSON.stringify(SEARCH_INPUT_SCHEMA)).toBe(JSON.stringify(LEGACY_SEARCH_INPUT_SCHEMA));+ });++ test("the derivation serves exactly the mcp rows, in declaration order", () => {+ const served = deriveSearchInputSchema();+ const mcpRows = SEARCH_OPTION_ROWS.filter((row) => row.surfaces.includes("mcp"));+ expect(Object.keys(served.properties)).toEqual(mcpRows.map((row) => row.name));+ expect(served.required).toEqual(+ mcpRows.filter((row) => row.required === true).map((row) => row.name),+ );+ expect(served.additionalProperties).toBe(false);+ });++ test("every cli row names its flag spelling, and an unflagged row reaches neither surface's flags", () => {+ const drifted: string[] = [];+ for (const row of SEARCH_OPTION_ROWS) {+ const onCli = row.surfaces.includes("cli");+ if (onCli && row.cliFlag === null) drifted.push(`${row.name}: cli row without a flag`);+ if (!onCli && row.cliFlag !== null) drifted.push(`${row.name}: flag outside the cli surface`);+ }+ expect(drifted).toEqual([]);+ });++ test("every row option key exists on SearchOptions - the compile-time assertion, anchored at runtime", () => {+ const phantom: string[] = [];+ for (const row of SEARCH_OPTION_ROWS) {+ if (row.option !== null && SEARCH_OPTIONS_KEY_PROBE[row.option] !== true) {+ phantom.push(`${row.name}: ${String(row.option)}`);+ }+ }+ expect(phantom).toEqual([]);+ });++ test("every SearchOptions field has a descriptor row - the reverse direction", () => {+ const rows = new Set(+ SEARCH_OPTION_ROWS.filter((row) => row.option !== null).map((row) => String(row.option)),+ );+ const exempt = new Set(NON_SURFACE_SEARCH_OPTIONS.map(String));+ const drifted: string[] = [];+ for (const key of Object.keys(SEARCH_OPTIONS_KEY_PROBE)) {+ const hasRow = rows.has(key);+ const isExempt = exempt.has(key);+ if (hasRow && isExempt) drifted.push(`${key}: exempted from the walk but a row serves it`);+ if (!hasRow && !isExempt) drifted.push(`${key}: no descriptor row and not exempted`);+ }+ expect(drifted).toEqual([]);+ });+});diff --git a/tests/core/state/surfaces.test.ts b/tests/core/state/surfaces.test.tsindex 9e8fc780..6d2407eb 100644--- a/tests/core/state/surfaces.test.ts+++ b/tests/core/state/surfaces.test.ts@@ -42,6 +42,7 @@ import {brainArtifactsDir,brainDirs,claimGraphPath,+ crossTopicLedgerPath,dreamRunsDir,hookAuditDir,prefAuditDir,@@ -305,6 +306,7 @@ const RESOLVER_BINDINGS: ReadonlyArray<readonly [StateSurfaceId, (vault: string)["skill_accept_journal", (v) => dirname(skillAcceptJournalPath(v, "probe"))],["claim_graph", (v) => claimGraphPath(v)],["rollup_ledger", (v) => rollupLedgerPath(v)],+ ["cross_topic_ledger", (v) => crossTopicLedgerPath(v)],["decision_ledger", (v) => decisionLedgerDir(v)],["source_archives", (v) => sourceArchivesDir(v)],]);@@ -465,6 +467,19 @@ describe("each row is bound to the resolver that owns it", () => {});}+ test("the cross-topic rule ledger names its Brain/ file exactly (t_642bc2b8)", () => {+ const example = resolve("/srv/vaults/example");+ expect(crossTopicLedgerPath(example)).toBe(join(example, "Brain", "cross-topic-rules.json"));+ expect(row(STATE_SURFACE_ID.crossTopicLedger).derive(example, null)).toBe(+ crossTopicLedgerPath(example),+ );+ // Nothing creates the ledger at init - it appears with the first+ // fired promotion - so a fresh vault reports it absent, not unchecked.+ expect(reportFor(tempVault(), STATE_SURFACE_ID.crossTopicLedger).reachability.state).toBe(+ STATE_REACHABILITY.absent,+ );+ });+test("the search index follows its override, and so does everything derived from it", () => {const elsewhere = "/elsewhere/brain.sqlite";expect(row("search_index").derive(vault, elsewhere)).toBe(resolveIndexPath(vault, elsewhere));diff --git a/tests/docs/search-query-doc-examples.test.ts b/tests/docs/search-query-doc-examples.test.tsnew file mode 100644index 00000000..bb3cac30--- /dev/null+++ b/tests/docs/search-query-doc-examples.test.ts@@ -0,0 +1,208 @@+/**+ * The documented search examples say what the code does (t_50c81d5c,+ * Task E5), on the retrieval-trail-doc pattern: extraction is scoped to+ * the Search sections of the operator docs, and every documented token is+ * checked against the code that must honor it.+ *+ * Four checks, each a different direction:+ *+ * - the documented structured-query example under "Structured recall+ * query documents" parses with the REAL parser, and the brain_search+ * argument object its claims describe validates against the COMMITTED+ * artifact (schemas/brain/search-query.schema.json);+ * - every intent token the documented grammar sentence names appears in+ * the artifact's query_document enum AND parses with the real parser,+ * so the artifact's grammar block cannot drift from either side;+ * - every `--flag` in the scoped `o2b search "<query>"` block of+ * docs/cli-reference.md is accepted by the descriptor-derived flag+ * table (doc -> code; other search verbs are excluded by the scoping);+ * - every backticked brain_search argument name in the docs/mcp.md+ * paragraph is a property of the artifact (code vocabulary must have a+ * documented row, inverted).+ *+ * Scope contract: this suite reads ONLY the operator docs listed below -+ * never docs/plans/** or docs/brainstorm/**, which are dated design+ * archives documenting superseded shapes.+ */++import { expect, test } from "bun:test";+import { readFileSync } from "node:fs";+import { join } from "node:path";++import { buildSearchQueryArtifact } from "../../src/cli/search/verbs/schema-export.ts";+import { SEARCH_QUERY_FLAGS } from "../../src/cli/search/verbs/query.ts";+import { parseStructuredRecallQueryDocument } from "../../src/core/search/structured-query.ts";+import { SEARCH_OPTION_ROWS } from "../../src/core/search/search-options-descriptor.ts";+import {+ assertSupportedSchema,+ type SchemaNode,+ validateAgainstSchema,+} from "../helpers/json-schema-subset.ts";++const REPO_ROOT = join(import.meta.dir, "..", "..");+const CLI_REFERENCE = readFileSync(join(REPO_ROOT, "docs", "cli-reference.md"), "utf8");+const MCP_DOC = readFileSync(join(REPO_ROOT, "docs", "mcp.md"), "utf8");++/** The only files this suite reads. The scope assertion below pins them. */+const DOC_FILES_READ: ReadonlyArray<string> = ["docs/cli-reference.md", "docs/mcp.md"];++const ARTIFACT: SchemaNode = (() => {+ const artifact = buildSearchQueryArtifact();+ assertSupportedSchema(artifact);+ return JSON.parse(JSON.stringify(artifact)) as SchemaNode;+})();++/** The grammar lane names, which document lines but are not artifact properties. */+const QUERY_DOCUMENT_LANES: ReadonlySet<string> = new Set(["intent", "lex", "vec", "hyde"]);++/** The `## Search` section of cli-reference.md, up to the next section heading. */+function searchSection(): string {+ const start = CLI_REFERENCE.indexOf("\n## Search\n");+ expect(start).toBeGreaterThanOrEqual(0);+ const next = CLI_REFERENCE.indexOf("\n## ", start + 1);+ return CLI_REFERENCE.slice(start, next === -1 ? undefined : next);+}++/** The `o2b search "<query>"` entry block, up to the next `o2b search` verb line. */+function queryVerbBlock(): string {+ const section = searchSection();+ const start = section.indexOf('o2b search "<query>"');+ expect(start).toBeGreaterThanOrEqual(0);+ const next = section.indexOf("\no2b search ", start + 1);+ return section.slice(start, next === -1 ? undefined : next);+}++/** The structured-query prose plus its fenced example, from the Search section. */+function structuredQueryDoc(): { prose: string; example: string } {+ const section = searchSection();+ const start = section.indexOf("Structured recall query documents");+ expect(start).toBeGreaterThanOrEqual(0);+ const fence = section.indexOf("```text", start);+ expect(fence).toBeGreaterThan(start);+ const close = section.indexOf("```", fence + 7);+ return {+ prose: section.slice(start, fence),+ example: section+ .slice(fence + 7, close)+ .replace(/^\n/, "")+ .replace(/\n$/, ""),+ };+}++test("the suite stays scoped to the operator docs, never the design archives", () => {+ for (const file of DOC_FILES_READ) {+ expect(+ `${file} outside design archives: ${file.startsWith("docs/plans/") || file.startsWith("docs/brainstorm/")}`,+ ).toBe(`${file} outside design archives: false`);+ }+});++test("the documented structured-query example parses with the real parser", () => {+ const { example } = structuredQueryDoc();+ // The example is exactly what the docs show; the real parser accepts it.+ const document = parseStructuredRecallQueryDocument(example);+ expect(document.intent).toBe("entity");+ expect(document.lex.include).toContain("project alpha");+ expect(document.lex.exclude).toContain("archived");+});++test("a brain_search call built from the documented claims validates against the artifact", () => {+ const { example } = structuredQueryDoc();+ const args = {+ query: "project alpha",+ query_document: example,+ kind: "section",+ since: "last week",+ limit: 10,+ disclosure: "cards",+ match_mode: "any",+ };+ const result = validateAgainstSchema(ARTIFACT, args);+ expect(result.errors).toEqual([]);+});++test("every intent token in the documented grammar sentence is in the artifact's enum and parses", () => {+ const { prose } = structuredQueryDoc();+ const marker = "`intent:` accepts";+ const at = prose.indexOf(marker);+ expect(at).toBeGreaterThanOrEqual(0);+ const sentence = prose.slice(at + marker.length, prose.indexOf(";", at));+ const named = [...sentence.matchAll(/`([a-z]+)`/g)].map((m) => m[1]!);+ // Not vacuous: the sentence names all four shipped intents.+ expect(named.toSorted()).toEqual(["broad", "entity", "exact", "neutral"]);+ const grammar = (+ ARTIFACT as unknown as {+ $defs: { search_query_document: { properties: { intent: { enum: string[] } } } };+ }+ ).$defs.search_query_document.properties.intent.enum;+ for (const token of named) {+ expect(`${token} in the artifact enum: ${grammar.includes(token)}`).toBe(+ `${token} in the artifact enum: true`,+ );+ // And the real parser accepts what the sentence and the artifact name.+ expect(() => parseStructuredRecallQueryDocument(`intent: ${token}`)).not.toThrow();+ }+});++test("every --flag in the documented query-verb block is accepted by the derived flag table", () => {+ const block = queryVerbBlock();+ const documented = [...new Set([...block.matchAll(/--[a-z0-9-]+/g)].map((m) => m[0]!.slice(2)))];+ // Not vacuous: the block documents the query verb's headline flags.+ expect(documented.length).toBeGreaterThanOrEqual(8);+ expect(documented).toContain("query-doc");+ const unknown = documented.filter((flag) => !(flag in SEARCH_QUERY_FLAGS));+ expect(unknown).toEqual([]);+});++test("the documented query-verb flags all name descriptor cli rows or the verb-local trio", () => {+ // The table the verb parses is descriptor rows + vault flags + the+ // verb-local output flags; the docs must never name a fourth kind.+ const cliRows = new Set(+ SEARCH_OPTION_ROWS.filter((row) => row.cliFlag !== null).map((row) => row.cliFlag!),+ );+ const vaultAndLocal = new Set(["vault", "config", "db", "auto-refresh", "json", "verbose"]);+ const block = queryVerbBlock();+ const documented = [...new Set([...block.matchAll(/--[a-z0-9-]+/g)].map((m) => m[0]!.slice(2)))];+ for (const flag of documented) {+ expect(+ `${flag} documented from the language: ${cliRows.has(flag) || vaultAndLocal.has(flag)}`,+ ).toBe(`${flag} documented from the language: true`);+ }+});++test("every backticked brain_search argument in the mcp paragraph is a property of the artifact", () => {+ const start = MCP_DOC.indexOf("`brain_search` accepts");+ expect(start).toBeGreaterThanOrEqual(0);+ // The input prose only: it flows into one printed paragraph with the+ // output-receipt history that follows it ("Since v<n> ... adds two+ // top-level receipts ..."), which documents OUTPUT fields - those are+ // the answer contract, not the query language, and stay out of scope.+ const paragraph = MCP_DOC.slice(start, MCP_DOC.indexOf("\nSince v", start));+ // Argument names appear in exactly three shapes in this prose; the+ // paragraph's output-field names (`why_retrieved`, `completeness`, ...)+ // never do, so the shapes are the scoping - no name allowlist to rot.+ const named = new Set<string>();+ for (const m of paragraph.matchAll(/`([a-z_]+):/g)) named.add(m[1]!); // argument: true / lane:+ for (const m of paragraph.matchAll(/`([a-z_]+)` with\b/g)) named.add(m[1]!); // `x` with ...+ for (const m of paragraph.matchAll(/`([a-z_]+)` \/ `([a-z_]+)`/g)) {+ named.add(m[1]!); // `x` / `y` pairs+ named.add(m[2]!);+ }+ named.delete("brain_search");+ for (const lane of QUERY_DOCUMENT_LANES) named.delete(lane);+ // Not vacuous: the paragraph documents the headline arguments.+ const argumentsNamed = [...named].toSorted();+ expect(argumentsNamed).toEqual([+ "evidence_pack",+ "focus_path_prefix",+ "focus_query",+ "include_superseded",+ "query_document",+ "since",+ "telemetry",+ "until",+ ]);+ const properties = ARTIFACT.properties as Record<string, unknown>;+ const missing = argumentsNamed.filter((token) => !(token in properties));+ expect(missing).toEqual([]);+});diff --git a/tests/fixtures/decision-model/recall-inject-take.json b/tests/fixtures/decision-model/recall-inject-take.jsonnew file mode 100644index 00000000..49d10d6e--- /dev/null+++ b/tests/fixtures/decision-model/recall-inject-take.json@@ -0,0 +1,760 @@+{+ "use": "recall_inject",+ "description": "Preregistered recall_inject take: 29 items, one useful note each (useful = the note whose body answers the prompted subject), useful position cycling 0-3. The counted metric is the regret rate: a useful note whose helps probability falls below the enforce drop floor.",+ "items": [+ {+ "id": "ri-001",+ "prompt": "What should I know about the kubernetes?",+ "notes": [+ {+ "title": "Cluster notes",+ "text": "The kubernetes cluster autoscaler adds nodes when pending pods wait longer than thirty seconds. This note is the working reference for it.",+ "useful": true+ },+ {+ "title": "Observatory setup",+ "text": "The telescope needs forty minutes to reach thermal equilibrium before Saturn resolves. A later section records what changed last season.",+ "useful": false+ },+ {+ "title": "Coastal walk",+ "text": "The lighthouse keeper's cottage opens to visitors on the first Saturday of each month. The appendix lists the tools involved.",+ "useful": false+ },+ {+ "title": "Climate primer",+ "text": "The monsoon arrives at the coast in June and reaches the plateau three weeks later. Photos from the visit are filed separately.",+ "useful": false+ }+ ]+ },+ {+ "id": "ri-002",+ "prompt": "What should I know about the sourdough?",+ "notes": [+ {+ "title": "Coastal walk",+ "text": "The lighthouse keeper's cottage opens to visitors on the first Saturday of each month. The appendix lists the tools involved.",+ "useful": false+ },+ {+ "title": "Baking log",+ "text": "The sourdough starter doubles in four hours when the kitchen stays above twenty degrees. A later section records what changed last season.",+ "useful": true+ },+ {+ "title": "Camp gear",+ "text": "The hammock ridgeline sag means the suspension needs shortening by one hand width. Photos from the visit are filed separately.",+ "useful": false+ },+ {+ "title": "Observatory setup",+ "text": "The telescope needs forty minutes to reach thermal equilibrium before Saturn resolves. This note is the working reference for it.",+ "useful": false+ }+ ]+ },+ {+ "id": "ri-003",+ "prompt": "What should I know about the jellyfish?",+ "notes": [+ {+ "title": "Camp gear",+ "text": "The hammock ridgeline sag means the suspension needs shortening by one hand width. Photos from the visit are filed separately.",+ "useful": false+ },+ {+ "title": "Field survey",+ "text": "The glacier terminus retreated twelve meters since the spring survey markers were placed. This note is the working reference for it.",+ "useful": false+ },+ {+ "title": "Aquarium guide",+ "text": "Moon jellyfish drift through the tank current and pulse when they meet the light. The appendix lists the tools involved.",+ "useful": true+ },+ {+ "title": "Coastal walk",+ "text": "The lighthouse keeper's cottage opens to visitors on the first Saturday of each month. A later section records what changed last season.",+ "useful": false+ }+ ]+ },+ {+ "id": "ri-004",+ "prompt": "What should I know about the telescope?",+ "notes": [+ {+ "title": "Field survey",+ "text": "The glacier terminus retreated twelve meters since the spring survey markers were placed. This note is the working reference for it.",+ "useful": false+ },+ {+ "title": "Repair bench",+ "text": "The typewriter carriage sticks when the draw band loses tension, a ten minute fix. A later section records what changed last season.",+ "useful": false+ },+ {+ "title": "Camp gear",+ "text": "The hammock ridgeline sag means the suspension needs shortening by one hand width. The appendix lists the tools involved.",+ "useful": false+ },+ {+ "title": "Observatory setup",+ "text": "The telescope needs forty minutes to reach thermal equilibrium before Saturn resolves. Photos from the visit are filed separately.",+ "useful": true+ }+ ]+ },+ {+ "id": "ri-005",+ "prompt": "What should I know about the glacier?",+ "notes": [+ {+ "title": "Field survey",+ "text": "The glacier terminus retreated twelve meters since the spring survey markers were placed. This note is the working reference for it.",+ "useful": true+ },+ {+ "title": "Repair bench",+ "text": "The typewriter carriage sticks when the draw band loses tension, a ten minute fix. A later section records what changed last season.",+ "useful": false+ },+ {+ "title": "Show schedule",+ "text": "The planetarium dome show narrates the ecliptic twice nightly through winter. The appendix lists the tools involved.",+ "useful": false+ },+ {+ "title": "Observatory setup",+ "text": "The telescope needs forty minutes to reach thermal equilibrium before Saturn resolves. Photos from the visit are filed separately.",+ "useful": false+ }+ ]+ },+ {+ "id": "ri-006",+ "prompt": "What should I know about the bonsai?",+ "notes": [+ {+ "title": "Show schedule",+ "text": "The planetarium dome show narrates the ecliptic twice nightly through winter. The appendix lists the tools involved.",+ "useful": false+ },+ {+ "title": "Potting diary",+ "text": "The bonsai fig drops leaves when moved, so repot only at the start of spring. A later section records what changed last season.",+ "useful": true+ },+ {+ "title": "Field survey",+ "text": "The glacier terminus retreated twelve meters since the spring survey markers were placed. Photos from the visit are filed separately.",+ "useful": false+ },+ {+ "title": "Repair bench",+ "text": "The typewriter carriage sticks when the draw band loses tension, a ten minute fix. This note is the working reference for it.",+ "useful": false+ }+ ]+ },+ {+ "id": "ri-007",+ "prompt": "What should I know about the subway?",+ "notes": [+ {+ "title": "Field survey",+ "text": "The glacier terminus retreated twelve meters since the spring survey markers were placed. Photos from the visit are filed separately.",+ "useful": false+ },+ {+ "title": "History notes",+ "text": "The aqueduct gradient falls one meter per four hundred, which kept the water flowing. This note is the working reference for it.",+ "useful": false+ },+ {+ "title": "Transit memo",+ "text": "The subway signal upgrade cuts headways to ninety seconds on the eastern line. The appendix lists the tools involved.",+ "useful": true+ },+ {+ "title": "Show schedule",+ "text": "The planetarium dome show narrates the ecliptic twice nightly through winter. A later section records what changed last season.",+ "useful": false+ }+ ]+ },+ {+ "id": "ri-008",+ "prompt": "What should I know about the beehive?",+ "notes": [+ {+ "title": "History notes",+ "text": "The aqueduct gradient falls one meter per four hundred, which kept the water flowing. This note is the working reference for it.",+ "useful": false+ },+ {+ "title": "Cluster notes",+ "text": "The kubernetes cluster autoscaler adds nodes when pending pods wait longer than thirty seconds. A later section records what changed last season.",+ "useful": false+ },+ {+ "title": "Field survey",+ "text": "The glacier terminus retreated twelve meters since the spring survey markers were placed. The appendix lists the tools involved.",+ "useful": false+ },+ {+ "title": "Apiary record",+ "text": "The beehive entrance reducer stays on until the colony draws out the second deep box. Photos from the visit are filed separately.",+ "useful": true+ }+ ]+ },+ {+ "id": "ri-009",+ "prompt": "What should I know about the lighthouse?",+ "notes": [+ {+ "title": "Coastal walk",+ "text": "The lighthouse keeper's cottage opens to visitors on the first Saturday of each month. This note is the working reference for it.",+ "useful": true+ },+ {+ "title": "Cluster notes",+ "text": "The kubernetes cluster autoscaler adds nodes when pending pods wait longer than thirty seconds. A later section records what changed last season.",+ "useful": false+ },+ {+ "title": "Potting diary",+ "text": "The bonsai fig drops leaves when moved, so repot only at the start of spring. The appendix lists the tools involved.",+ "useful": false+ },+ {+ "title": "History notes",+ "text": "The aqueduct gradient falls one meter per four hundred, which kept the water flowing. Photos from the visit are filed separately.",+ "useful": false+ }+ ]+ },+ {+ "id": "ri-010",+ "prompt": "What should I know about the typewriter?",+ "notes": [+ {+ "title": "Potting diary",+ "text": "The bonsai fig drops leaves when moved, so repot only at the start of spring. The appendix lists the tools involved.",+ "useful": false+ },+ {+ "title": "Repair bench",+ "text": "The typewriter carriage sticks when the draw band loses tension, a ten minute fix. A later section records what changed last season.",+ "useful": true+ },+ {+ "title": "Restoration log",+ "text": "The windmill sails need tarring before the autumn storms, never in direct sun. Photos from the visit are filed separately.",+ "useful": false+ },+ {+ "title": "Cluster notes",+ "text": "The kubernetes cluster autoscaler adds nodes when pending pods wait longer than thirty seconds. This note is the working reference for it.",+ "useful": false+ }+ ]+ },+ {+ "id": "ri-011",+ "prompt": "What should I know about the aqueduct?",+ "notes": [+ {+ "title": "Restoration log",+ "text": "The windmill sails need tarring before the autumn storms, never in direct sun. Photos from the visit are filed separately.",+ "useful": false+ },+ {+ "title": "Baking log",+ "text": "The sourdough starter doubles in four hours when the kitchen stays above twenty degrees. This note is the working reference for it.",+ "useful": false+ },+ {+ "title": "History notes",+ "text": "The aqueduct gradient falls one meter per four hundred, which kept the water flowing. The appendix lists the tools involved.",+ "useful": true+ },+ {+ "title": "Potting diary",+ "text": "The bonsai fig drops leaves when moved, so repot only at the start of spring. A later section records what changed last season.",+ "useful": false+ }+ ]+ },+ {+ "id": "ri-012",+ "prompt": "What should I know about the windmill?",+ "notes": [+ {+ "title": "Baking log",+ "text": "The sourdough starter doubles in four hours when the kitchen stays above twenty degrees. This note is the working reference for it.",+ "useful": false+ },+ {+ "title": "Transit memo",+ "text": "The subway signal upgrade cuts headways to ninety seconds on the eastern line. A later section records what changed last season.",+ "useful": false+ },+ {+ "title": "History notes",+ "text": "The aqueduct gradient falls one meter per four hundred, which kept the water flowing. The appendix lists the tools involved.",+ "useful": false+ },+ {+ "title": "Restoration log",+ "text": "The windmill sails need tarring before the autumn storms, never in direct sun. Photos from the visit are filed separately.",+ "useful": true+ }+ ]+ },+ {+ "id": "ri-013",+ "prompt": "What should I know about the monsoon?",+ "notes": [+ {+ "title": "Climate primer",+ "text": "The monsoon arrives at the coast in June and reaches the plateau three weeks later. This note is the working reference for it.",+ "useful": true+ },+ {+ "title": "Transit memo",+ "text": "The subway signal upgrade cuts headways to ninety seconds on the eastern line. A later section records what changed last season.",+ "useful": false+ },+ {+ "title": "Restoration log",+ "text": "The windmill sails need tarring before the autumn storms, never in direct sun. The appendix lists the tools involved.",+ "useful": false+ },+ {+ "title": "Baking log",+ "text": "The sourdough starter doubles in four hours when the kitchen stays above twenty degrees. Photos from the visit are filed separately.",+ "useful": false+ }+ ]+ },+ {+ "id": "ri-014",+ "prompt": "What should I know about the hammock?",+ "notes": [+ {+ "title": "Restoration log",+ "text": "The windmill sails need tarring before the autumn storms, never in direct sun. The appendix lists the tools involved.",+ "useful": false+ },+ {+ "title": "Camp gear",+ "text": "The hammock ridgeline sag means the suspension needs shortening by one hand width. A later section records what changed last season.",+ "useful": true+ },+ {+ "title": "Aquarium guide",+ "text": "Moon jellyfish drift through the tank current and pulse when they meet the light. Photos from the visit are filed separately.",+ "useful": false+ },+ {+ "title": "Transit memo",+ "text": "The subway signal upgrade cuts headways to ninety seconds on the eastern line. This note is the working reference for it.",+ "useful": false+ }+ ]+ },+ {+ "id": "ri-015",+ "prompt": "What should I know about the planetarium?",+ "notes": [+ {+ "title": "Aquarium guide",+ "text": "Moon jellyfish drift through the tank current and pulse when they meet the light. Photos from the visit are filed separately.",+ "useful": false+ },+ {+ "title": "Apiary record",+ "text": "The beehive entrance reducer stays on until the colony draws out the second deep box. This note is the working reference for it.",+ "useful": false+ },+ {+ "title": "Show schedule",+ "text": "The planetarium dome show narrates the ecliptic twice nightly through winter. The appendix lists the tools involved.",+ "useful": true+ },+ {+ "title": "Restoration log",+ "text": "The windmill sails need tarring before the autumn storms, never in direct sun. A later section records what changed last season.",+ "useful": false+ }+ ]+ },+ {+ "id": "ri-016",+ "prompt": "What should I know about the kubernetes?",+ "notes": [+ {+ "title": "Coastal walk",+ "text": "The lighthouse keeper's cottage opens to visitors on the first Saturday of each month. This note is the working reference for it.",+ "useful": false+ },+ {+ "title": "Camp gear",+ "text": "The hammock ridgeline sag means the suspension needs shortening by one hand width. A later section records what changed last season.",+ "useful": false+ },+ {+ "title": "Observatory setup",+ "text": "The telescope needs forty minutes to reach thermal equilibrium before Saturn resolves. The appendix lists the tools involved.",+ "useful": false+ },+ {+ "title": "Cluster notes",+ "text": "The kubernetes cluster autoscaler adds nodes when pending pods wait longer than thirty seconds. Photos from the visit are filed separately.",+ "useful": true+ }+ ]+ },+ {+ "id": "ri-017",+ "prompt": "What should I know about the sourdough?",+ "notes": [+ {+ "title": "Baking log",+ "text": "The sourdough starter doubles in four hours when the kitchen stays above twenty degrees. This note is the working reference for it.",+ "useful": true+ },+ {+ "title": "Camp gear",+ "text": "The hammock ridgeline sag means the suspension needs shortening by one hand width. A later section records what changed last season.",+ "useful": false+ },+ {+ "title": "Field survey",+ "text": "The glacier terminus retreated twelve meters since the spring survey markers were placed. The appendix lists the tools involved.",+ "useful": false+ },+ {+ "title": "Coastal walk",+ "text": "The lighthouse keeper's cottage opens to visitors on the first Saturday of each month. Photos from the visit are filed separately.",+ "useful": false+ }+ ]+ },+ {+ "id": "ri-018",+ "prompt": "What should I know about the jellyfish?",+ "notes": [+ {+ "title": "Field survey",+ "text": "The glacier terminus retreated twelve meters since the spring survey markers were placed. The appendix lists the tools involved.",+ "useful": false+ },+ {+ "title": "Aquarium guide",+ "text": "Moon jellyfish drift through the tank current and pulse when they meet the light. A later section records what changed last season.",+ "useful": true+ },+ {+ "title": "Repair bench",+ "text": "The typewriter carriage sticks when the draw band loses tension, a ten minute fix. Photos from the visit are filed separately.",+ "useful": false+ },+ {+ "title": "Camp gear",+ "text": "The hammock ridgeline sag means the suspension needs shortening by one hand width. This note is the working reference for it.",+ "useful": false+ }+ ]+ },+ {+ "id": "ri-019",+ "prompt": "What should I know about the telescope?",+ "notes": [+ {+ "title": "Repair bench",+ "text": "The typewriter carriage sticks when the draw band loses tension, a ten minute fix. Photos from the visit are filed separately.",+ "useful": false+ },+ {+ "title": "Show schedule",+ "text": "The planetarium dome show narrates the ecliptic twice nightly through winter. This note is the working reference for it.",+ "useful": false+ },+ {+ "title": "Observatory setup",+ "text": "The telescope needs forty minutes to reach thermal equilibrium before Saturn resolves. The appendix lists the tools involved.",+ "useful": true+ },+ {+ "title": "Field survey",+ "text": "The glacier terminus retreated twelve meters since the spring survey markers were placed. A later section records what changed last season.",+ "useful": false+ }+ ]+ },+ {+ "id": "ri-020",+ "prompt": "What should I know about the glacier?",+ "notes": [+ {+ "title": "Show schedule",+ "text": "The planetarium dome show narrates the ecliptic twice nightly through winter. This note is the working reference for it.",+ "useful": false+ },+ {+ "title": "Potting diary",+ "text": "The bonsai fig drops leaves when moved, so repot only at the start of spring. A later section records what changed last season.",+ "useful": false+ },+ {+ "title": "Repair bench",+ "text": "The typewriter carriage sticks when the draw band loses tension, a ten minute fix. The appendix lists the tools involved.",+ "useful": false+ },+ {+ "title": "Field survey",+ "text": "The glacier terminus retreated twelve meters since the spring survey markers were placed. Photos from the visit are filed separately.",+ "useful": true+ }+ ]+ },+ {+ "id": "ri-021",+ "prompt": "What should I know about the bonsai?",+ "notes": [+ {+ "title": "Potting diary",+ "text": "The bonsai fig drops leaves when moved, so repot only at the start of spring. This note is the working reference for it.",+ "useful": true+ },+ {+ "title": "Field survey",+ "text": "The glacier terminus retreated twelve meters since the spring survey markers were placed. A later section records what changed last season.",+ "useful": false+ },+ {+ "title": "History notes",+ "text": "The aqueduct gradient falls one meter per four hundred, which kept the water flowing. The appendix lists the tools involved.",+ "useful": false+ },+ {+ "title": "Show schedule",+ "text": "The planetarium dome show narrates the ecliptic twice nightly through winter. Photos from the visit are filed separately.",+ "useful": false+ }+ ]+ },+ {+ "id": "ri-022",+ "prompt": "What should I know about the subway?",+ "notes": [+ {+ "title": "History notes",+ "text": "The aqueduct gradient falls one meter per four hundred, which kept the water flowing. The appendix lists the tools involved.",+ "useful": false+ },+ {+ "title": "Transit memo",+ "text": "The subway signal upgrade cuts headways to ninety seconds on the eastern line. A later section records what changed last season.",+ "useful": true+ },+ {+ "title": "Cluster notes",+ "text": "The kubernetes cluster autoscaler adds nodes when pending pods wait longer than thirty seconds. Photos from the visit are filed separately.",+ "useful": false+ },+ {+ "title": "Field survey",+ "text": "The glacier terminus retreated twelve meters since the spring survey markers were placed. This note is the working reference for it.",+ "useful": false+ }+ ]+ },+ {+ "id": "ri-023",+ "prompt": "What should I know about the beehive?",+ "notes": [+ {+ "title": "Cluster notes",+ "text": "The kubernetes cluster autoscaler adds nodes when pending pods wait longer than thirty seconds. Photos from the visit are filed separately.",+ "useful": false+ },+ {+ "title": "Potting diary",+ "text": "The bonsai fig drops leaves when moved, so repot only at the start of spring. This note is the working reference for it.",+ "useful": false+ },+ {+ "title": "Apiary record",+ "text": "The beehive entrance reducer stays on until the colony draws out the second deep box. The appendix lists the tools involved.",+ "useful": true+ },+ {+ "title": "History notes",+ "text": "The aqueduct gradient falls one meter per four hundred, which kept the water flowing. A later section records what changed last season.",+ "useful": false+ }+ ]+ },+ {+ "id": "ri-024",+ "prompt": "What should I know about the lighthouse?",+ "notes": [+ {+ "title": "Potting diary",+ "text": "The bonsai fig drops leaves when moved, so repot only at the start of spring. This note is the working reference for it.",+ "useful": false+ },+ {+ "title": "Restoration log",+ "text": "The windmill sails need tarring before the autumn storms, never in direct sun. A later section records what changed last season.",+ "useful": false+ },+ {+ "title": "Cluster notes",+ "text": "The kubernetes cluster autoscaler adds nodes when pending pods wait longer than thirty seconds. The appendix lists the tools involved.",+ "useful": false+ },+ {+ "title": "Coastal walk",+ "text": "The lighthouse keeper's cottage opens to visitors on the first Saturday of each month. Photos from the visit are filed separately.",+ "useful": true+ }+ ]+ },+ {+ "id": "ri-025",+ "prompt": "What should I know about the typewriter?",+ "notes": [+ {+ "title": "Repair bench",+ "text": "The typewriter carriage sticks when the draw band loses tension, a ten minute fix. This note is the working reference for it.",+ "useful": true+ },+ {+ "title": "Restoration log",+ "text": "The windmill sails need tarring before the autumn storms, never in direct sun. A later section records what changed last season.",+ "useful": false+ },+ {+ "title": "Baking log",+ "text": "The sourdough starter doubles in four hours when the kitchen stays above twenty degrees. The appendix lists the tools involved.",+ "useful": false+ },+ {+ "title": "Potting diary",+ "text": "The bonsai fig drops leaves when moved, so repot only at the start of spring. Photos from the visit are filed separately.",+ "useful": false+ }+ ]+ },+ {+ "id": "ri-026",+ "prompt": "What should I know about the aqueduct?",+ "notes": [+ {+ "title": "Baking log",+ "text": "The sourdough starter doubles in four hours when the kitchen stays above twenty degrees. The appendix lists the tools involved.",+ "useful": false+ },+ {+ "title": "History notes",+ "text": "The aqueduct gradient falls one meter per four hundred, which kept the water flowing. A later section records what changed last season.",+ "useful": true+ },+ {+ "title": "Transit memo",+ "text": "The subway signal upgrade cuts headways to ninety seconds on the eastern line. Photos from the visit are filed separately.",+ "useful": false+ },+ {+ "title": "Restoration log",+ "text": "The windmill sails need tarring before the autumn storms, never in direct sun. This note is the working reference for it.",+ "useful": false+ }+ ]+ },+ {+ "id": "ri-027",+ "prompt": "What should I know about the windmill?",+ "notes": [+ {+ "title": "Transit memo",+ "text": "The subway signal upgrade cuts headways to ninety seconds on the eastern line. Photos from the visit are filed separately.",+ "useful": false+ },+ {+ "title": "Climate primer",+ "text": "The monsoon arrives at the coast in June and reaches the plateau three weeks later. This note is the working reference for it.",+ "useful": false+ },+ {+ "title": "Restoration log",+ "text": "The windmill sails need tarring before the autumn storms, never in direct sun. The appendix lists the tools involved.",+ "useful": true+ },+ {+ "title": "Baking log",+ "text": "The sourdough starter doubles in four hours when the kitchen stays above twenty degrees. A later section records what changed last season.",+ "useful": false+ }+ ]+ },+ {+ "id": "ri-028",+ "prompt": "What should I know about the monsoon?",+ "notes": [+ {+ "title": "Restoration log",+ "text": "The windmill sails need tarring before the autumn storms, never in direct sun. This note is the working reference for it.",+ "useful": false+ },+ {+ "title": "Aquarium guide",+ "text": "Moon jellyfish drift through the tank current and pulse when they meet the light. A later section records what changed last season.",+ "useful": false+ },+ {+ "title": "Transit memo",+ "text": "The subway signal upgrade cuts headways to ninety seconds on the eastern line. The appendix lists the tools involved.",+ "useful": false+ },+ {+ "title": "Climate primer",+ "text": "The monsoon arrives at the coast in June and reaches the plateau three weeks later. Photos from the visit are filed separately.",+ "useful": true+ }+ ]+ },+ {+ "id": "ri-029",+ "prompt": "What should I know about the hammock?",+ "notes": [+ {+ "title": "Camp gear",+ "text": "The hammock ridgeline sag means the suspension needs shortening by one hand width. This note is the working reference for it.",+ "useful": true+ },+ {+ "title": "Aquarium guide",+ "text": "Moon jellyfish drift through the tank current and pulse when they meet the light. A later section records what changed last season.",+ "useful": false+ },+ {+ "title": "Apiary record",+ "text": "The beehive entrance reducer stays on until the colony draws out the second deep box. The appendix lists the tools involved.",+ "useful": false+ },+ {+ "title": "Restoration log",+ "text": "The windmill sails need tarring before the autumn storms, never in direct sun. Photos from the visit are filed separately.",+ "useful": false+ }+ ]+ }+ ]+}diff --git a/tests/fixtures/decision-model/rerank-take.json b/tests/fixtures/decision-model/rerank-take.jsonnew file mode 100644index 00000000..00ed3260--- /dev/null+++ b/tests/fixtures/decision-model/rerank-take.json@@ -0,0 +1,1124 @@+{+ "use": "rerank",+ "description": "Preregistered rerank take: 43 items, one relevant candidate each (relevance = the note whose body is about the queried subject), relevant position cycling 0-3 so the input order is wrong on three of every four items.",+ "items": [+ {+ "id": "rk-001",+ "query": "How do I look after the kubernetes?",+ "candidates": [+ {+ "title": "Cluster notes",+ "text": "The kubernetes cluster autoscaler adds nodes when pending pods wait longer than thirty seconds. This note is the working reference for it.",+ "relevant": true+ },+ {+ "title": "Aquarium guide",+ "text": "Moon jellyfish drift through the tank current and pulse when they meet the light. A later section records what changed last season.",+ "relevant": false+ },+ {+ "title": "Transit memo",+ "text": "The subway signal upgrade cuts headways to ninety seconds on the eastern line. The appendix lists the tools involved.",+ "relevant": false+ },+ {+ "title": "History notes",+ "text": "The aqueduct gradient falls one meter per four hundred, which kept the water flowing. Photos from the visit are filed separately.",+ "relevant": false+ }+ ]+ },+ {+ "id": "rk-002",+ "query": "How do I look after the sourdough?",+ "candidates": [+ {+ "title": "Repair bench",+ "text": "The typewriter carriage sticks when the draw band loses tension, a ten minute fix. The appendix lists the tools involved.",+ "relevant": false+ },+ {+ "title": "Baking log",+ "text": "The sourdough starter doubles in four hours when the kitchen stays above twenty degrees. A later section records what changed last season.",+ "relevant": true+ },+ {+ "title": "Camp gear",+ "text": "The hammock ridgeline sag means the suspension needs shortening by one hand width. Photos from the visit are filed separately.",+ "relevant": false+ },+ {+ "title": "Observatory setup",+ "text": "The telescope needs forty minutes to reach thermal equilibrium before Saturn resolves. This note is the working reference for it.",+ "relevant": false+ }+ ]+ },+ {+ "id": "rk-003",+ "query": "How do I look after the jellyfish?",+ "candidates": [+ {+ "title": "Baking log",+ "text": "The sourdough starter doubles in four hours when the kitchen stays above twenty degrees. Photos from the visit are filed separately.",+ "relevant": false+ },+ {+ "title": "Transit memo",+ "text": "The subway signal upgrade cuts headways to ninety seconds on the eastern line. This note is the working reference for it.",+ "relevant": false+ },+ {+ "title": "Aquarium guide",+ "text": "Moon jellyfish drift through the tank current and pulse when they meet the light. The appendix lists the tools involved.",+ "relevant": true+ },+ {+ "title": "History notes",+ "text": "The aqueduct gradient falls one meter per four hundred, which kept the water flowing. A later section records what changed last season.",+ "relevant": false+ }+ ]+ },+ {+ "id": "rk-004",+ "query": "How do I look after the telescope?",+ "candidates": [+ {+ "title": "Repair bench",+ "text": "The typewriter carriage sticks when the draw band loses tension, a ten minute fix. This note is the working reference for it.",+ "relevant": false+ },+ {+ "title": "Camp gear",+ "text": "The hammock ridgeline sag means the suspension needs shortening by one hand width. A later section records what changed last season.",+ "relevant": false+ },+ {+ "title": "Aquarium guide",+ "text": "Moon jellyfish drift through the tank current and pulse when they meet the light. The appendix lists the tools involved.",+ "relevant": false+ },+ {+ "title": "Observatory setup",+ "text": "The telescope needs forty minutes to reach thermal equilibrium before Saturn resolves. Photos from the visit are filed separately.",+ "relevant": true+ }+ ]+ },+ {+ "id": "rk-005",+ "query": "How do I look after the glacier?",+ "candidates": [+ {+ "title": "Field survey",+ "text": "The glacier terminus retreated twelve meters since the spring survey markers were placed. This note is the working reference for it.",+ "relevant": true+ },+ {+ "title": "Baking log",+ "text": "The sourdough starter doubles in four hours when the kitchen stays above twenty degrees. A later section records what changed last season.",+ "relevant": false+ },+ {+ "title": "Transit memo",+ "text": "The subway signal upgrade cuts headways to ninety seconds on the eastern line. The appendix lists the tools involved.",+ "relevant": false+ },+ {+ "title": "History notes",+ "text": "The aqueduct gradient falls one meter per four hundred, which kept the water flowing. Photos from the visit are filed separately.",+ "relevant": false+ }+ ]+ },+ {+ "id": "rk-006",+ "query": "How do I look after the bonsai?",+ "candidates": [+ {+ "title": "Repair bench",+ "text": "The typewriter carriage sticks when the draw band loses tension, a ten minute fix. The appendix lists the tools involved.",+ "relevant": false+ },+ {+ "title": "Potting diary",+ "text": "The bonsai fig drops leaves when moved, so repot only at the start of spring. A later section records what changed last season.",+ "relevant": true+ },+ {+ "title": "Camp gear",+ "text": "The hammock ridgeline sag means the suspension needs shortening by one hand width. Photos from the visit are filed separately.",+ "relevant": false+ },+ {+ "title": "Aquarium guide",+ "text": "Moon jellyfish drift through the tank current and pulse when they meet the light. This note is the working reference for it.",+ "relevant": false+ }+ ]+ },+ {+ "id": "rk-007",+ "query": "How do I look after the subway?",+ "candidates": [+ {+ "title": "Baking log",+ "text": "The sourdough starter doubles in four hours when the kitchen stays above twenty degrees. Photos from the visit are filed separately.",+ "relevant": false+ },+ {+ "title": "Potting diary",+ "text": "The bonsai fig drops leaves when moved, so repot only at the start of spring. This note is the working reference for it.",+ "relevant": false+ },+ {+ "title": "Transit memo",+ "text": "The subway signal upgrade cuts headways to ninety seconds on the eastern line. The appendix lists the tools involved.",+ "relevant": true+ },+ {+ "title": "History notes",+ "text": "The aqueduct gradient falls one meter per four hundred, which kept the water flowing. A later section records what changed last season.",+ "relevant": false+ }+ ]+ },+ {+ "id": "rk-008",+ "query": "How do I look after the beehive?",+ "candidates": [+ {+ "title": "Repair bench",+ "text": "The typewriter carriage sticks when the draw band loses tension, a ten minute fix. This note is the working reference for it.",+ "relevant": false+ },+ {+ "title": "Camp gear",+ "text": "The hammock ridgeline sag means the suspension needs shortening by one hand width. A later section records what changed last season.",+ "relevant": false+ },+ {+ "title": "Aquarium guide",+ "text": "Moon jellyfish drift through the tank current and pulse when they meet the light. The appendix lists the tools involved.",+ "relevant": false+ },+ {+ "title": "Apiary record",+ "text": "The beehive entrance reducer stays on until the colony draws out the second deep box. Photos from the visit are filed separately.",+ "relevant": true+ }+ ]+ },+ {+ "id": "rk-009",+ "query": "How do I look after the lighthouse?",+ "candidates": [+ {+ "title": "Coastal walk",+ "text": "The lighthouse keeper's cottage opens to visitors on the first Saturday of each month. This note is the working reference for it.",+ "relevant": true+ },+ {+ "title": "Baking log",+ "text": "The sourdough starter doubles in four hours when the kitchen stays above twenty degrees. A later section records what changed last season.",+ "relevant": false+ },+ {+ "title": "Potting diary",+ "text": "The bonsai fig drops leaves when moved, so repot only at the start of spring. The appendix lists the tools involved.",+ "relevant": false+ },+ {+ "title": "History notes",+ "text": "The aqueduct gradient falls one meter per four hundred, which kept the water flowing. Photos from the visit are filed separately.",+ "relevant": false+ }+ ]+ },+ {+ "id": "rk-010",+ "query": "How do I look after the typewriter?",+ "candidates": [+ {+ "title": "Coastal walk",+ "text": "The lighthouse keeper's cottage opens to visitors on the first Saturday of each month. The appendix lists the tools involved.",+ "relevant": false+ },+ {+ "title": "Repair bench",+ "text": "The typewriter carriage sticks when the draw band loses tension, a ten minute fix. A later section records what changed last season.",+ "relevant": true+ },+ {+ "title": "Camp gear",+ "text": "The hammock ridgeline sag means the suspension needs shortening by one hand width. Photos from the visit are filed separately.",+ "relevant": false+ },+ {+ "title": "Aquarium guide",+ "text": "Moon jellyfish drift through the tank current and pulse when they meet the light. This note is the working reference for it.",+ "relevant": false+ }+ ]+ },+ {+ "id": "rk-011",+ "query": "How do I look after the aqueduct?",+ "candidates": [+ {+ "title": "Baking log",+ "text": "The sourdough starter doubles in four hours when the kitchen stays above twenty degrees. Photos from the visit are filed separately.",+ "relevant": false+ },+ {+ "title": "Potting diary",+ "text": "The bonsai fig drops leaves when moved, so repot only at the start of spring. This note is the working reference for it.",+ "relevant": false+ },+ {+ "title": "History notes",+ "text": "The aqueduct gradient falls one meter per four hundred, which kept the water flowing. The appendix lists the tools involved.",+ "relevant": true+ },+ {+ "title": "Repair bench",+ "text": "The typewriter carriage sticks when the draw band loses tension, a ten minute fix. A later section records what changed last season.",+ "relevant": false+ }+ ]+ },+ {+ "id": "rk-012",+ "query": "How do I look after the windmill?",+ "candidates": [+ {+ "title": "Coastal walk",+ "text": "The lighthouse keeper's cottage opens to visitors on the first Saturday of each month. This note is the working reference for it.",+ "relevant": false+ },+ {+ "title": "Camp gear",+ "text": "The hammock ridgeline sag means the suspension needs shortening by one hand width. A later section records what changed last season.",+ "relevant": false+ },+ {+ "title": "Aquarium guide",+ "text": "Moon jellyfish drift through the tank current and pulse when they meet the light. The appendix lists the tools involved.",+ "relevant": false+ },+ {+ "title": "Restoration log",+ "text": "The windmill sails need tarring before the autumn storms, never in direct sun. Photos from the visit are filed separately.",+ "relevant": true+ }+ ]+ },+ {+ "id": "rk-013",+ "query": "How do I look after the monsoon?",+ "candidates": [+ {+ "title": "Climate primer",+ "text": "The monsoon arrives at the coast in June and reaches the plateau three weeks later. This note is the working reference for it.",+ "relevant": true+ },+ {+ "title": "Baking log",+ "text": "The sourdough starter doubles in four hours when the kitchen stays above twenty degrees. A later section records what changed last season.",+ "relevant": false+ },+ {+ "title": "Potting diary",+ "text": "The bonsai fig drops leaves when moved, so repot only at the start of spring. The appendix lists the tools involved.",+ "relevant": false+ },+ {+ "title": "Repair bench",+ "text": "The typewriter carriage sticks when the draw band loses tension, a ten minute fix. Photos from the visit are filed separately.",+ "relevant": false+ }+ ]+ },+ {+ "id": "rk-014",+ "query": "How do I look after the hammock?",+ "candidates": [+ {+ "title": "Coastal walk",+ "text": "The lighthouse keeper's cottage opens to visitors on the first Saturday of each month. The appendix lists the tools involved.",+ "relevant": false+ },+ {+ "title": "Camp gear",+ "text": "The hammock ridgeline sag means the suspension needs shortening by one hand width. A later section records what changed last season.",+ "relevant": true+ },+ {+ "title": "Climate primer",+ "text": "The monsoon arrives at the coast in June and reaches the plateau three weeks later. Photos from the visit are filed separately.",+ "relevant": false+ },+ {+ "title": "Aquarium guide",+ "text": "Moon jellyfish drift through the tank current and pulse when they meet the light. This note is the working reference for it.",+ "relevant": false+ }+ ]+ },+ {+ "id": "rk-015",+ "query": "How do I look after the planetarium?",+ "candidates": [+ {+ "title": "Baking log",+ "text": "The sourdough starter doubles in four hours when the kitchen stays above twenty degrees. Photos from the visit are filed separately.",+ "relevant": false+ },+ {+ "title": "Potting diary",+ "text": "The bonsai fig drops leaves when moved, so repot only at the start of spring. This note is the working reference for it.",+ "relevant": false+ },+ {+ "title": "Show schedule",+ "text": "The planetarium dome show narrates the ecliptic twice nightly through winter. The appendix lists the tools involved.",+ "relevant": true+ },+ {+ "title": "Repair bench",+ "text": "The typewriter carriage sticks when the draw band loses tension, a ten minute fix. A later section records what changed last season.",+ "relevant": false+ }+ ]+ },+ {+ "id": "rk-016",+ "query": "How do I look after the kubernetes?",+ "candidates": [+ {+ "title": "Repair bench",+ "text": "The typewriter carriage sticks when the draw band loses tension, a ten minute fix. This note is the working reference for it.",+ "relevant": false+ },+ {+ "title": "Camp gear",+ "text": "The hammock ridgeline sag means the suspension needs shortening by one hand width. A later section records what changed last season.",+ "relevant": false+ },+ {+ "title": "Observatory setup",+ "text": "The telescope needs forty minutes to reach thermal equilibrium before Saturn resolves. The appendix lists the tools involved.",+ "relevant": false+ },+ {+ "title": "Cluster notes",+ "text": "The kubernetes cluster autoscaler adds nodes when pending pods wait longer than thirty seconds. Photos from the visit are filed separately.",+ "relevant": true+ }+ ]+ },+ {+ "id": "rk-017",+ "query": "How do I look after the sourdough?",+ "candidates": [+ {+ "title": "Baking log",+ "text": "The sourdough starter doubles in four hours when the kitchen stays above twenty degrees. This note is the working reference for it.",+ "relevant": true+ },+ {+ "title": "Aquarium guide",+ "text": "Moon jellyfish drift through the tank current and pulse when they meet the light. A later section records what changed last season.",+ "relevant": false+ },+ {+ "title": "Transit memo",+ "text": "The subway signal upgrade cuts headways to ninety seconds on the eastern line. The appendix lists the tools involved.",+ "relevant": false+ },+ {+ "title": "History notes",+ "text": "The aqueduct gradient falls one meter per four hundred, which kept the water flowing. Photos from the visit are filed separately.",+ "relevant": false+ }+ ]+ },+ {+ "id": "rk-018",+ "query": "How do I look after the jellyfish?",+ "candidates": [+ {+ "title": "Repair bench",+ "text": "The typewriter carriage sticks when the draw band loses tension, a ten minute fix. The appendix lists the tools involved.",+ "relevant": false+ },+ {+ "title": "Aquarium guide",+ "text": "Moon jellyfish drift through the tank current and pulse when they meet the light. A later section records what changed last season.",+ "relevant": true+ },+ {+ "title": "Camp gear",+ "text": "The hammock ridgeline sag means the suspension needs shortening by one hand width. Photos from the visit are filed separately.",+ "relevant": false+ },+ {+ "title": "Observatory setup",+ "text": "The telescope needs forty minutes to reach thermal equilibrium before Saturn resolves. This note is the working reference for it.",+ "relevant": false+ }+ ]+ },+ {+ "id": "rk-019",+ "query": "How do I look after the telescope?",+ "candidates": [+ {+ "title": "Baking log",+ "text": "The sourdough starter doubles in four hours when the kitchen stays above twenty degrees. Photos from the visit are filed separately.",+ "relevant": false+ },+ {+ "title": "Transit memo",+ "text": "The subway signal upgrade cuts headways to ninety seconds on the eastern line. This note is the working reference for it.",+ "relevant": false+ },+ {+ "title": "Observatory setup",+ "text": "The telescope needs forty minutes to reach thermal equilibrium before Saturn resolves. The appendix lists the tools involved.",+ "relevant": true+ },+ {+ "title": "History notes",+ "text": "The aqueduct gradient falls one meter per four hundred, which kept the water flowing. A later section records what changed last season.",+ "relevant": false+ }+ ]+ },+ {+ "id": "rk-020",+ "query": "How do I look after the glacier?",+ "candidates": [+ {+ "title": "Repair bench",+ "text": "The typewriter carriage sticks when the draw band loses tension, a ten minute fix. This note is the working reference for it.",+ "relevant": false+ },+ {+ "title": "Camp gear",+ "text": "The hammock ridgeline sag means the suspension needs shortening by one hand width. A later section records what changed last season.",+ "relevant": false+ },+ {+ "title": "Aquarium guide",+ "text": "Moon jellyfish drift through the tank current and pulse when they meet the light. The appendix lists the tools involved.",+ "relevant": false+ },+ {+ "title": "Field survey",+ "text": "The glacier terminus retreated twelve meters since the spring survey markers were placed. Photos from the visit are filed separately.",+ "relevant": true+ }+ ]+ },+ {+ "id": "rk-021",+ "query": "How do I look after the bonsai?",+ "candidates": [+ {+ "title": "Potting diary",+ "text": "The bonsai fig drops leaves when moved, so repot only at the start of spring. This note is the working reference for it.",+ "relevant": true+ },+ {+ "title": "Baking log",+ "text": "The sourdough starter doubles in four hours when the kitchen stays above twenty degrees. A later section records what changed last season.",+ "relevant": false+ },+ {+ "title": "Transit memo",+ "text": "The subway signal upgrade cuts headways to ninety seconds on the eastern line. The appendix lists the tools involved.",+ "relevant": false+ },+ {+ "title": "History notes",+ "text": "The aqueduct gradient falls one meter per four hundred, which kept the water flowing. Photos from the visit are filed separately.",+ "relevant": false+ }+ ]+ },+ {+ "id": "rk-022",+ "query": "How do I look after the subway?",+ "candidates": [+ {+ "title": "Repair bench",+ "text": "The typewriter carriage sticks when the draw band loses tension, a ten minute fix. The appendix lists the tools involved.",+ "relevant": false+ },+ {+ "title": "Transit memo",+ "text": "The subway signal upgrade cuts headways to ninety seconds on the eastern line. A later section records what changed last season.",+ "relevant": true+ },+ {+ "title": "Camp gear",+ "text": "The hammock ridgeline sag means the suspension needs shortening by one hand width. Photos from the visit are filed separately.",+ "relevant": false+ },+ {+ "title": "Aquarium guide",+ "text": "Moon jellyfish drift through the tank current and pulse when they meet the light. This note is the working reference for it.",+ "relevant": false+ }+ ]+ },+ {+ "id": "rk-023",+ "query": "How do I look after the beehive?",+ "candidates": [+ {+ "title": "Baking log",+ "text": "The sourdough starter doubles in four hours when the kitchen stays above twenty degrees. Photos from the visit are filed separately.",+ "relevant": false+ },+ {+ "title": "Potting diary",+ "text": "The bonsai fig drops leaves when moved, so repot only at the start of spring. This note is the working reference for it.",+ "relevant": false+ },+ {+ "title": "Apiary record",+ "text": "The beehive entrance reducer stays on until the colony draws out the second deep box. The appendix lists the tools involved.",+ "relevant": true+ },+ {+ "title": "History notes",+ "text": "The aqueduct gradient falls one meter per four hundred, which kept the water flowing. A later section records what changed last season.",+ "relevant": false+ }+ ]+ },+ {+ "id": "rk-024",+ "query": "How do I look after the lighthouse?",+ "candidates": [+ {+ "title": "Repair bench",+ "text": "The typewriter carriage sticks when the draw band loses tension, a ten minute fix. This note is the working reference for it.",+ "relevant": false+ },+ {+ "title": "Camp gear",+ "text": "The hammock ridgeline sag means the suspension needs shortening by one hand width. A later section records what changed last season.",+ "relevant": false+ },+ {+ "title": "Aquarium guide",+ "text": "Moon jellyfish drift through the tank current and pulse when they meet the light. The appendix lists the tools involved.",+ "relevant": false+ },+ {+ "title": "Coastal walk",+ "text": "The lighthouse keeper's cottage opens to visitors on the first Saturday of each month. Photos from the visit are filed separately.",+ "relevant": true+ }+ ]+ },+ {+ "id": "rk-025",+ "query": "How do I look after the typewriter?",+ "candidates": [+ {+ "title": "Repair bench",+ "text": "The typewriter carriage sticks when the draw band loses tension, a ten minute fix. This note is the working reference for it.",+ "relevant": true+ },+ {+ "title": "Baking log",+ "text": "The sourdough starter doubles in four hours when the kitchen stays above twenty degrees. A later section records what changed last season.",+ "relevant": false+ },+ {+ "title": "Potting diary",+ "text": "The bonsai fig drops leaves when moved, so repot only at the start of spring. The appendix lists the tools involved.",+ "relevant": false+ },+ {+ "title": "History notes",+ "text": "The aqueduct gradient falls one meter per four hundred, which kept the water flowing. Photos from the visit are filed separately.",+ "relevant": false+ }+ ]+ },+ {+ "id": "rk-026",+ "query": "How do I look after the aqueduct?",+ "candidates": [+ {+ "title": "Coastal walk",+ "text": "The lighthouse keeper's cottage opens to visitors on the first Saturday of each month. The appendix lists the tools involved.",+ "relevant": false+ },+ {+ "title": "History notes",+ "text": "The aqueduct gradient falls one meter per four hundred, which kept the water flowing. A later section records what changed last season.",+ "relevant": true+ },+ {+ "title": "Camp gear",+ "text": "The hammock ridgeline sag means the suspension needs shortening by one hand width. Photos from the visit are filed separately.",+ "relevant": false+ },+ {+ "title": "Aquarium guide",+ "text": "Moon jellyfish drift through the tank current and pulse when they meet the light. This note is the working reference for it.",+ "relevant": false+ }+ ]+ },+ {+ "id": "rk-027",+ "query": "How do I look after the windmill?",+ "candidates": [+ {+ "title": "Baking log",+ "text": "The sourdough starter doubles in four hours when the kitchen stays above twenty degrees. Photos from the visit are filed separately.",+ "relevant": false+ },+ {+ "title": "Potting diary",+ "text": "The bonsai fig drops leaves when moved, so repot only at the start of spring. This note is the working reference for it.",+ "relevant": false+ },+ {+ "title": "Restoration log",+ "text": "The windmill sails need tarring before the autumn storms, never in direct sun. The appendix lists the tools involved.",+ "relevant": true+ },+ {+ "title": "Repair bench",+ "text": "The typewriter carriage sticks when the draw band loses tension, a ten minute fix. A later section records what changed last season.",+ "relevant": false+ }+ ]+ },+ {+ "id": "rk-028",+ "query": "How do I look after the monsoon?",+ "candidates": [+ {+ "title": "Coastal walk",+ "text": "The lighthouse keeper's cottage opens to visitors on the first Saturday of each month. This note is the working reference for it.",+ "relevant": false+ },+ {+ "title": "Camp gear",+ "text": "The hammock ridgeline sag means the suspension needs shortening by one hand width. A later section records what changed last season.",+ "relevant": false+ },+ {+ "title": "Aquarium guide",+ "text": "Moon jellyfish drift through the tank current and pulse when they meet the light. The appendix lists the tools involved.",+ "relevant": false+ },+ {+ "title": "Climate primer",+ "text": "The monsoon arrives at the coast in June and reaches the plateau three weeks later. Photos from the visit are filed separately.",+ "relevant": true+ }+ ]+ },+ {+ "id": "rk-029",+ "query": "How do I look after the hammock?",+ "candidates": [+ {+ "title": "Camp gear",+ "text": "The hammock ridgeline sag means the suspension needs shortening by one hand width. This note is the working reference for it.",+ "relevant": true+ },+ {+ "title": "Baking log",+ "text": "The sourdough starter doubles in four hours when the kitchen stays above twenty degrees. A later section records what changed last season.",+ "relevant": false+ },+ {+ "title": "Potting diary",+ "text": "The bonsai fig drops leaves when moved, so repot only at the start of spring. The appendix lists the tools involved.",+ "relevant": false+ },+ {+ "title": "Repair bench",+ "text": "The typewriter carriage sticks when the draw band loses tension, a ten minute fix. Photos from the visit are filed separately.",+ "relevant": false+ }+ ]+ },+ {+ "id": "rk-030",+ "query": "How do I look after the planetarium?",+ "candidates": [+ {+ "title": "Coastal walk",+ "text": "The lighthouse keeper's cottage opens to visitors on the first Saturday of each month. The appendix lists the tools involved.",+ "relevant": false+ },+ {+ "title": "Show schedule",+ "text": "The planetarium dome show narrates the ecliptic twice nightly through winter. A later section records what changed last season.",+ "relevant": true+ },+ {+ "title": "Climate primer",+ "text": "The monsoon arrives at the coast in June and reaches the plateau three weeks later. Photos from the visit are filed separately.",+ "relevant": false+ },+ {+ "title": "Aquarium guide",+ "text": "Moon jellyfish drift through the tank current and pulse when they meet the light. This note is the working reference for it.",+ "relevant": false+ }+ ]+ },+ {+ "id": "rk-031",+ "query": "How do I look after the kubernetes?",+ "candidates": [+ {+ "title": "Aquarium guide",+ "text": "Moon jellyfish drift through the tank current and pulse when they meet the light. Photos from the visit are filed separately.",+ "relevant": false+ },+ {+ "title": "Transit memo",+ "text": "The subway signal upgrade cuts headways to ninety seconds on the eastern line. This note is the working reference for it.",+ "relevant": false+ },+ {+ "title": "Cluster notes",+ "text": "The kubernetes cluster autoscaler adds nodes when pending pods wait longer than thirty seconds. The appendix lists the tools involved.",+ "relevant": true+ },+ {+ "title": "History notes",+ "text": "The aqueduct gradient falls one meter per four hundred, which kept the water flowing. A later section records what changed last season.",+ "relevant": false+ }+ ]+ },+ {+ "id": "rk-032",+ "query": "How do I look after the sourdough?",+ "candidates": [+ {+ "title": "Repair bench",+ "text": "The typewriter carriage sticks when the draw band loses tension, a ten minute fix. This note is the working reference for it.",+ "relevant": false+ },+ {+ "title": "Camp gear",+ "text": "The hammock ridgeline sag means the suspension needs shortening by one hand width. A later section records what changed last season.",+ "relevant": false+ },+ {+ "title": "Observatory setup",+ "text": "The telescope needs forty minutes to reach thermal equilibrium before Saturn resolves. The appendix lists the tools involved.",+ "relevant": false+ },+ {+ "title": "Baking log",+ "text": "The sourdough starter doubles in four hours when the kitchen stays above twenty degrees. Photos from the visit are filed separately.",+ "relevant": true+ }+ ]+ },+ {+ "id": "rk-033",+ "query": "How do I look after the jellyfish?",+ "candidates": [+ {+ "title": "Aquarium guide",+ "text": "Moon jellyfish drift through the tank current and pulse when they meet the light. This note is the working reference for it.",+ "relevant": true+ },+ {+ "title": "Baking log",+ "text": "The sourdough starter doubles in four hours when the kitchen stays above twenty degrees. A later section records what changed last season.",+ "relevant": false+ },+ {+ "title": "Transit memo",+ "text": "The subway signal upgrade cuts headways to ninety seconds on the eastern line. The appendix lists the tools involved.",+ "relevant": false+ },+ {+ "title": "History notes",+ "text": "The aqueduct gradient falls one meter per four hundred, which kept the water flowing. Photos from the visit are filed separately.",+ "relevant": false+ }+ ]+ },+ {+ "id": "rk-034",+ "query": "How do I look after the telescope?",+ "candidates": [+ {+ "title": "Repair bench",+ "text": "The typewriter carriage sticks when the draw band loses tension, a ten minute fix. The appendix lists the tools involved.",+ "relevant": false+ },+ {+ "title": "Observatory setup",+ "text": "The telescope needs forty minutes to reach thermal equilibrium before Saturn resolves. A later section records what changed last season.",+ "relevant": true+ },+ {+ "title": "Camp gear",+ "text": "The hammock ridgeline sag means the suspension needs shortening by one hand width. Photos from the visit are filed separately.",+ "relevant": false+ },+ {+ "title": "Aquarium guide",+ "text": "Moon jellyfish drift through the tank current and pulse when they meet the light. This note is the working reference for it.",+ "relevant": false+ }+ ]+ },+ {+ "id": "rk-035",+ "query": "How do I look after the glacier?",+ "candidates": [+ {+ "title": "Baking log",+ "text": "The sourdough starter doubles in four hours when the kitchen stays above twenty degrees. Photos from the visit are filed separately.",+ "relevant": false+ },+ {+ "title": "Transit memo",+ "text": "The subway signal upgrade cuts headways to ninety seconds on the eastern line. This note is the working reference for it.",+ "relevant": false+ },+ {+ "title": "Field survey",+ "text": "The glacier terminus retreated twelve meters since the spring survey markers were placed. The appendix lists the tools involved.",+ "relevant": true+ },+ {+ "title": "History notes",+ "text": "The aqueduct gradient falls one meter per four hundred, which kept the water flowing. A later section records what changed last season.",+ "relevant": false+ }+ ]+ },+ {+ "id": "rk-036",+ "query": "How do I look after the bonsai?",+ "candidates": [+ {+ "title": "Repair bench",+ "text": "The typewriter carriage sticks when the draw band loses tension, a ten minute fix. This note is the working reference for it.",+ "relevant": false+ },+ {+ "title": "Camp gear",+ "text": "The hammock ridgeline sag means the suspension needs shortening by one hand width. A later section records what changed last season.",+ "relevant": false+ },+ {+ "title": "Aquarium guide",+ "text": "Moon jellyfish drift through the tank current and pulse when they meet the light. The appendix lists the tools involved.",+ "relevant": false+ },+ {+ "title": "Potting diary",+ "text": "The bonsai fig drops leaves when moved, so repot only at the start of spring. Photos from the visit are filed separately.",+ "relevant": true+ }+ ]+ },+ {+ "id": "rk-037",+ "query": "How do I look after the subway?",+ "candidates": [+ {+ "title": "Transit memo",+ "text": "The subway signal upgrade cuts headways to ninety seconds on the eastern line. This note is the working reference for it.",+ "relevant": true+ },+ {+ "title": "Baking log",+ "text": "The sourdough starter doubles in four hours when the kitchen stays above twenty degrees. A later section records what changed last season.",+ "relevant": false+ },+ {+ "title": "Potting diary",+ "text": "The bonsai fig drops leaves when moved, so repot only at the start of spring. The appendix lists the tools involved.",+ "relevant": false+ },+ {+ "title": "History notes",+ "text": "The aqueduct gradient falls one meter per four hundred, which kept the water flowing. Photos from the visit are filed separately.",+ "relevant": false+ }+ ]+ },+ {+ "id": "rk-038",+ "query": "How do I look after the beehive?",+ "candidates": [+ {+ "title": "Repair bench",+ "text": "The typewriter carriage sticks when the draw band loses tension, a ten minute fix. The appendix lists the tools involved.",+ "relevant": false+ },+ {+ "title": "Apiary record",+ "text": "The beehive entrance reducer stays on until the colony draws out the second deep box. A later section records what changed last season.",+ "relevant": true+ },+ {+ "title": "Camp gear",+ "text": "The hammock ridgeline sag means the suspension needs shortening by one hand width. Photos from the visit are filed separately.",+ "relevant": false+ },+ {+ "title": "Aquarium guide",+ "text": "Moon jellyfish drift through the tank current and pulse when they meet the light. This note is the working reference for it.",+ "relevant": false+ }+ ]+ },+ {+ "id": "rk-039",+ "query": "How do I look after the lighthouse?",+ "candidates": [+ {+ "title": "Baking log",+ "text": "The sourdough starter doubles in four hours when the kitchen stays above twenty degrees. Photos from the visit are filed separately.",+ "relevant": false+ },+ {+ "title": "Potting diary",+ "text": "The bonsai fig drops leaves when moved, so repot only at the start of spring. This note is the working reference for it.",+ "relevant": false+ },+ {+ "title": "Coastal walk",+ "text": "The lighthouse keeper's cottage opens to visitors on the first Saturday of each month. The appendix lists the tools involved.",+ "relevant": true+ },+ {+ "title": "History notes",+ "text": "The aqueduct gradient falls one meter per four hundred, which kept the water flowing. A later section records what changed last season.",+ "relevant": false+ }+ ]+ },+ {+ "id": "rk-040",+ "query": "How do I look after the typewriter?",+ "candidates": [+ {+ "title": "Coastal walk",+ "text": "The lighthouse keeper's cottage opens to visitors on the first Saturday of each month. This note is the working reference for it.",+ "relevant": false+ },+ {+ "title": "Camp gear",+ "text": "The hammock ridgeline sag means the suspension needs shortening by one hand width. A later section records what changed last season.",+ "relevant": false+ },+ {+ "title": "Aquarium guide",+ "text": "Moon jellyfish drift through the tank current and pulse when they meet the light. The appendix lists the tools involved.",+ "relevant": false+ },+ {+ "title": "Repair bench",+ "text": "The typewriter carriage sticks when the draw band loses tension, a ten minute fix. Photos from the visit are filed separately.",+ "relevant": true+ }+ ]+ },+ {+ "id": "rk-041",+ "query": "How do I look after the aqueduct?",+ "candidates": [+ {+ "title": "History notes",+ "text": "The aqueduct gradient falls one meter per four hundred, which kept the water flowing. This note is the working reference for it.",+ "relevant": true+ },+ {+ "title": "Baking log",+ "text": "The sourdough starter doubles in four hours when the kitchen stays above twenty degrees. A later section records what changed last season.",+ "relevant": false+ },+ {+ "title": "Potting diary",+ "text": "The bonsai fig drops leaves when moved, so repot only at the start of spring. The appendix lists the tools involved.",+ "relevant": false+ },+ {+ "title": "Repair bench",+ "text": "The typewriter carriage sticks when the draw band loses tension, a ten minute fix. Photos from the visit are filed separately.",+ "relevant": false+ }+ ]+ },+ {+ "id": "rk-042",+ "query": "How do I look after the windmill?",+ "candidates": [+ {+ "title": "Coastal walk",+ "text": "The lighthouse keeper's cottage opens to visitors on the first Saturday of each month. The appendix lists the tools involved.",+ "relevant": false+ },+ {+ "title": "Restoration log",+ "text": "The windmill sails need tarring before the autumn storms, never in direct sun. A later section records what changed last season.",+ "relevant": true+ },+ {+ "title": "Camp gear",+ "text": "The hammock ridgeline sag means the suspension needs shortening by one hand width. Photos from the visit are filed separately.",+ "relevant": false+ },+ {+ "title": "Aquarium guide",+ "text": "Moon jellyfish drift through the tank current and pulse when they meet the light. This note is the working reference for it.",+ "relevant": false+ }+ ]+ },+ {+ "id": "rk-043",+ "query": "How do I look after the monsoon?",+ "candidates": [+ {+ "title": "Baking log",+ "text": "The sourdough starter doubles in four hours when the kitchen stays above twenty degrees. Photos from the visit are filed separately.",+ "relevant": false+ },+ {+ "title": "Potting diary",+ "text": "The bonsai fig drops leaves when moved, so repot only at the start of spring. This note is the working reference for it.",+ "relevant": false+ },+ {+ "title": "Climate primer",+ "text": "The monsoon arrives at the coast in June and reaches the plateau three weeks later. The appendix lists the tools involved.",+ "relevant": true+ },+ {+ "title": "Repair bench",+ "text": "The typewriter carriage sticks when the draw band loses tension, a ten minute fix. A later section records what changed last season.",+ "relevant": false+ }+ ]+ }+ ]+}diff --git a/tests/helpers/json-schema-subset.ts b/tests/helpers/json-schema-subset.tsindex 73bc5108..9c309b7c 100644--- a/tests/helpers/json-schema-subset.ts+++ b/tests/helpers/json-schema-subset.ts@@ -20,17 +20,26 @@ export type SchemaType = "object" | "array" | "string" | "integer" | "number" |export interface SchemaNode {readonly $schema?: string;readonly $id?: string;+ readonly $defs?: Readonly<Record<string, SchemaNode>>;readonly type?: SchemaType;readonly title?: string;readonly description?: string;readonly format?: "date-time";readonly minimum?: number;readonly maximum?: number;+ readonly minLength?: number;+ readonly maxLength?: number;+ readonly maxItems?: number;readonly enum?: ReadonlyArray<unknown>;readonly required?: ReadonlyArray<string>;readonly properties?: Readonly<Record<string, SchemaNode>>;readonly items?: SchemaNode;- readonly additionalProperties?: boolean;+ /**+ * The boolean form excludes unknown keys; the SCHEMA form validates each+ * unknown key against it (the search-query artifact's `properties` row+ * types its filter map this way).+ */+ readonly additionalProperties?: boolean | SchemaNode;}export interface SchemaValidationResult {@@ -41,12 +50,16 @@ export interface SchemaValidationResult {const SUPPORTED_KEYWORDS: ReadonlySet<string> = new Set(["$schema","$id",+ "$defs","type","title","description","format","minimum","maximum",+ "minLength",+ "maxLength",+ "maxItems","enum","required","properties",@@ -85,7 +98,10 @@ export function assertSupportedSchema(schema: unknown, path = ""): void {}const additional = schema["additionalProperties"];if (additional !== undefined && typeof additional !== "boolean") {- throw new Error(`${formatPath(path)}: additionalProperties must be a boolean here`);+ // The schema form is checked recursively below, like properties.+ if (!isRecord(additional)) {+ throw new Error(`${formatPath(path)}: additionalProperties must be a boolean or a schema`);+ }}const properties = schema["properties"];if (properties !== undefined) {@@ -94,7 +110,17 @@ export function assertSupportedSchema(schema: unknown, path = ""): void {assertSupportedSchema(child, appendPath(path, key));}}+ if (schema["$defs"] !== undefined) {+ const defs = schema["$defs"];+ if (!isRecord(defs)) throw new Error(`${formatPath(path)}: $defs must be an object`);+ for (const [name, child] of Object.entries(defs)) {+ assertSupportedSchema(child, appendPath(path, name));+ }+ }if (schema["items"] !== undefined) assertSupportedSchema(schema["items"], `${path}[]`);+ if (additional !== undefined && typeof additional !== "boolean") {+ assertSupportedSchema(additional, appendPath(path, "(additionalProperties)"));+ }}export function validateAgainstSchema(schema: SchemaNode, value: unknown): SchemaValidationResult {@@ -117,6 +143,14 @@ function validateNode(schema: SchemaNode, value: unknown, path: string, errors:if (schema.format === "date-time" && typeof value === "string") {if (!Number.isFinite(Date.parse(value))) errors.push(`${formatPath(path)} must be date-time`);}+ if (typeof value === "string") {+ if (schema.minLength !== undefined && value.length < schema.minLength) {+ errors.push(`${formatPath(path)} must be at least ${schema.minLength} character(s)`);+ }+ if (schema.maxLength !== undefined && value.length > schema.maxLength) {+ errors.push(`${formatPath(path)} must be at most ${schema.maxLength} character(s)`);+ }+ }if (typeof value === "number") {if (schema.minimum !== undefined && value < schema.minimum) {errors.push(`${formatPath(path)} must be >= ${schema.minimum}`);@@ -125,6 +159,9 @@ function validateNode(schema: SchemaNode, value: unknown, path: string, errors:errors.push(`${formatPath(path)} must be <= ${schema.maximum}`);}}+ if (Array.isArray(value) && schema.maxItems !== undefined && value.length > schema.maxItems) {+ errors.push(`${formatPath(path)} must have at most ${schema.maxItems} item(s)`);+ }if (schema.type === "object" && isRecord(value)) {const properties = schema.properties ?? {};for (const key of schema.required ?? []) {@@ -135,6 +172,8 @@ function validateNode(schema: SchemaNode, value: unknown, path: string, errors:if (childSchema === undefined) {if (schema.additionalProperties === false) {errors.push(`${formatPath(appendPath(path, key))} is not allowed`);+ } else if (typeof schema.additionalProperties === "object") {+ validateNode(schema.additionalProperties, child, appendPath(path, key), errors);}continue;}diff --git a/tests/mcp/context-pack-tool.test.ts b/tests/mcp/context-pack-tool.test.tsindex 6ee01123..c2905bc1 100644--- a/tests/mcp/context-pack-tool.test.ts+++ b/tests/mcp/context-pack-tool.test.ts@@ -12,10 +12,13 @@ import { join } from "node:path";import { JSONRPC_VERSION, MCPServer, PROTOCOL_VERSION } from "../../src/mcp/index.ts";import { buildToolTable } from "../../src/mcp/tools.ts";import { atomicWriteFileSync } from "../../src/core/fs-atomic.ts";+import { MODEL_CONTEXT_WINDOW_ENV_KEY } from "../../src/core/config.ts";import { CONTEXT_GUARD_PLACEHOLDER } from "../../src/core/brain/safety/context-guard.ts";import { brainConfigPath } from "../../src/core/brain/paths.ts";import { persistTension } from "../../src/core/brain/tensions.ts";import { BELIEF_VECTORS_BACKFILL_COMMAND } from "../../src/core/brain/context-pack.ts";+import { writePreference } from "../../src/core/brain/preference.ts";+import { BRAIN_CONFIDENCE, BRAIN_PREFERENCE_STATUS } from "../../src/core/brain/types.ts";import { LOCAL_EMBEDDING_MODEL } from "../../src/core/search/embeddings/signature.ts";import { EMBEDDING_PRICE_SOURCE } from "../../src/core/search/embeddings/pricing.ts";import { indexVault, resolveSearchConfig } from "../../src/core/search/index.ts";@@ -1053,3 +1056,345 @@ describe("brain_context_pack tool — semantic query mode", () => {},);});++/**+ * Derived budget (t_a567cc12): `max_tokens` is optional. When it is+ * omitted, the budget derives from the model context window the resolver+ * resolves - operator `context:` block, env override, or the caller's+ * `model` hint, in that precedence - through the matching preset's+ * `context_pack.max_tokens`. Explicit `max_tokens` stays first-class and+ * untouched; omission with nothing resolvable refuses exactly as before+ * (the pinned decision - never a silent default budget).+ */+describe("brain_context_pack tool — derived budget", () => {+ function writeOnePref(): void {+ writeFileSync(+ join(vault, "Brain", "preferences", "pref-core.md"),+ "---\nid: pref-core\ntopic: x\nprinciple: core principle\ntier: core\ncreated_at: 2026-05-01T00:00:00Z\n---\n",+ );+ }++ function writeBrainConfig(contents: string): void {+ atomicWriteFileSync(brainConfigPath(vault), contents);+ }++ test("a model hint derives the preset budget for the declared window", async () => {+ writeOnePref();+ const server = new MCPServer({ vault, configPath });+ await initialize(server);+ const out = await callPack(server, { model: "gpt-4o" });+ expect(out["max_tokens"]).toBe(24_000);+ expect(out["max_tokens_source"]).toBe("declared");+ expect((out["items"] as Array<{ id: string }>).map((i) => i.id)).toEqual(["pref-core"]);+ });++ test("a 1m-suffix model derives from the one-million window", async () => {+ writeOnePref();+ const server = new MCPServer({ vault, configPath });+ await initialize(server);+ const out = await callPack(server, { model: "qwen3-235b-1m" });+ expect(out["max_tokens"]).toBe(24_000);+ expect(out["max_tokens_source"]).toBe("suffix");+ });++ test("a hint-only model budgets the preset suggest answers for it", async () => {+ writeOnePref();+ const server = new MCPServer({ vault, configPath });+ await initialize(server);+ // "gemini-2.5-flash" is unknown to the declared table: the resolver+ // answers the default window, which used to budget long-context (24k)+ // while suggest answered the model's hint (tight-context, 4k). The+ // derivation applies the same hint fallback suggest uses, so one model+ // gets one mapping; the disclosed source stays the window's.+ const out = await callPack(server, { model: "gemini-2.5-flash" });+ expect(out["max_tokens"]).toBe(4_000);+ expect(out["max_tokens_source"]).toBe("default");+ });++ test("a table-known model still ignores its hint", async () => {+ writeOnePref();+ const server = new MCPServer({ vault, configPath });+ await initialize(server);+ // "gpt-4.1-mini" matches the "mini" hint AND the declared table: the+ // declared 1M window decides the budget, never the hint.+ const out = await callPack(server, { model: "gpt-4.1-mini" });+ expect(out["max_tokens"]).toBe(24_000);+ expect(out["max_tokens_source"]).toBe("declared");+ });++ test("an unrecognised model refuses the derived budget by name", async () => {+ writeOnePref();+ const server = new MCPServer({ vault, configPath });+ await initialize(server);+ // "llama3:8b" has no table row, no `-1m` suffix and no hint: the+ // derived budget used to answer the default window's long-context+ // 24k - about three times the model's whole 8k window. The refusal+ // is the conservative pre-derivation posture, naming the id and the+ // two remedies (an explicit `max_tokens` stays first-class).+ const r = (await server.handleRequest({+ jsonrpc: JSONRPC_VERSION,+ id: 15,+ method: "tools/call",+ params: { name: "brain_context_pack", arguments: { model: "llama3:8b" } },+ })) as { error?: { code: number; message: string } };+ expect(r.error?.code).toBe(-32602);+ expect(r.error!.message).toBe(+ "brain_context_pack: model 'llama3:8b' not recognised; pass max_tokens or set context.window_tokens",+ );+ });++ test("a whitespace-only model is absent: refused as nothing-resolvable", async () => {+ writeOnePref();+ const server = new MCPServer({ vault, configPath });+ await initialize(server);+ // A blank name is no name: the call refuses exactly as a call+ // without `model` does - the nothing-resolvable budget message, not+ // a model-argument complaint and never a derived default budget.+ const r = (await server.handleRequest({+ jsonrpc: JSONRPC_VERSION,+ id: 16,+ method: "tools/call",+ params: { name: "brain_context_pack", arguments: { model: " " } },+ })) as { error?: { code: number; message: string } };+ expect(r.error?.code).toBe(-32602);+ expect(r.error!.message).toBe("brain_context_pack: max_tokens must be a positive integer");+ });++ test("the operator context block resolves without a model", async () => {+ writeOnePref();+ writeBrainConfig("schema_version: 1\ncontext:\n window_tokens: 150000\n");+ const server = new MCPServer({ vault, configPath });+ await initialize(server);+ const out = await callPack(server, {});+ expect(out["max_tokens"]).toBe(24_000);+ expect(out["max_tokens_source"]).toBe("operator-config");+ });++ test("an out-of-band operator value passes through unclamped", async () => {+ writeOnePref();+ writeBrainConfig("schema_version: 1\ncontext:\n window_tokens: 5000000\n");+ const server = new MCPServer({ vault, configPath });+ await initialize(server);+ // A first-hand declaration passes through exactly as given (never+ // clamped into the band); 5M simply lands in the long-context bucket.+ const out = await callPack(server, {});+ expect(out["max_tokens"]).toBe(24_000);+ expect(out["max_tokens_source"]).toBe("operator-config");+ });++ test("the env channel resolves, and the operator block beats it", async () => {+ writeOnePref();+ const key = MODEL_CONTEXT_WINDOW_ENV_KEY;+ const previous = process.env[key];+ process.env[key] = "150000";+ try {+ const server = new MCPServer({ vault, configPath });+ await initialize(server);+ const fromEnv = await callPack(server, {});+ expect(fromEnv["max_tokens"]).toBe(24_000);+ expect(fromEnv["max_tokens_source"]).toBe("operator-env");++ writeBrainConfig("schema_version: 1\ncontext:\n window_tokens: 32000\n");+ const server2 = new MCPServer({ vault, configPath });+ await initialize(server2);+ // The operator block wins over the env channel: the disclosed+ // source flips. The declared 32k window passes through unclamped+ // now, so it sizes tight-context (4k) against the env channel's+ // long-context (24k) instead of both clamping into one preset.+ const fromConfig = await callPack(server2, {});+ expect(fromConfig["max_tokens"]).toBe(4_000);+ expect(fromConfig["max_tokens_source"]).toBe("operator-config");+ } finally {+ if (previous === undefined) delete process.env[key];+ else process.env[key] = previous;+ }+ });++ test("omission with nothing resolvable refuses exactly as before", async () => {+ writeOnePref();+ const server = new MCPServer({ vault, configPath });+ await initialize(server);+ const r = (await server.handleRequest({+ jsonrpc: JSONRPC_VERSION,+ id: 13,+ method: "tools/call",+ params: { name: "brain_context_pack", arguments: {} },+ })) as { error?: { code: number; message: string } };+ expect(r.error?.code).toBe(-32602);+ expect(r.error!.message).toBe("brain_context_pack: max_tokens must be a positive integer");+ });++ test("explicit max_tokens stays first-class and discloses nothing", async () => {+ writeOnePref();+ const server = new MCPServer({ vault, configPath });+ await initialize(server);+ const out = await callPack(server, { model: "gpt-4o", max_tokens: 1_000 });+ expect(out["max_tokens"]).toBe(1_000);+ expect(out["max_tokens_source"]).toBeUndefined();+ });++ test("the schema declares the optional budget and the derivation", () => {+ const tool = buildToolTable("full").find((t) => t.name === "brain_context_pack")!;+ const schema = tool.inputSchema as {+ properties: Record<string, { description?: string }>;+ required?: ReadonlyArray<string>;+ };+ expect(schema.required ?? []).not.toContain("max_tokens");+ expect(schema.properties["max_tokens"]!.description).toContain("derives");+ expect(schema.properties["model"]!.description).toContain("context window");+ });+});++/**+ * Derived caps (t_a567cc12): the pre-compress addendum's character caps+ * were unbounded when absent. With a resolvable window they now derive+ * from the matching preset's `pre_compress` block; nothing resolvable+ * keeps the historical unbounded addendum; explicit caps stay first-class.+ */+describe("brain_pre_compress_pack tool — derived caps", () => {+ const LONG_PRINCIPLE = "never deploy on a friday afternoon".padEnd(2_400, " filler");++ function seedTwoLongConfirmedPreferences(): void {+ writePreference(vault, {+ slug: "pref-long-a",+ topic: "deploy",+ principle: LONG_PRINCIPLE,+ created_at: "2026-05-01T00:00:00Z",+ unconfirmed_until: "2026-05-08T00:00:00Z",+ status: BRAIN_PREFERENCE_STATUS.confirmed,+ evidenced_by: ["[[sig-a]]"],+ confirmed_at: "2026-05-02T00:00:00Z",+ applied_count: 1,+ violated_count: 0,+ last_evidence_at: "2026-05-02T00:00:00Z",+ confidence: BRAIN_CONFIDENCE.high,+ confidence_value: 0.9,+ });+ writePreference(vault, {+ slug: "pref-long-b",+ topic: "deploy",+ principle: LONG_PRINCIPLE,+ created_at: "2026-05-01T00:00:00Z",+ unconfirmed_until: "2026-05-08T00:00:00Z",+ status: BRAIN_PREFERENCE_STATUS.confirmed,+ evidenced_by: ["[[sig-b]]"],+ confirmed_at: "2026-05-02T00:00:00Z",+ applied_count: 1,+ violated_count: 0,+ last_evidence_at: "2026-05-02T00:00:00Z",+ confidence: BRAIN_CONFIDENCE.high,+ confidence_value: 0.8,+ });+ }++ async function callPreCompress(+ server: MCPServer,+ args: Record<string, unknown>,+ ): Promise<Record<string, unknown>> {+ const r = (await server.handleRequest({+ jsonrpc: JSONRPC_VERSION,+ id: 14,+ method: "tools/call",+ params: { name: "brain_pre_compress_pack", arguments: args },+ })) as { result: { content: ReadonlyArray<{ type: string; text: string }> } };+ return JSON.parse(r.result.content[0]!.text);+ }++ test("a resolved window bounds the addendum with the preset caps", async () => {+ seedTwoLongConfirmedPreferences();+ const server = new MCPServer({ vault, configPath });+ await initialize(server);+ const out = await callPreCompress(server, { model: "gpt-4o" });+ const items = out["items"] as Array<{ principle: string; trimmed: boolean }>;+ expect(items).toHaveLength(2);+ // The long-context preset caps each entry at 2000 code points.+ for (const item of items) {+ expect(item.trimmed).toBe(true);+ expect(item.principle.length).toBe(2_000);+ }+ expect(out["total_chars"]).toBeLessThanOrEqual(16_000);+ });++ test("a hint-only model derives tight caps, the mapping the pack budgets", async () => {+ seedTwoLongConfirmedPreferences();+ const server = new MCPServer({ vault, configPath });+ await initialize(server);+ // "gemini-2.5-flash" is unknown to the declared table: the resolver+ // answers the default window, and the pack budgets its hint+ // (tight-context, 4k). The pre-compress caps answer from the SAME+ // mapping - tight's 800/4000 - never from the default window's+ // long-context caps the raw window bucket would name.+ const out = await callPreCompress(server, { model: "gemini-2.5-flash" });+ const items = out["items"] as Array<{ principle: string; trimmed: boolean }>;+ expect(items).toHaveLength(2);+ // The tight-context preset caps each entry at 800 code points.+ for (const item of items) {+ expect(item.trimmed).toBe(true);+ expect(item.principle.length).toBe(800);+ }+ expect(out["total_chars"]).toBeLessThanOrEqual(4_000);+ });++ test("nothing resolvable keeps the unbounded addendum", async () => {+ seedTwoLongConfirmedPreferences();+ const server = new MCPServer({ vault, configPath });+ await initialize(server);+ const out = await callPreCompress(server, {});+ const items = out["items"] as Array<{ principle: string; trimmed: boolean }>;+ expect(items).toHaveLength(2);+ for (const item of items) {+ expect(item.trimmed).toBe(false);+ expect(item.principle).toBe(LONG_PRINCIPLE);+ }+ });++ test("a malformed window env degrades to the unbounded addendum with a warning", async () => {+ seedTwoLongConfirmedPreferences();+ const key = MODEL_CONTEXT_WINDOW_ENV_KEY;+ const previous = process.env[key];+ process.env[key] = "200k";+ try {+ const server = new MCPServer({ vault, configPath });+ await initialize(server);+ // The call SUCCEEDS: on this path an unparseable env value is+ // nothing resolvable, so the historical unbounded caps stand - it+ // used to rethrow as INVALID_PARAMS blaming the caller's+ // parameters, losing the addendum over an operator typo the caller+ // cannot see.+ const out = await callPreCompress(server, {});+ const items = out["items"] as Array<{ principle: string; trimmed: boolean }>;+ expect(items).toHaveLength(2);+ for (const item of items) {+ expect(item.trimmed).toBe(false);+ expect(item.principle).toBe(LONG_PRINCIPLE);+ }+ // A named warning says which channel misread - never the value.+ const warning = out["window_warning"] as string | undefined;+ expect(typeof warning).toBe("string");+ expect(warning).toContain("OPEN_SECOND_BRAIN_MODEL_CONTEXT_WINDOW");+ expect(warning).not.toContain("200k");+ } finally {+ if (previous === undefined) delete process.env[key];+ else process.env[key] = previous;+ }+ });++ test("explicit caps stay first-class beside a resolvable window", async () => {+ seedTwoLongConfirmedPreferences();+ const server = new MCPServer({ vault, configPath });+ await initialize(server);+ const out = await callPreCompress(server, { model: "gpt-4o", max_chars_per_memory: 50 });+ const items = out["items"] as Array<{ principle: string; trimmed: boolean }>;+ for (const item of items) {+ expect(item.trimmed).toBe(true);+ expect(item.principle.length).toBe(50);+ }+ });++ test("the schema declares the optional model and the derivation", () => {+ const tool = buildToolTable("full").find((t) => t.name === "brain_pre_compress_pack")!;+ const schema = tool.inputSchema as { properties: Record<string, { description?: string }> };+ expect(schema.properties["model"]!.description).toContain("context window");+ expect(schema.properties["max_chars_per_memory"]!.description).toContain("resolves");+ });+});diff --git a/tests/mcp/context-presets-tool.test.ts b/tests/mcp/context-presets-tool.test.tsindex d7649f14..27c8b314 100644--- a/tests/mcp/context-presets-tool.test.ts+++ b/tests/mcp/context-presets-tool.test.ts@@ -72,4 +72,50 @@ describe("brain_context_presets tool", () => {preserved_overrides: [{ path: "context_pack.max_tokens", current: 9000, preset: 4000 }],});});++ test("a model-only suggest resolves the window and discloses the source", async () => {+ await expect(callPresets({ operation: "suggest", model: "gpt-4o" })).resolves.toMatchObject({+ preset_id: "long-context",+ confidence: "high",+ reason: "context window 128000 tokens resolved from declared matched long-context",+ });+ // Unknown model, no hint: nothing published places the id, so the+ // conservative fallback answers - the same tight-context/low answer a+ // model-free call gets. The pack budget surfaces refuse the same id+ // instead of budgeting the default window's long-context.+ await expect(callPresets({ operation: "suggest", model: "kimi-k2" })).resolves.toMatchObject({+ preset_id: "tight-context",+ confidence: "low",+ reason: "no model or context-window hint matched; using conservative default",+ });+ // The disagreeing-model case: "gpt-4.1-mini" matches the "mini" hint+ // AND the declared table. The suggestion must name the long-context+ // mapping the pack budget derives from, not the hint's tight-context.+ await expect(+ callPresets({ operation: "suggest", model: "gpt-4.1-mini" }),+ ).resolves.toMatchObject({+ preset_id: "long-context",+ confidence: "high",+ reason: "context window 1000000 tokens resolved from declared matched long-context",+ });+ // No model and no window keeps the conservative fallback.+ await expect(callPresets({ operation: "suggest" })).resolves.toMatchObject({+ preset_id: "tight-context",+ confidence: "low",+ });+ });++ test("a hint-only model answers its hint, the mapping the pack budget derives", async () => {+ // "gemini-2.5-flash" is unknown to the declared table: the resolver+ // answers the default window, but the hint decides on BOTH surfaces -+ // this suggest answer and the pack budget derivation that applies the+ // same fallback when the resolver's source is "default".+ await expect(+ callPresets({ operation: "suggest", model: "gemini-2.5-flash" }),+ ).resolves.toMatchObject({+ preset_id: "tight-context",+ confidence: "high",+ reason: "model hint matched tight-context",+ });+ });});diff --git a/tests/mcp/recall-adequacy-pairing.test.ts b/tests/mcp/recall-adequacy-pairing.test.tsindex bcfa7e26..9bf1b48d 100644--- a/tests/mcp/recall-adequacy-pairing.test.ts+++ b/tests/mcp/recall-adequacy-pairing.test.ts@@ -115,6 +115,15 @@ function sampleFor(prop: Schema): unknown {/*** The smallest payload a tool accepts, so the refusal under test is the* pairing's and not a missing unrelated argument's.+ *+ * Required properties are sampled from their own schema. Optional+ * integer/number properties join too, at their documented minimum: a+ * tool may refuse to invent a value for a budget knob while still+ * declaring it optional (`brain_context_pack.max_tokens` derives from+ * the model window or refuses), and the derivation refusal must not be+ * mistaken for the pairing's. Strings, booleans and arrays stay out -+ * those switch modes, and a sampled mode can demand companions of its+ * own.*/function minimalArgs(schema: Schema): Record<string, unknown> {const props = properties(schema);@@ -125,6 +134,18 @@ function minimalArgs(schema: Schema): Record<string, unknown> {if (prop === undefined) throw new Error(`required arg ${key} has no property schema`);args[key] = sampleFor(prop);}+ const scoresKey = scoresKeyOf(schema);+ for (const [key, prop] of Object.entries(props)) {+ if (key in args) continue;+ // The pairing's own halves are the subject of the test, never part of+ // the base payload - and `match_quality` is a number, so without this+ // exclusion the numeric sweep below would complete every "incomplete"+ // pair before the cases under test even ran.+ if (key === MATCH_QUALITY_ARG_NAME || key === scoresKey) continue;+ if (prop["type"] === "integer" || prop["type"] === "number") {+ args[key] = sampleFor(prop);+ }+ }return args;}diff --git a/uv.lock b/uv.lockindex f60d5e7a..3017564a 100644--- a/uv.lock+++ b/uv.lock@@ -4,5 +4,5 @@ requires-python = ">=3.11"[[package]]name = "open-second-brain"-version = "1.89.0"+version = "1.90.0"source = { editable = "." }