Skip to content

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

TypeScript

feat(search): Recall Trust Suite - relation polarity, learned weights, time-aware and verified recall (#64)

Sol Aitkenc494fd8ba24d
diff --git a/.claude-plugin/plugin.json b/.claude-plugin/plugin.json
index 9cef56e6..6e493f74 100644
--- a/.claude-plugin/plugin.json
+++ b/.claude-plugin/plugin.json
@@ -1,6 +1,6 @@
{
"name": "open-second-brain",
- "version": "0.32.1",
+ "version": "0.33.0",
"description": "Plugin-first second brain package for AI agents and humans.",
"author": {
"name": "Open Second Brain contributors"
diff --git a/.codex-plugin/plugin.json b/.codex-plugin/plugin.json
index 988fe99d..c2a93651 100644
--- a/.codex-plugin/plugin.json
+++ b/.codex-plugin/plugin.json
@@ -1,6 +1,6 @@
{
"name": "open-second-brain",
- "version": "0.32.1",
+ "version": "0.33.0",
"description": "Plugin-first second brain package for Codex, Hermes, Claude Code, OpenClaw, and other agent runtimes.",
"skills": "./skills",
"hooks": "./hooks/hooks.json",
diff --git a/.gitignore b/.gitignore
index 64dd831f..2085cc2a 100644
--- a/.gitignore
+++ b/.gitignore
@@ -24,3 +24,4 @@ node_modules/
sandbox-vault/
.codegraph/
.orphaned_at
+.claude/scheduled_tasks.lock
diff --git a/CHANGELOG.md b/CHANGELOG.md
index 5c7f83db..ffe55a52 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -5,6 +5,59 @@ 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).
+## [0.33.0] - 2026-06-02
+
+Recall Trust Suite: five features that make recall something an agent can
+trust β€” typed relations carry ranking polarity, ranking weights learn from
+explicit feedback within audited bounds, recall scopes by time, evidence packs
+verify multi-record coverage with IDF weighting, and a completeness verdict
+guards against false-absence claims. All deterministic; no LLM in the core
+path.
+
+### Added
+
+- **Relation-aware recall polarity.** Typed relation edges
+ (`superseded_by` / `contradicts` / `related` / `extends` / `depends_on` /
+ `refines`) now participate in ranking: a matched `superseded_by`
+ predecessor is demoted and its successor boosted or pulled into the result
+ window; `contradicts` adds warning-style `why_retrieved` reasons on both
+ endpoints without a score change; positive relations grant a small bounded
+ boost between co-retrieved pages. History mode (`--include-superseded`,
+ MCP `include_superseded`) keeps predecessors undemoted. Kill switch:
+ `search_relation_polarity_enabled` /
+ `OPEN_SECOND_BRAIN_SEARCH_RELATION_POLARITY` (default on; vaults without
+ typed relations rank identically either way).
+- **Retrieval feedback loop with learned recall weights.** `o2b search
+ feedback --query <q> --result <path> --verdict up|down` and the new MCP
+ tool `brain_recall_feedback` record one JSON event per feedback under
+ `Brain/search/feedback/` (the conflict-free one-file-per-signal pattern).
+ A deterministic, order-insensitive fold derives per-layer multipliers
+ bounded to [0.8, 1.2] into `Brain/search/learned-weights.json`; ranking
+ applies them only behind the `search_learned_weights_enabled` opt-in, and
+ affected results carry a `learned_weights:` reason. `o2b search weights`
+ shows base + learned + bounds; `--reset` drops the derived file while
+ keeping events. The weights state is part of the query-cache key.
+- **Time-aware recall.** `--since` / `--until` on `o2b search` and
+ `since` / `until` on MCP `brain_search` accept ISO dates and datetimes,
+ `today` / `yesterday` / `last week` / `last month`, and `24h` / `7d` /
+ `2w` shorthand, resolved deterministically in UTC and filtered on document
+ mtime before ranking. Invalid input fails with `INVALID_INPUT`;
+ time-filtered queries bypass the query cache.
+- **Verified multi-record recall.** Evidence packs gain a coverage engine:
+ IDF-weighted support coverage, rare-term classification (document
+ frequency within 2% of the corpus), a rare-term abstention gate, and a
+ bounded per-token recall union (`union_records`, up to 2 records per
+ uncovered term / 8 total) so evidence spanning multiple records is visible
+ even when the AND-joined primary ranking returns nothing. Completes the
+ verified-recall scope started by the v0.27.0 evidence-pack foundation.
+- **Search-completeness guard.** Evidence packs carry a deterministic
+ `completeness` verdict (`complete` at 0.8+ IDF-weighted coverage,
+ `partial` at 0.4+, else `sparse`) and a false-absence guard:
+ `uncovered_but_present_in_corpus` lists every uncovered term the corpus
+ does contain, including the zero-results case, so a downstream summarizer
+ cannot honestly claim the vault has nothing on a term that sits in an
+ unreturned page.
+
## [0.32.1] - 2026-06-02
### Changed
@@ -3857,6 +3910,7 @@ plugin config (vault field)`, and exits with a clear
- Sandbox vault and plugin manifest fixtures for tests.
- GitHub release workflow for tag-based and manually dispatched releases.
+[0.33.0]: https://github.com/itechmeat/open-second-brain/compare/v0.32.1...v0.33.0
[0.32.1]: https://github.com/itechmeat/open-second-brain/compare/v0.32.0...v0.32.1
[0.32.0]: https://github.com/itechmeat/open-second-brain/compare/v0.31.2...v0.32.0
[0.31.2]: https://github.com/itechmeat/open-second-brain/compare/v0.31.1...v0.31.2
diff --git a/README.md b/README.md
index 0f3cae22..19d111ee 100644
--- a/README.md
+++ b/README.md
@@ -109,12 +109,12 @@ The capabilities you actually feel day to day:
| 6 | Browse and govern your memory schema | `o2b brain explorer` opens a force-directed HTML graph of every rule, every link, every retirement. Preference files can declare typed relationships such as `depends_on:` and `refines:`, plus `memory_layer` / `memory_branch` labels and optional `schema_type:` taxonomy metadata; `o2b brain schema` stats, lint, graph, explain, orphans, and apply audit and mutate those tokens through locked, audited writes. Double-click a node β€” Obsidian opens the underlying note. |
| 7 | Undo the agent if it gets it wrong | Every Brain mutation lands a verified snapshot before touching anything. One command (`o2b brain rollback <id>`) restores yesterday's state, and drift detection refuses to clobber unintended local edits. |
| 8 | Pin, merge, retire by hand | When a rule is wrong, you fix it. `o2b brain pin` keeps a good one safe from auto-retire, `merge` folds duplicates, `reject` puts a bad rule in the bin with a reason. The CLI is the operator's seat. |
-| 9 | Hybrid search that explains itself | `o2b search "<query>" --property type=decision --property status=open --evidence-pack` β€” SQLite + FTS5 and an optional semantic layer, with CJK-aware token expansion for unspaced Chinese/Japanese/Korean text. Recall is sharpened by MMR diversity, link-graph traversal, entity boosting, structured query lanes, session focus, and header-anchored chunking; opt-in evidence packs show matched/missing terms, abstention text, terminal-state downranks, and `why_retrieved` reasons. |
+| 9 | Hybrid search that explains itself | `o2b search "<query>" --property type=decision --property status=open --evidence-pack --since 7d` β€” SQLite + FTS5 and an optional semantic layer, with CJK-aware token expansion for unspaced Chinese/Japanese/Korean text. Recall is sharpened by MMR diversity, link-graph traversal, entity boosting, structured query lanes, session focus, and header-anchored chunking; typed relations carry recall polarity (a `superseded_by` predecessor is demoted below its successor, `contradicts` warns without endorsing); `--since` / `--until` scope recall by time; `o2b search feedback` trains bounded, auditable learned weights; opt-in evidence packs show matched/missing terms, IDF-weighted coverage, per-token union records, a completeness verdict with a false-absence guard, abstention text, terminal-state downranks, and `why_retrieved` reasons. |
| 10 | Pay Memory β€” audit every paid action | When the agent spends money (Solana-Foundation `pay`, third-party APIs) every receipt lands in `Brain/payments/<date>/`. Spending policy, approval gate, daily Telegram report. The agent never holds wallet keys. |
These are the headline capabilities. The full surface also includes: importing Claude Code memory directories, daily logging-discipline cron with a complexity-to-thinking warning, cross-project pointers for shared vaults, transient pinned session context through `brain_pinned_context` / `Brain/pinned.md`, source-agent query and comparison (`brain_agent_query`, `brain_agent_diff`, `o2b brain agent-query`, `o2b brain agent-diff`), the codegraph partner skill, vault hygiene lints, per-MOC coverage audit, concept synthesis, an operator dashboard, configurable Markdown-link presentation output, MCP output-contract checks for core agent-facing tools, private-region stripping with `<private>...</private>`, the v0.12.0 Brain Integrity Suite (content-hash drift detection, durable workrun checkpoints, destructive-from-confirmed retire gate, and the `brain_review_candidates` MCP tool that previews what the next dream pass would do without writing anything), the v0.13.0 Hybrid Search and Recall Quality suite (explainable recall, MMR diversity, link-graph traversal, entity-boosted retrieval, header-anchored chunking), the v0.14.0 Semantic Brain Health and Self-Maintenance suite (cross-preference contradiction detection, concept-gap and stale-claim surfacing, per-preference edit-history, a clean/watch/investigate reconciliation verdict via `brain_health`, and dependency-ordered `doctor --remediate`), the v0.17.0 Brain Lifecycle Review Suite (`intent-review`, `retention`, `monthly`, lifecycle schemas, and discipline complexity ratio), and the v0.18.0 MCP context economy (a per-tool preview budget that returns a bounded inline preview and parks the full payload in a vault-local artifact the agent fetches on demand with `brain_artifact_get`, plus a `recall_hint` one-liner on search results), and the v0.19.0 typed graph semantics (typed frontmatter relationships - `related` / `extends` / `contradicts` / `superseded_by` - that surface inline on search results, a `visibility:` scoping axis for `brain_search`, and a `brain_mcp_landscape` view of the Model Context Protocol servers configured across the vault), and the v0.20.0 Recall and Ranking Quality suite (a configurable Weibull recency-decay curve, structural query-intent classification that re-weights ranking by query shape, language-agnostic synonym expansion via local co-occurrence, per-memory and total recall character budgets for `brain_context_pack`, a persistent query cache that self-invalidates on a corpus-generation change, and a `brain_pre_compress_pack` tool that returns a budgeted top-preferences addendum for a host runtime to inject before context compression), and the v0.21.0 Brain Lifecycle Suite (a per-preference mutation audit trail keyed by preference id - create / promote / update / retire / merge with revision + content-hash before/after, via `o2b brain audit` and `brain_audit`; a multi-phase `dream` pipeline that names its close / reconcile / synthesize / heal / log seams and reports a structured per-phase summary without rewriting the proven internals; deterministic reconcile-phase domain classification that buckets contradictions into claims / entity / decisions / source-freshness, auto-resolves only the decisive source-freshness case, and surfaces the rest as open questions instead of forcing a merge; a budgeted `o2b brain morning-brief` / `brain_morning_brief` session-start summary of top preferences, recent open questions, and recent notes; language-agnostic ISO-8601 temporal extraction that fills preference validity windows from signal text; and opt-in heal-phase vault enrichment that links exact title mentions across user pages), and the v0.22.0 Vault portability + session economy suite (a deterministic lossless session codec - `expand(compress(x)) === x` for all input, opt-in on the signal store and exposed as `o2b brain codec`; an `o2b brain sources` / `brain_sources` read-only dashboard of signals by agent and source type; vault-map `{{role}}` tokens resolved via an optional `Brain/_vault-map.yaml` and wired into scan-inline read paths and graph import; named multi-vault profiles with `o2b vault profile` + a `brain_switch_vault` tool, activated by a pointer in config; and `o2b brain graph-export` / `graph-import` for moving a vault's knowledge graph between layouts with skip/overwrite/merge conflict modes). Browse [`docs/cli-reference.md`](docs/cli-reference.md) for every verb and [`docs/how-it-works.md`](docs/how-it-works.md) for the mental model.
-The v0.26.0 surface adds audited schema mutation/admin tools, real-time lifecycle capture hooks for prompt markers and `brain_feedback` tool calls, CJK-aware FTS recall, and `brain_watchdog` / `o2b brain watchdog` recovery probes. The v0.27.0 surface adds recall-control and trust tools: structured search query documents, session focus, MCP `brain_recall_gate`, polarity-aware context lanes, and opt-in evidence packs for CLI/MCP search. The v0.28.0 surface adds a deterministic prompt-injection guard for automatically surfaced Brain context, agent-blind `$secret:NAME` references, and preview foundations for source-scoped forget, privacy-scanned knowledge packs, and oversized payload externalization. The v0.29.0 surface adds opt-in context receipts and recall telemetry, read-only context budget presets, pre-compaction extraction, and a continuity-backed session recall DAG.
+The v0.26.0 surface adds audited schema mutation/admin tools, real-time lifecycle capture hooks for prompt markers and `brain_feedback` tool calls, CJK-aware FTS recall, and `brain_watchdog` / `o2b brain watchdog` recovery probes. The v0.27.0 surface adds recall-control and trust tools: structured search query documents, session focus, MCP `brain_recall_gate`, polarity-aware context lanes, and opt-in evidence packs for CLI/MCP search. The v0.28.0 surface adds a deterministic prompt-injection guard for automatically surfaced Brain context, agent-blind `$secret:NAME` references, and preview foundations for source-scoped forget, privacy-scanned knowledge packs, and oversized payload externalization. The v0.29.0 surface adds opt-in context receipts and recall telemetry, read-only context budget presets, pre-compaction extraction, and a continuity-backed session recall DAG. The v0.33.0 surface adds the Recall Trust Suite: relation-aware recall polarity for typed memory edges, an explicit retrieval feedback loop with bounded learned weights (`o2b search feedback` / `weights`, MCP `brain_recall_feedback`), time-aware recall (`--since` / `--until` with natural-language ranges), verified multi-record recall (per-token union records, IDF-weighted coverage, rare-term abstention), and a search-completeness verdict with a false-absence guard.
## CLI
@@ -143,6 +143,9 @@ o2b vault profile switch work # Activate a named multi-vault profile
o2b brain agent-query --agent claude --json # Source-agent provenance query
o2b brain agent-diff --mode diff --agent claude --agent codex
o2b search "<query>" --evidence-pack # FTS5/hybrid search with matched/missing evidence
+o2b search "<query>" --since 7d --until today # Time-scoped recall (mtime window)
+o2b search feedback --query "<q>" --result note.md --verdict up # Train learned recall weights
+o2b search weights --json # Inspect base + learned ranking weights
o2b search focus set --query "current task" --path Notes/Project
o2b secrets list --json # Inspect $secret:NAME references without printing values
o2b help --json # Machine-readable command/flag manifest
diff --git a/docs/brainstorm/recall-trust-suite/cli-output/claude.md b/docs/brainstorm/recall-trust-suite/cli-output/claude.md
new file mode 100644
index 00000000..ea370f60
--- /dev/null
+++ b/docs/brainstorm/recall-trust-suite/cli-output/claude.md
@@ -0,0 +1,37 @@
+### Variant 1: Independent feature modules
+- **Approach**: Implement each of the five features as a self-contained module gated by its own config flag, wired into the orchestrator at its natural seam (A/B into `ranker.ts`, C/E into `evidence-pack.ts`, D into candidate filtering + CLI/MCP schema). No shared abstraction is introduced; each feature owns its own helpers, including separate "significant term" and coverage logic for C and E.
+- **Trade-offs**:
+ - Pro: Each commit maps cleanly to one kanban task; trivial to TDD and revert in isolation.
+ - Pro: Lowest blast radius β€” a flag-off feature touches nothing else; default behavior trivially stable.
+ - Pro: No early refactor of shared internals, so review stays localized.
+ - Con: C (rare-term gate / IDF coverage) and E (top-N term coverage) independently reimplement term-significance and coverage matrices, risking divergent verdicts on the same query.
+ - Con: B's learned-weight path and A's relation layer both mutate the weight profile without a shared contract, inviting subtle ordering bugs.
+ - Con: Duplication accrues as future trust features land.
+- **Complexity**: medium
+- **Risk**: low
+
+### Variant 2: Shared trust substrate first
+- **Approach**: Land foundational primitives in the early commits β€” a term-signal engine (significant-term extraction, per-token record union, IDF statistics, coverage matrix) plus a relation-signal resolver β€” then implement all five features as thin consumers of that substrate. C, E, and the rare-term gate all read one coverage matrix; A and B feed one scoring-context object.
+- **Trade-offs**:
+ - Pro: Single source of truth for "significant/rare term" and coverage; C and E verdicts are guaranteed consistent.
+ - Pro: Cleanest long-term architecture; future trust features extend the substrate cheaply.
+ - Pro: Centralized determinism/auditing surface aligns with the `why_retrieved` philosophy.
+ - Con: The first commits are foundation, not kanban tasks β€” breaks the clean one-commit-per-feature mapping and the TDD-per-task framing.
+ - Con: Largest upfront refactor of `ranker.ts`/`evidence-pack.ts` internals; higher chance of perturbing stable default behavior or the config-fingerprint cache key.
+ - Con: Bigger, harder-to-review diff before any user-visible feature lands.
+- **Complexity**: large
+- **Risk**: medium
+
+### Variant 3: Two-phase layering (pre-rank signals vs post-rank verification overlay)
+- **Approach**: Split the suite along the existing pipeline. A pre-rank "signal injection" group β€” A (relation polarity into the ranker), B (learned weights into weight resolution), D (time constraint into candidate filtering) β€” shares the weight-profile/candidate path. A post-rank "verification overlay" group β€” C (per-token union + IDF + rare-term gate) and E (completeness verdict) β€” shares one coverage engine built over the final candidate set in the evidence-pack stage. Sharing is introduced only where features genuinely overlap (C+E coverage), not globally.
+- **Trade-offs**:
+ - Pro: Each feature remains its own atomic, TDD'd commit while C and E still share the one place they truly overlap.
+ - Pro: Maps onto real pipeline seams (rank vs evidence-pack post-pass), so the scoping is self-documenting and defaults stay isolated per group.
+ - Pro: Avoids Variant 2's foundation-first commit and Variant 1's C/E duplication.
+ - Con: Two coupling boundaries to keep clean (weight-profile contract; coverage engine), more design thought than Variant 1.
+ - Con: The shared coverage engine still lands inside whichever of C/E is built first, so commit ordering carries a small dependency.
+- **Complexity**: medium
+- **Risk**: low-medium
+
+### Recommended: Variant 3
+**Rationale**: It honors the hard constraints β€” atomic per-feature commits, opt-in additive features, stable defaults β€” while consolidating the one substantive overlap (C's IDF/rare-term coverage and E's completeness audit both need a per-token coverage matrix) so the two cannot produce contradictory verdicts. It fits the existing orchestrator seams (pre-rank scoring vs evidence-pack post-pass) without Variant 2's risky foundation-first refactor of the cache-fingerprinted ranking core, and avoids the duplication and drift that Variant 1 would bake into the trust layer.
diff --git a/docs/brainstorm/recall-trust-suite/cli-output/prompt.md b/docs/brainstorm/recall-trust-suite/cli-output/prompt.md
new file mode 100644
index 00000000..be742ce1
--- /dev/null
+++ b/docs/brainstorm/recall-trust-suite/cli-output/prompt.md
@@ -0,0 +1,111 @@
+You are brainstorming architectural variants for the following task. Do not write code. Do not write a final design. Only produce variants and a recommendation.
+
+# Task
+
+One multi-task PR ("Recall Trust Suite") bundling five kanban tasks that all extend the Open Second Brain search/recall stack. The theme: recall an agent can trust β€” relation-aware ranking, auditable learned weights, verified multi-record evidence, time-scoped queries, and completeness guards.
+
+## Feature A β€” Relation-aware recall for typed memory edges (t_d8571bf0, P3)
+
+Open Second Brain already has typed graph relations (`related`, `extends`, `depends_on`, `refines`, `contradicts`, `superseded_by`) declared in page frontmatter and surfaced in search results, but they do not participate in ranking. Add a relation-polarity layer:
+
+- `superseded_by` is a stale-predecessor signal: when the predecessor matches, pull in and boost the successor; demote the predecessor unless the query explicitly asks for history.
+- `contradicts` is relevant-but-not-endorsing: surface the contradicting artifact with warning-style explanation, no positive graph halo.
+- `depends_on`, `extends`, `refines` are directional positive relevance with weaker weights than direct text match.
+- `why_retrieved` gains reasons like `superseded by <id>`, `contradicted by <id>`, `refines matched memory`.
+- History-oriented flows must still be able to include predecessors without demotion.
+- Deterministic, transparent, conservative defaults, no LLM dependency. Default behavior stays stable for vaults without typed relations.
+
+## Feature B β€” Retrieval feedback loop for learned recall weights (t_68e1b774, P3)
+
+Search weights (keyword, semantic, link, entity, recency, intent) are currently configured statically. Add optional recall-feedback capture and a deterministic learned-weight update path:
+
+- Lightweight feedback artifact or JSONL sidecar for recall events: query hash, selected/dismissed result IDs, explicit thumbs-up/down, scoring contributions at retrieval time.
+- CLI (`o2b search feedback`) and MCP (`brain_recall_feedback`) surfaces for explicit feedback.
+- Deterministic, bounded per-layer adjustments; learned weights stored separately from configured defaults; both visible in diagnostics.
+- Reset/freeze controls; operator config remains base policy; learned weights cannot drift outside documented limits.
+- No reinforcement learning, no opaque training, opt-in only.
+
+## Feature C β€” Full verified multi-record recall (t_407a3477, P2, follow-up of merged PR #54)
+
+PR #54 shipped evidence packs (matched/missing terms, support coverage, abstention field, per-record `why_retrieved`, terminal-state downrank, CLI `--evidence-pack`, MCP `evidence_pack`). The remaining upstream scope:
+
+- Per-token multi-record recall union β€” gather records covering each significant query token, not just the top-ranked set, so evidence can span multiple records.
+- IDF verifier β€” weight term coverage by inverse document frequency when judging support.
+- Rare-term gate β€” require rare/high-signal terms to be covered before answering, else abstain (populate the existing abstention field).
+
+## Feature D β€” Time-aware recall with natural-language time ranges (t_9dfbaa76, P2)
+
+Recall queries cannot be scoped by time today. Add since/until parameters accepting ISO timestamps, relative phrases (yesterday, last week), and duration shorthand (7d, 24h, 2w):
+
+- Wire through CLI search flags and the MCP brain_search tool schema.
+- Filter or constrain candidates by document mtime/frontmatter date during ranking.
+- There is no existing natural-language date parsing utility in the repo; one must be added (deterministic, no external dependency preferred).
+
+## Feature E β€” Search-completeness guard (t_854b8e5f, P1)
+
+No guard verifies that retrieval adequately covered the query. Add a deterministic search-completeness check: audit whether top-N results cover the significant query terms, expose a completeness verdict/metric in search output (and evidence pack), so downstream summarizers can detect false-absence claims and incomplete retrieval. No LLM verification β€” deterministic coverage auditing only.
+
+# Project context
+
+Open Second Brain β€” TypeScript on Bun. Obsidian-compatible Markdown vault as memory store; SQLite FTS5 search index with optional semantic embeddings; CLI (`o2b`) + MCP server surfaces for connected agents (Claude Code, Codex, Hermes).
+
+Recent commits:
+23ff4fb refactor(hermes): single intentional self-bootstrap for the plugin entrypoint (#63)
+0952dfc feat: become a native Hermes memory provider (#62)
+6fbab0b feat: hands-off post-upgrade migration (v0.31.2) (#61)
+496dd2d fix: make plugin updates self-healing (v0.31.1) (#60)
+09c0592 chore(release): v0.31.0 (#59)
+b81335c Feat/procedural attention suite (#58)
+1f3a218 Feat/self learning skill proposals (#57)
+0162d13 feat(brain): add context continuity and receipts suite (#56)
+3b7b3a5 feat(brain): add safety governance foundations (#55)
+794ee45 feat(search): ship recall control and trust surfaces (#54)
+40d4e2b feat: cjk schema lifecycle recovery (#53)
+
+Related files:
+- src/core/search/search.ts (orchestrator: FTS -> semantic -> hydrate -> rank -> MMR -> traversal -> property filter -> evidence pack; config fingerprint for query cache at :61)
+- src/core/search/ranker.ts (RankerInputs/RankerOptions; layered score: keyword+semantic*tier + entity + link + recency + sessionFocus; buildReasons -> why_retrieved)
+- src/core/search/evidence-pack.ts (EvidenceRecord/EvidencePack: matchedTerms, missingTerms, supportCoverage, terminalState, abstention)
+- src/core/search/traversal.ts (link-graph BFS expansion with hop decay)
+- src/core/search/recency.ts (Weibull decay: shape/scale/amplitude)
+- src/core/search/query-plan.ts (intent classification -> WeightProfile multipliers)
+- src/core/search/types.ts (SearchOptions, BrainSearchResult.relations, ResolvedRecallConfig)
+- src/core/search/index.ts (resolveSearchConfig: env + config.yaml + _brain.yaml)
+- src/core/graph/relation-vocab.ts (DEFAULT_RELATION_TYPES), src/core/graph/frontmatter-relations.ts (frontmatter extraction)
+- src/core/search/schema.ts (SQLite schema; links table has no relation column β€” frontmatter relations computed at query time)
+- src/cli/search.ts (o2b search query|index|reindex|status|check|focus)
+- src/mcp/search-tools.ts (brain_search MCP tool schema; recall telemetry wiring)
+- src/core/brain/recall-telemetry.ts (emitRecallTelemetry -> continuity JSONL store; precedent for feedback capture)
+- tests/core/search/*.test.ts (bun:test; createTempVault/writeMd/makeConfig fixtures)
+
+Conventions:
+- Bun runtime; bun test; oxlint + oxfmt; `bun run validate` = typecheck + lint + test.
+- Conventional commits; one PR = one CHANGELOG version (may bundle several features).
+- Deterministic core: brain features avoid LLM calls in the core path; everything auditable and explainable (why_retrieved pattern).
+- Search config resolved from env > config.yaml > defaults; static recall config is fingerprinted into the query cache key.
+- MCP tools are read-only on the search surface; index management is CLI-only.
+- Prior suites shipped as multi-feature PRs: search-recall-suite (#46-ish), recall-ranking-suite (#47), recall-control-trust-suite (#54).
+
+Constraints:
+- Do not change existing public API shapes (BrainSearchResult fields may gain optional fields, not change existing ones).
+- No new external runtime dependencies.
+- Default search behavior must remain stable for users who do not opt in (feedback loop, time filters, completeness guard are additive; relation-aware ranking needs conservative defaults).
+- All five features in one PR on one branch, implemented sequentially via TDD, atomic commits per feature.
+- SQLite schema changes must come with index-version bump / rebuild path (existing pattern).
+
+# 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/recall-trust-suite/design.md b/docs/brainstorm/recall-trust-suite/design.md
new file mode 100644
index 00000000..2763f05b
--- /dev/null
+++ b/docs/brainstorm/recall-trust-suite/design.md
@@ -0,0 +1,200 @@
+# Recall Trust Suite β€” recall an agent can trust
+
+**Status:** draft
+**Author:** claude-dev-agent (via feature-release-playbook)
+**Audience:** implementation
+**Kanban:** epic t_e9aebbc8; children t_d8571bf0, t_68e1b774, t_407a3477, t_9dfbaa76, t_854b8e5f
+**Chosen variant:** Variant 3 β€” two-phase layering (see `variants.md`)
+
+## Problem statement
+
+Open Second Brain search explains *why* a result surfaced (`why_retrieved`)
+but cannot yet be *trusted* on four axes: typed relations
+(`superseded_by`, `contradicts`) are surfaced but do not affect ranking, so a
+stale superseded memory can outrank its successor; ranking weights are static
+and cannot learn from operator feedback; evidence packs (PR #54) judge term
+support without frequency weighting, so a result matching only common words
+looks as supported as one matching the rare, high-signal term; and recall
+cannot be scoped by time, nor can a downstream summarizer detect that
+retrieval failed to cover the query. The suite closes all four gaps with
+deterministic, auditable mechanics β€” no LLM in the core path.
+
+## Scope
+
+Five features, two pipeline groups (Variant 3):
+
+**Pre-rank signal group**
+
+- **A. Relation-aware recall** (t_d8571bf0): typed relation edges get recall
+ polarity. `superseded_by` demotes the matched predecessor and pulls in /
+ boosts its successor; `contradicts` surfaces with a warning-style reason and
+ no positive halo; `depends_on` / `extends` / `refines` / `related` give a
+ small bounded directional boost between co-retrieved candidates. New
+ `why_retrieved` reasons. Opt-out for history-oriented queries.
+- **B. Retrieval feedback loop** (t_68e1b774): explicit per-result feedback
+ events (CLI `o2b search feedback`, MCP `brain_recall_feedback`) recorded as
+ one JSON file per event under `Brain/search/feedback/` (the conflict-free
+ inbox pattern). A deterministic, bounded computation derives per-layer
+ learned multipliers from accumulated events into
+ `Brain/search/learned-weights.json`. Opt-in via config; reset and freeze
+ controls; weights and provenance visible via `o2b search weights`.
+- **D. Time-aware recall** (t_9dfbaa76): `since` / `until` query parameters
+ accepting ISO dates, relative phrases (`yesterday`, `last week`), and
+ duration shorthand (`24h`, `7d`, `2w`). Deterministic parser module; filter
+ on indexed document mtime; CLI flags and MCP schema fields.
+
+**Post-rank verification group**
+
+- **C. Verified multi-record recall** (t_407a3477, follow-up of PR #54): a
+ shared coverage engine (`coverage.ts`) computing per-term postings over the
+ result set and corpus document frequency (IDF) from the FTS index. On top of
+ it: per-token recall union (fetch a bounded number of extra records for
+ significant terms the ranked set left uncovered), IDF-weighted support
+ coverage, and a rare-term gate that populates the existing `abstention`
+ field when a rare, high-signal term is uncovered. All scoped under the
+ existing opt-in `evidence_pack` mode.
+- **E. Search-completeness guard** (t_854b8e5f): a deterministic completeness
+ verdict (`complete` / `partial` / `sparse`) over the returned results,
+ computed from the same coverage engine, plus a false-absence guard: when
+ results are empty (or a term is uncovered) but the corpus *does* contain
+ matches for it, the pack says so explicitly. Shipped inside the evidence
+ pack (the trust surface added by PR #54).
+
+## Out of scope
+
+- LLM-based verification of summaries against sources (the upstream
+ obsidian-second-brain guard idea is reduced to its deterministic core).
+- Frontmatter date fields as the time-filter source (mtime only; frontmatter
+ dates can extend later without schema changes).
+- Implicit feedback capture (only explicit feedback events in this PR;
+ downstream tools may call the same MCP tool later).
+- Reinforcement learning or any non-deterministic weight training.
+- SQLite schema changes (IDF and relation edges are computed from existing
+ tables at query time; no index-version bump).
+- Cross-vault recall, entity registry, log sharding (other kanban tasks).
+
+## Chosen approach
+
+Variant 3 (two-phase layering). The pre-rank group injects signals at the
+seams `search.ts` already exposes: relation polarity runs as a bounded
+post-rank adjustment pass over the assembled candidate pool (it needs the
+ranked set to know which predecessors matched); learned weights resolve into
+the existing `WeightProfile` multiplier contract; the time filter prunes
+hydrated candidates before ranking. The post-rank group extends the
+`evidencePack === true` post-pass: `coverage.ts` is the single source of truth
+for significant terms, per-term postings, and IDF; both the C verifier and the
+E verdict read it, so they can never disagree on what "covered" means.
+
+Pipeline after the change (additions in brackets):
+
+```
+FTS β†’ semantic β†’ hydrate β†’ [D: time filter] β†’ rank ([B: learned multipliers])
+ β†’ traversal β†’ MMR β†’ property/visibility
+ β†’ [A: relation polarity adjust] β†’ slice β†’ relations attach
+ β†’ evidence pack ([C: union + IDF + rare-term gate] β†’ [E: completeness])
+```
+
+## Design decisions
+
+- **A runs post-rank, pre-slice, not inside `rankResults`.** The ranker is a
+ pure function with no I/O; relation edges need a store query
+ (`typedRelationEdgesForDocuments`, new). Running the polarity pass over the
+ assembled pool (before the final `limit` slice; the existing
+ relations-attach step for output stays after the slice) keeps the ranker
+ pure and lets a pulled-in successor compete for the final window while a
+ demoted predecessor can fall out of it. Demotion is a
+ bounded multiplier (`0.6`) on the predecessor's score unless
+ `includeSuperseded` is set; successor pull-in reuses the traversal
+ representative-chunk mechanism with `searchType: "link"`.
+- **A is on by default with conservative constants.** Vaults without typed
+ relations are bit-identical (the pass no-ops on zero edges) β€” that satisfies
+ the stability acceptance criterion. `search_relation_polarity_enabled`
+ config (default `true`) provides the kill switch, folded into the config
+ fingerprint so the query cache invalidates.
+- **A reasons vocabulary:** `superseded_by: <target>` (on the demoted
+ predecessor), `supersedes_matched: <path>` (on the boosted/pulled successor),
+ `contradicts: <target>` / `contradicted_by: <path>` (warning-style, score
+ untouched), `relation_boost: <relation> <path>` (positive relations).
+- **B stores feedback as one file per event** under
+ `Brain/search/feedback/<ts>-<hash>.json` β€” mirrors the `Brain/inbox/`
+ conflict-free pattern (a per-day shared JSONL would recreate the Syncthing
+ conflict bug t_6d52641f documents). Learned weights are a pure fold over the
+ event set: per layer, `multiplier = clamp(1 + step * netSignal /
+ totalEvents, 0.8, 1.2)` with `step = 0.5`; documented bounds, deterministic
+ replay, `o2b search weights --reset` deletes the derived file (events stay),
+ config `search_learned_weights_enabled` (default `false`, opt-in per task)
+ freezes/unfreezes. The learned multipliers compose with the intent
+ `WeightProfile` by multiplication and are clamped after composition.
+- **B cache integration:** the learned-weights file hash joins the config
+ fingerprint, so feedback-driven changes invalidate cached outcomes.
+- **B explanation:** when active and non-neutral, every result gains one
+ reason `learned_weights: kw=<x> sem=<x> ent=<x> rec=<x>` (only non-1.0
+ entries listed); `o2b search weights` prints base config, learned
+ multipliers, event counts, and bounds.
+- **C/E live entirely under `evidence_pack: true`.** PR #54 made the evidence
+ pack the opt-in trust surface; the union fetch and IDF queries cost extra
+ store reads, so they stay off the default path. `EvidencePack` gains only
+ optional fields (`idfWeightedCoverage`, `rareTerms`, `uncoveredRareTerms`,
+ `unionRecords`, `completeness`) β€” additive, no field changes.
+- **IDF from the live FTS index, no schema change:** document frequency per
+ significant term via one FTS query per term (bounded by the significant-term
+ cap), `idf = ln(1 + N / (1 + df))`. Rare-term threshold: `df <= max(1,
+ 0.02 * N)` β€” a term in at most 2% of documents is high-signal.
+- **C union fetch is bounded:** at most 2 extra records per uncovered
+ significant term, at most 8 total, fetched with a single-term FTS query and
+ appended to the pack's `unionRecords` (not into `results` β€” the primary
+ result contract stays untouched; agents consume the pack).
+- **E verdict thresholds:** `complete` when IDF-weighted coverage β‰₯ 0.8,
+ `partial` β‰₯ 0.4, else `sparse`. False-absence guard: any uncovered term with
+ corpus `df > 0` is reported as `uncovered_but_present_in_corpus` so a
+ downstream summarizer cannot honestly claim "the vault has nothing on X".
+- **D parser is a pure module** (`time-range.ts`) taking an injected `nowMs`;
+ unparseable input throws `SearchError("INVALID_INPUT")` β€” explicit, not
+ silent. Time-filtered queries bypass the query cache (a relative range
+ resolves to a different absolute window every call; caching would serve
+ stale windows).
+- **D filters hydrated candidates by `mtime` before ranking**, so every later
+ phase (traversal seeds, MMR, relations) sees only in-range candidates.
+
+## File changes
+
+New modules:
+
+- `src/core/search/relation-polarity.ts` (A: polarity pass, constants, reasons)
+- `src/core/search/feedback.ts` (B: event shape, file store, learned-weight fold)
+- `src/core/search/coverage.ts` (C+E: significant terms, postings, IDF, union, verdict)
+- `src/core/search/time-range.ts` (D: since/until parser)
+
+Modified:
+
+- `src/core/search/search.ts` (wire A/B/D phases, C/E pack assembly, cache fingerprint)
+- `src/core/search/types.ts` (SearchOptions: `since`, `until`, `includeSuperseded`; ResolvedRecallConfig: relation polarity + learned weights toggles; EvidencePack import type)
+- `src/core/search/evidence-pack.ts` (optional pack fields, delegate coverage math to `coverage.ts`)
+- `src/core/search/store.ts` (new: `typedRelationEdgesForDocuments`, `documentFrequency`, `documentCount`)
+- `src/core/search/index.ts` (config keys + re-exports)
+- `src/cli/search.ts` (flags: `--since`, `--until`, `--include-superseded`; verbs: `feedback`, `weights`)
+- `src/mcp/search-tools.ts` (brain_search schema: `since`, `until`, `include_superseded`; new tool `brain_recall_feedback`)
+
+Tests (bun:test, `tests/core/search/`): new `relation-polarity.test.ts`,
+`feedback.test.ts`, `coverage.test.ts`, `time-range.test.ts`,
+`completeness.test.ts`, plus integration cases in `search.test.ts`,
+`evidence-pack.test.ts`, CLI/MCP surface tests.
+
+Docs: `README.md`, `CHANGELOG.md`, `docs/cli-reference.md`, `docs/mcp.md`.
+
+## Risks and open questions
+
+- **Relation targets may be unresolved** (`target_document_id` NULL when the
+ target page does not exist). The polarity pass must treat unresolved edges
+ as inert (reason-only, no pull-in). Covered by a test.
+- **Pulled-in successors compete with genuine hits** for the final window;
+ the boost is derived from the predecessor's score (Γ—0.9) and capped so a
+ successor never outranks a direct strong match on its own merits alone.
+- **IDF query cost**: one FTS query per significant term, only in evidence-pack
+ mode; significant terms are bounded by query length. Acceptable; measured in
+ QA.
+- **Learned-weight gaming/drift**: bounds [0.8, 1.2] and pure-fold determinism
+ keep worst-case drift small and reproducible; the operator can freeze or
+ reset at any time.
+- **Feedback file growth**: one small JSON per explicit event; low volume by
+ construction. A future compaction command is deliberately deferred.
diff --git a/docs/brainstorm/recall-trust-suite/plan.md b/docs/brainstorm/recall-trust-suite/plan.md
new file mode 100644
index 00000000..135540e8
--- /dev/null
+++ b/docs/brainstorm/recall-trust-suite/plan.md
@@ -0,0 +1,101 @@
+# Recall Trust Suite β€” implementation plan
+
+Implementation order encodes the Variant 3 dependency: the coverage engine
+lands inside Task 4 (Feature C) and Task 5 (Feature E) consumes it. Tasks 1-3
+are independent of each other. Each task is one atomic conventional commit,
+TDD (failing tests first), formatter + linter green before the commit.
+
+## Tasks
+
+### Task 1: Relation-aware recall (Feature A, t_d8571bf0)
+
+- **Files**: new `src/core/search/relation-polarity.ts`,
+ new `tests/core/search/relation-polarity.test.ts`;
+ modify `src/core/search/store.ts` (`typedRelationEdgesForDocuments`),
+ `src/core/search/search.ts` (polarity pass on the assembled pool before the
+ final slice; config fingerprint), `src/core/search/types.ts`
+ (`SearchOptions.includeSuperseded`, `ResolvedRecallConfig.relationPolarityEnabled`),
+ `src/core/search/index.ts` (config key `search_relation_polarity_enabled`),
+ `src/cli/search.ts` (`--include-superseded`),
+ `src/mcp/search-tools.ts` (`include_superseded`),
+ `tests/core/search/search.test.ts` (integration).
+- **Acceptance**: a query matching a superseded page surfaces the successor
+ above the predecessor; predecessor carries `superseded_by: <target>` reason;
+ `--include-superseded` restores undemoted order; `contradicts` adds a
+ warning reason without a score change; positive relations add a bounded
+ boost between co-retrieved candidates; unresolved targets are inert; a vault
+ with no typed relations ranks bit-identically.
+- **Depends on**: none.
+
+### Task 2: Retrieval feedback loop (Feature B, t_68e1b774)
+
+- **Files**: new `src/core/search/feedback.ts`,
+ new `tests/core/search/feedback.test.ts`;
+ modify `src/core/search/search.ts` (learned multipliers into ranking;
+ learned-weights hash into cache fingerprint), `src/core/search/types.ts`
+ (`ResolvedRecallConfig.learnedWeightsEnabled`), `src/core/search/index.ts`
+ (config key `search_learned_weights_enabled`), `src/cli/search.ts`
+ (verbs `feedback`, `weights` incl. `--reset`), `src/mcp/search-tools.ts`
+ (new tool `brain_recall_feedback`),
+ `tests/core/search/search.test.ts`, MCP surface test.
+- **Acceptance**: recording feedback creates one event file under
+ `Brain/search/feedback/`; the learned-weight fold is deterministic, bounded
+ to [0.8, 1.2], and replayable from events; ranking shifts only when the
+ config opt-in is on; affected results carry a `learned_weights:` reason;
+ `o2b search weights` shows base + learned + counts; `--reset` removes the
+ derived weights but keeps events.
+- **Depends on**: none.
+
+### Task 3: Time-aware recall (Feature D, t_9dfbaa76)
+
+- **Files**: new `src/core/search/time-range.ts`,
+ new `tests/core/search/time-range.test.ts`;
+ modify `src/core/search/search.ts` (mtime filter before ranking; cache
+ bypass when a range is active), `src/core/search/types.ts`
+ (`SearchOptions.since/until`), `src/cli/search.ts` (`--since`, `--until`),
+ `src/mcp/search-tools.ts` (`since`, `until`),
+ `tests/core/search/search.test.ts`.
+- **Acceptance**: ISO dates, `yesterday` / `today` / `last week` /
+ `last month`, and `24h` / `7d` / `2w` shorthand all resolve deterministically
+ against an injected now; out-of-range candidates never surface; invalid
+ input raises `INVALID_INPUT`; time-filtered queries bypass the query cache.
+- **Depends on**: none.
+
+### Task 4: Verified multi-record recall (Feature C, t_407a3477)
+
+- **Files**: new `src/core/search/coverage.ts`,
+ new `tests/core/search/coverage.test.ts`;
+ modify `src/core/search/store.ts` (`documentFrequency`, `documentCount`),
+ `src/core/search/evidence-pack.ts` (optional fields
+ `idfWeightedCoverage`, `rareTerms`, `uncoveredRareTerms`, `unionRecords`;
+ rare-term abstention; delegate term math to `coverage.ts`),
+ `src/core/search/search.ts` (union fetch in evidence-pack mode),
+ `tests/core/search/evidence-pack.test.ts`.
+- **Acceptance**: per-token union gathers bounded extra records for uncovered
+ significant terms; coverage is IDF-weighted; an uncovered rare term
+ populates `abstention`; legacy pack fields are byte-identical for callers
+ that ignore the new optional fields; non-evidence-pack searches are
+ untouched.
+- **Depends on**: none (lands the coverage engine).
+
+### Task 5: Search-completeness guard (Feature E, t_854b8e5f)
+
+- **Files**: modify `src/core/search/coverage.ts` (verdict + false-absence),
+ `src/core/search/evidence-pack.ts` (`completeness` field),
+ new `tests/core/search/completeness.test.ts`;
+ modify `tests/core/search/evidence-pack.test.ts`.
+- **Acceptance**: pack carries `completeness` with verdict
+ `complete` / `partial` / `sparse` from IDF-weighted coverage thresholds
+ (0.8 / 0.4); every uncovered term present in the corpus is listed as
+ `uncovered_but_present_in_corpus` (false-absence guard), including the
+ zero-results case.
+- **Depends on**: Task 4.
+
+### Task 6: Docs + release prep (phase 5 of the playbook)
+
+- **Files**: `README.md`, `CHANGELOG.md`, `docs/cli-reference.md`,
+ `docs/mcp.md`, `package.json` (version bump), version-synced files via
+ `bun run sync-version`.
+- **Acceptance**: one CHANGELOG version bundling the five features;
+ `bun run sync-version:check` passes; `bun run validate` green.
+- **Depends on**: Tasks 1-5.
diff --git a/docs/brainstorm/recall-trust-suite/variants.md b/docs/brainstorm/recall-trust-suite/variants.md
new file mode 100644
index 00000000..15c71434
--- /dev/null
+++ b/docs/brainstorm/recall-trust-suite/variants.md
@@ -0,0 +1,66 @@
+# Recall Trust Suite β€” brainstorm variants (audit trail)
+
+**Consultant:** Claude Code (`claude -p`), 2026-06-02. Raw output: `cli-output/claude.md`.
+Prompt: `cli-output/prompt.md`. Fallback consultant (Codex) was not needed β€”
+the primary returned 3 parseable variants.
+
+## Variant 1: Independent feature modules
+
+- **Approach**: Implement each of the five features as a self-contained module gated by its own config flag, wired into the orchestrator at its natural seam (A/B into `ranker.ts`, C/E into `evidence-pack.ts`, D into candidate filtering + CLI/MCP schema). No shared abstraction is introduced; each feature owns its own helpers, including separate "significant term" and coverage logic for C and E.
+- **Trade-offs**:
+ - Pro: Each commit maps cleanly to one kanban task; trivial to TDD and revert in isolation.
+ - Pro: Lowest blast radius β€” a flag-off feature touches nothing else; default behavior trivially stable.
+ - Pro: No early refactor of shared internals, so review stays localized.
+ - Con: C (rare-term gate / IDF coverage) and E (top-N term coverage) independently reimplement term-significance and coverage matrices, risking divergent verdicts on the same query.
+ - Con: B's learned-weight path and A's relation layer both mutate the weight profile without a shared contract, inviting subtle ordering bugs.
+ - Con: Duplication accrues as future trust features land.
+- **Complexity**: medium
+- **Risk**: low
+
+## Variant 2: Shared trust substrate first
+
+- **Approach**: Land foundational primitives in the early commits β€” a term-signal engine (significant-term extraction, per-token record union, IDF statistics, coverage matrix) plus a relation-signal resolver β€” then implement all five features as thin consumers of that substrate. C, E, and the rare-term gate all read one coverage matrix; A and B feed one scoring-context object.
+- **Trade-offs**:
+ - Pro: Single source of truth for "significant/rare term" and coverage; C and E verdicts are guaranteed consistent.
+ - Pro: Cleanest long-term architecture; future trust features extend the substrate cheaply.
+ - Pro: Centralized determinism/auditing surface aligns with the `why_retrieved` philosophy.
+ - Con: The first commits are foundation, not kanban tasks β€” breaks the clean one-commit-per-feature mapping and the TDD-per-task framing.
+ - Con: Largest upfront refactor of `ranker.ts`/`evidence-pack.ts` internals; higher chance of perturbing stable default behavior or the config-fingerprint cache key.
+ - Con: Bigger, harder-to-review diff before any user-visible feature lands.
+- **Complexity**: large
+- **Risk**: medium
+
+## Variant 3: Two-phase layering (pre-rank signals vs post-rank verification overlay)
+
+- **Approach**: Split the suite along the existing pipeline. A pre-rank "signal injection" group β€” A (relation polarity into the ranker), B (learned weights into weight resolution), D (time constraint into candidate filtering) β€” shares the weight-profile/candidate path. A post-rank "verification overlay" group β€” C (per-token union + IDF + rare-term gate) and E (completeness verdict) β€” shares one coverage engine built over the final candidate set in the evidence-pack stage. Sharing is introduced only where features genuinely overlap (C+E coverage), not globally.
+- **Trade-offs**:
+ - Pro: Each feature remains its own atomic, TDD'd commit while C and E still share the one place they truly overlap.
+ - Pro: Maps onto real pipeline seams (rank vs evidence-pack post-pass), so the scoping is self-documenting and defaults stay isolated per group.
+ - Pro: Avoids Variant 2's foundation-first commit and Variant 1's C/E duplication.
+ - Con: Two coupling boundaries to keep clean (weight-profile contract; coverage engine), more design thought than Variant 1.
+ - Con: The shared coverage engine still lands inside whichever of C/E is built first, so commit ordering carries a small dependency.
+- **Complexity**: medium
+- **Risk**: low-medium
+
+## Consultant recommendation
+
+**Variant 3.** Rationale (verbatim): It honors the hard constraints β€” atomic
+per-feature commits, opt-in additive features, stable defaults β€” while
+consolidating the one substantive overlap (C's IDF/rare-term coverage and E's
+completeness audit both need a per-token coverage matrix) so the two cannot
+produce contradictory verdicts. It fits the existing orchestrator seams
+(pre-rank scoring vs evidence-pack post-pass) without Variant 2's risky
+foundation-first refactor of the cache-fingerprinted ranking core, and avoids
+the duplication and drift that Variant 1 would bake into the trust layer.
+
+## Orchestrator decision
+
+**Agree with the consultant: Variant 3.** Project context confirms the
+recommendation: prior suites (#46, #47, #54) all landed as per-feature atomic
+commits on existing pipeline seams, and `search.ts` already models exactly the
+two seams Variant 3 uses (the `assemble()` rank pass and the
+`evidencePack === true` post-pass). Variant 2 would refactor the
+cache-fingerprinted core that PR #47's query cache depends on β€” unnecessary
+risk for this scope. The C/E coverage engine lands as its own module
+(`coverage.ts`) inside the Feature C commit, then E consumes it; commit
+ordering in `plan.md` encodes that dependency.
diff --git a/docs/cli-reference.md b/docs/cli-reference.md
index 7d014e9d..4c426e72 100644
--- a/docs/cli-reference.md
+++ b/docs/cli-reference.md
@@ -163,10 +163,19 @@ o2b search "<query>" Hybrid full-text + semantic search across the vaul
--property type=decision --property status=open
filters on frontmatter scalars (post-FTS phase)
--query-doc '<lanes>' separates intent/lex/vec/hyde recall lanes
- --evidence-pack adds matched/missing term diagnostics and abstention text
+ --evidence-pack adds matched/missing term diagnostics, abstention text,
+ IDF-weighted coverage, per-token union records, and a completeness verdict
+ --since/--until scope recall by document mtime (ISO date/datetime,
+ today / yesterday / last week / last month, or 24h / 7d / 2w shorthand)
+ --include-superseded keeps superseded predecessors undemoted (history mode)
--verbose adds per-result why_retrieved reasons
--json for structured output (includes reasons[])
CJK text is expanded for FTS recall without polluting returned content
+o2b search feedback Record explicit recall feedback for one result
+ (--query Q --result <path> --verdict up|down; one JSON event file
+ under Brain/search/feedback/, learned weights refresh deterministically)
+o2b search weights Show base weights, learned multipliers, event count, and bounds
+ --reset removes the derived learned-weights file (events kept)
o2b search focus set Persist a 120-minute ranking focus (--query Q and/or --path P; --ttl-minutes N)
o2b search focus status Show the active focus; --json emits { active, focus }
o2b search focus clear Clear the persisted focus file next to the search index
@@ -174,6 +183,18 @@ o2b search reindex Rebuild the SQLite + FTS5 index from scratch
(required after upgrading to v0.13.0 recall schema or v0.26.0 CJK FTS content)
```
+Typed relations participate in ranking (relation polarity): a page whose
+frontmatter declares `superseded_by:` is demoted when it matches and its
+successor is boosted or pulled in, `contradicts:` surfaces warning-style
+`why_retrieved` reasons on both endpoints without endorsement, and
+`related` / `extends` / `depends_on` / `refines` grant a small bounded boost
+between co-retrieved pages. Vaults without typed relations rank identically;
+`search_relation_polarity_enabled: false` (or
+`OPEN_SECOND_BRAIN_SEARCH_RELATION_POLARITY=false`) is the kill switch. Learned
+recall weights are opt-in via `search_learned_weights_enabled: true` (or
+`OPEN_SECOND_BRAIN_SEARCH_LEARNED_WEIGHTS=true`); multipliers stay within
+[0.8, 1.2] and affected results carry a `learned_weights:` reason.
+
Structured recall query documents are line-oriented. `intent:` accepts
`neutral`, `exact`, `entity`, or `broad`; `lex:` accepts bare or quoted terms
and `-excluded` tokens; `vec:` and `hyde:` provide semantic text lanes when the
diff --git a/docs/mcp.md b/docs/mcp.md
index a554b6b8..eade7680 100644
--- a/docs/mcp.md
+++ b/docs/mcp.md
@@ -38,7 +38,8 @@ capability flags for a narrower per-process full server.
| `brain_agent_diff` | Read-only comparison between source agents using browse/search/diff/map modes over the same provenance foundation. | β€” |
| `brain_audit` | Read-only per-preference mutation trail (create / promote / update / retire / merge) with agent, reason, revision + content-hash before/after. | `pref_id` |
| `brain_morning_brief` | Read-only session-start summary: top confirmed preferences, recent reconcile open questions, recent notes; character-budgeted. | β€” |
-| `brain_search` | Read-only vault search with optional structured query lanes, explicit focus hints, and evidence-pack diagnostics. | `query` |
+| `brain_search` | Read-only vault search with optional structured query lanes, explicit focus hints, time ranges, and evidence-pack diagnostics. | `query` |
+| `brain_recall_feedback` | Record explicit up/down recall feedback for one search result; feeds the deterministic learned-weight fold. | `query`, `result_path`, `verdict` |
| `brain_recall_gate` | Read-only classifier for whether an automatic recall attempt should run; returns `retrieve` plus a stable reason. | `prompt` |
| `brain_context_pack` | Budgeted context slice; pass `lanes: true` to return directives, constraints, and consider lanes. Filtered items include `safety.reasons`. | `max_tokens` |
| `brain_context_receipts` | List or show opt-in prompt context receipt continuity records with budgets, hashes, source refs, safety/redaction metadata, and item IDs. | `operation` |
@@ -77,9 +78,18 @@ capability flags for a narrower per-process full server.
`diff`, `map`). Omitting `agents` means all known source agents.
`brain_search` accepts `query_document` with line-oriented `intent:`, `lex:`,
`vec:`, and `hyde:` lanes; `focus_query` / `focus_path_prefix` to steer a
-single call; and `evidence_pack: true` to return significant/matched/missing
-terms, abstention text, terminal-state downrank reasons, and per-result
-`why_retrieved`. It can also emit opt-in recall telemetry with `telemetry: true`.
+single call; `since` / `until` time ranges (ISO date/datetime, `today`,
+`yesterday`, `last week`, `last month`, or `<n>h`/`<n>d`/`<n>w` shorthand,
+filtered on document mtime); `include_superseded: true` to keep superseded
+predecessors undemoted (history mode); and `evidence_pack: true` to return
+significant/matched/missing terms, abstention text, terminal-state downrank
+reasons, per-result `why_retrieved`, IDF-weighted coverage with rare-term
+classification, per-token `union_records` for uncovered terms, and a
+`completeness` verdict whose `uncovered_but_present_in_corpus` list is the
+false-absence guard. It can also emit opt-in recall telemetry with
+`telemetry: true`. `brain_recall_feedback` records one feedback event as a
+JSON file under `Brain/search/feedback/` and returns the refreshed learned
+weights (applied to ranking only when `search_learned_weights_enabled` is on).
`brain_context_pack` accepts opt-in `receipt`, `telemetry`, `cache_stable`, and
`dedup_repeated` diagnostics; `brain_pre_compress_pack` accepts opt-in `receipt`
and `telemetry`. `brain_context_receipts` supports `operation: "list"|"show"`;
diff --git a/openclaw.plugin.json b/openclaw.plugin.json
index 4b109d91..dcf2ce90 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": "0.32.1",
+ "version": "0.33.0",
"activation": { "onStartup": true },
"skills": ["./skills"],
"contracts": {
diff --git a/package.json b/package.json
index b5cc5262..3218554b 100644
--- a/package.json
+++ b/package.json
@@ -1,6 +1,6 @@
{
"name": "open-second-brain",
- "version": "0.32.1",
+ "version": "0.33.0",
"private": false,
"description": "Second brain for AI agents using Obsidian-compatible Markdown vaults. Works with Hermes, Claude Code, Codex, and OpenClaw.",
"keywords": [
diff --git a/plugin.yaml b/plugin.yaml
index a9cbde07..16aad972 100644
--- a/plugin.yaml
+++ b/plugin.yaml
@@ -1,5 +1,5 @@
name: open-second-brain
-version: "0.32.1"
+version: "0.33.0"
description: "Open Second Brain - native Hermes memory provider backed by an Obsidian-compatible Markdown vault."
author: "Open Second Brain contributors"
memory_provider: true
diff --git a/plugins/codex/.codex-plugin/plugin.json b/plugins/codex/.codex-plugin/plugin.json
index 0dfbe3f2..06f268e7 100644
--- a/plugins/codex/.codex-plugin/plugin.json
+++ b/plugins/codex/.codex-plugin/plugin.json
@@ -1,6 +1,6 @@
{
"name": "open-second-brain",
- "version": "0.32.1",
+ "version": "0.33.0",
"description": "Plugin-first second brain package for Codex, Hermes, Claude Code, OpenClaw, and other agent runtimes.",
"author": {
"name": "Open Second Brain contributors",
diff --git a/plugins/hermes/plugin.yaml b/plugins/hermes/plugin.yaml
index a9cbde07..16aad972 100644
--- a/plugins/hermes/plugin.yaml
+++ b/plugins/hermes/plugin.yaml
@@ -1,5 +1,5 @@
name: open-second-brain
-version: "0.32.1"
+version: "0.33.0"
description: "Open Second Brain - native Hermes memory provider backed by an Obsidian-compatible Markdown vault."
author: "Open Second Brain contributors"
memory_provider: true
diff --git a/pyproject.toml b/pyproject.toml
index ea4fd3d8..1e7074b9 100644
--- a/pyproject.toml
+++ b/pyproject.toml
@@ -10,7 +10,7 @@ build-backend = "setuptools.build_meta"
# CLI entry points (those moved to `package.json` `bin`).
[project]
name = "open-second-brain"
-version = "0.32.1"
+version = "0.33.0"
description = "Hermes Python shim for Open Second Brain. Most of the project (CLI, MCP server, OpenClaw plugin) is TypeScript on Bun; see package.json."
readme = "README.md"
requires-python = ">=3.11"
diff --git a/src/cli/search.ts b/src/cli/search.ts
index e5b4a5c2..98fe4f65 100644
--- a/src/cli/search.ts
+++ b/src/cli/search.ts
@@ -15,10 +15,14 @@
import { defaultConfigPath, resolveVault } from "../core/config.ts";
import {
+ captureRecallFeedback,
indexCheck,
indexStatus,
indexVault,
+ loadFeedbackEvents,
+ readLearnedWeights,
reindexVault,
+ resetLearnedWeights,
resolveSearchConfig,
search,
SearchError,
@@ -28,6 +32,9 @@ import {
readSessionFocus,
structuredRecallQueryText,
writeSessionFocus,
+ LEARNED_WEIGHT_MIN,
+ LEARNED_WEIGHT_MAX,
+ type LearnedWeights,
} from "../core/search/index.ts";
import type {
IndexCheckReport,
@@ -41,7 +48,16 @@ import type {
import { CliError, parseFlags } from "./argparse.ts";
import { CronTemplateError, renderCronTemplate } from "./search-cron-template.ts";
-const KNOWN_VERBS = new Set(["query", "index", "reindex", "status", "check", "focus"]);
+const KNOWN_VERBS = new Set([
+ "query",
+ "index",
+ "reindex",
+ "status",
+ "check",
+ "focus",
+ "feedback",
+ "weights",
+]);
export async function handleSearchSubcommand(argv: ReadonlyArray<string>): Promise<number> {
// First positional is verb iff it matches a known verb. Otherwise the
@@ -67,6 +83,10 @@ export async function handleSearchSubcommand(argv: ReadonlyArray<string>): Promi
return await cmdSearchCheck(rest);
case "focus":
return await cmdSearchFocus(rest);
+ case "feedback":
+ return await cmdSearchFeedback(rest);
+ case "weights":
+ return await cmdSearchWeights(rest);
default:
process.stderr.write(`error: unknown search verb: ${verb}\n`);
return 2;
@@ -177,6 +197,102 @@ function writeFocusResponse(focus: SearchSessionFocus | null, json: boolean): vo
process.stdout.write(`search focus: active ${parts.join(" ")}\n`);
}
+// ─── feedback / weights (recall-trust-suite) ─────────────────────────────────
+
+async function cmdSearchFeedback(argv: ReadonlyArray<string>): Promise<number> {
+ const { flags } = parseFlags(argv, {
+ vault: { type: "string" },
+ config: { type: "string" },
+ db: { type: "string" },
+ query: { type: "string" },
+ result: { type: "string" },
+ verdict: { type: "string" },
+ json: { type: "boolean" },
+ });
+ const query = typeof flags["query"] === "string" ? (flags["query"] as string) : "";
+ const resultPath = typeof flags["result"] === "string" ? (flags["result"] as string) : "";
+ const verdict = typeof flags["verdict"] === "string" ? (flags["verdict"] as string) : "";
+ if (!query || !resultPath) {
+ throw new CliError("usage: o2b search feedback --query <q> --result <path> --verdict up|down");
+ }
+ if (verdict !== "up" && verdict !== "down") {
+ throw new CliError("--verdict must be 'up' or 'down'");
+ }
+ const cfg = resolveConfig(flags);
+ const outcome = await captureRecallFeedback(cfg, { query, resultPath, verdict });
+ if (flags["json"] === true) {
+ process.stdout.write(
+ JSON.stringify({
+ recorded: true,
+ result_found: outcome.resultFound,
+ file: outcome.file,
+ learned: outcome.learned,
+ }) + "\n",
+ );
+ return 0;
+ }
+ const found = outcome.resultFound
+ ? ""
+ : " (result not in current top-50; recorded with zero contributions)";
+ process.stdout.write(
+ `recorded ${verdict} for ${resultPath}${found}\n` +
+ `learned weights now: ${formatLearnedWeights(outcome.learned)}\n`,
+ );
+ return 0;
+}
+
+async function cmdSearchWeights(argv: ReadonlyArray<string>): Promise<number> {
+ const { flags } = parseFlags(argv, {
+ vault: { type: "string" },
+ config: { type: "string" },
+ db: { type: "string" },
+ reset: { type: "boolean" },
+ json: { type: "boolean" },
+ });
+ const cfg = resolveConfig(flags);
+ if (flags["reset"] === true) {
+ resetLearnedWeights(cfg.vault);
+ if (flags["json"] === true) {
+ process.stdout.write(JSON.stringify({ reset: true }) + "\n");
+ } else {
+ process.stdout.write("learned weights reset (feedback events kept)\n");
+ }
+ return 0;
+ }
+ const learned = readLearnedWeights(cfg.vault);
+ const payload = {
+ enabled: cfg.recall.learnedWeightsEnabled,
+ base: {
+ keywordWeight: cfg.keywordWeight,
+ semanticWeight: cfg.semanticWeight,
+ },
+ learned,
+ events: loadFeedbackEvents(cfg.vault).length,
+ bounds: { min: LEARNED_WEIGHT_MIN, max: LEARNED_WEIGHT_MAX },
+ };
+ if (flags["json"] === true) {
+ process.stdout.write(JSON.stringify(payload) + "\n");
+ return 0;
+ }
+ const lines = [
+ `learned weights: ${payload.enabled ? "enabled" : "disabled (search_learned_weights_enabled)"}`,
+ `base: kw=${cfg.keywordWeight} sem=${cfg.semanticWeight}`,
+ learned === null
+ ? "learned: none (no feedback recorded)"
+ : `learned: ${formatLearnedWeights(learned)} from ${learned.events} event(s)`,
+ `bounds: [${LEARNED_WEIGHT_MIN}, ${LEARNED_WEIGHT_MAX}]`,
+ ];
+ process.stdout.write(lines.join("\n") + "\n");
+ return 0;
+}
+
+function formatLearnedWeights(w: LearnedWeights): string {
+ return (
+ `kw=${w.keywordMul.toFixed(3)} sem=${w.semanticMul.toFixed(3)} ` +
+ `ent=${w.entityMul.toFixed(3)} rec=${w.recencyMul.toFixed(3)}`
+ );
+}
+
// ─── query ────────────────────────────────────────────────────────────────────
async function cmdSearchQuery(argv: ReadonlyArray<string>): Promise<number> {
@@ -195,6 +311,9 @@ async function cmdSearchQuery(argv: ReadonlyArray<string>): Promise<number> {
visibility: { type: "string-array" },
"query-doc": { type: "string" },
"evidence-pack": { type: "boolean" },
+ "include-superseded": { type: "boolean" },
+ since: { type: "string" },
+ until: { type: "string" },
json: { type: "boolean" },
verbose: { type: "boolean" },
});
@@ -252,6 +371,9 @@ async function cmdSearchQuery(argv: ReadonlyArray<string>): Promise<number> {
...(visibility !== undefined && visibility.length > 0 ? { visibility } : {}),
...(structuredQuery !== undefined ? { structuredQuery } : {}),
...(flags["evidence-pack"] === true ? { evidencePack: true } : {}),
+ ...(flags["include-superseded"] === true ? { includeSuperseded: true } : {}),
+ ...(typeof flags["since"] === "string" ? { since: flags["since"] as string } : {}),
+ ...(typeof flags["until"] === "string" ? { until: flags["until"] as string } : {}),
});
if (flags["json"]) {
@@ -337,6 +459,34 @@ function jsonForEvidencePack(pack: NonNullable<SearchOutcome["evidencePack"]>):
})),
dropped_candidates: pack.droppedCandidates,
abstention: pack.abstention,
+ ...(pack.idfWeightedCoverage !== undefined
+ ? { idf_weighted_coverage: pack.idfWeightedCoverage }
+ : {}),
+ ...(pack.rareTerms !== undefined ? { rare_terms: pack.rareTerms } : {}),
+ ...(pack.uncoveredRareTerms !== undefined
+ ? { uncovered_rare_terms: pack.uncoveredRareTerms }
+ : {}),
+ ...(pack.unionRecords !== undefined
+ ? {
+ union_records: pack.unionRecords.map((r) => ({
+ term: r.term,
+ path: r.path,
+ document_id: r.documentId,
+ chunk_id: r.chunkId,
+ })),
+ }
+ : {}),
+ ...(pack.completeness !== undefined
+ ? {
+ completeness: {
+ verdict: pack.completeness.verdict,
+ idf_weighted_coverage: pack.completeness.idfWeightedCoverage,
+ covered_terms: pack.completeness.coveredTerms,
+ uncovered_terms: pack.completeness.uncoveredTerms,
+ uncovered_but_present_in_corpus: pack.completeness.uncoveredButPresentInCorpus,
+ },
+ }
+ : {}),
};
}
diff --git a/src/core/search/coverage.ts b/src/core/search/coverage.ts
new file mode 100644
index 00000000..be42e555
--- /dev/null
+++ b/src/core/search/coverage.ts
@@ -0,0 +1,170 @@
+/**
+ * Coverage engine (recall-trust-suite, Features C and E).
+ *
+ * The single source of truth for query-term verification: significant
+ * terms, per-term coverage postings, corpus document frequency turned
+ * into IDF weight, and the rare-term classification. Both the verified
+ * multi-record recall pass (Feature C: union fetch, IDF-weighted
+ * support, rare-term abstention) and the search-completeness guard
+ * (Feature E) read this one report, so the two can never disagree about
+ * what "covered" means.
+ *
+ * Pure module β€” callers (search.ts / evidence-pack.ts) gather document
+ * counts and per-term document frequencies from the store and hand them
+ * in. Deterministic, no LLM, no clock.
+ */
+
+const STOPWORDS = new Set([
+ "about",
+ "and",
+ "are",
+ "for",
+ "from",
+ "how",
+ "the",
+ "this",
+ "that",
+ "what",
+ "when",
+ "where",
+ "with",
+]);
+
+/** Share of the corpus a term may appear in and still count as rare. */
+export const RARE_TERM_CORPUS_SHARE = 0.02;
+
+/**
+ * Significant query terms: length >= 3, not a stopword, deduplicated,
+ * in query order. The same extraction the evidence pack has used since
+ * PR #54 β€” now owned here so every consumer agrees.
+ */
+export function significantTerms(query: string): string[] {
+ const terms = new Set<string>();
+ for (const token of query.toLocaleLowerCase().split(/[^\p{L}\p{N}_-]+/u)) {
+ if (token.length >= 3 && !STOPWORDS.has(token)) terms.add(token);
+ }
+ return [...terms];
+}
+
+/** Case-folded containment check shared by pack record building. */
+export function termIncludedIn(haystack: string, term: string): boolean {
+ return haystack.toLocaleLowerCase().includes(term);
+}
+
+/**
+ * Smoothed inverse document frequency: `ln(1 + N / (1 + df))`. Always
+ * positive (even a term in every document keeps a small weight), higher
+ * for rarer terms, and stable for df = 0.
+ */
+export function idfForTerm(df: number, documentCount: number): number {
+ const n = Math.max(0, documentCount);
+ const d = Math.max(0, df);
+ return Math.log(1 + n / (1 + d));
+}
+
+/**
+ * A term is rare (high-signal) when it appears in at most
+ * `RARE_TERM_CORPUS_SHARE` of the corpus, with a floor of one document
+ * so tiny corpora still classify their unique terms as rare.
+ */
+export function isRareTerm(df: number, documentCount: number): boolean {
+ return df <= Math.max(1, Math.floor(RARE_TERM_CORPUS_SHARE * documentCount));
+}
+
+export interface TermCoverage {
+ readonly term: string;
+ readonly df: number;
+ readonly idf: number;
+ readonly rare: boolean;
+ readonly covered: boolean;
+}
+
+export interface CoverageInputs {
+ readonly significantTerms: ReadonlyArray<string>;
+ /** Terms at least one returned result contains. */
+ readonly coveredTerms: ReadonlySet<string>;
+ readonly documentCount: number;
+ /** Corpus document frequency per significant term (absent β†’ 0). */
+ readonly dfByTerm: ReadonlyMap<string, number>;
+}
+
+export interface CoverageReport {
+ readonly terms: ReadonlyArray<TermCoverage>;
+ /**
+ * Support coverage weighted by IDF: the share of the query's total
+ * IDF mass the covered terms carry. A result set matching only the
+ * common words scores low even when it matches most terms by count.
+ */
+ readonly idfWeightedCoverage: number;
+ readonly rareTerms: ReadonlyArray<string>;
+ readonly uncoveredRareTerms: ReadonlyArray<string>;
+}
+
+/** IDF-weighted coverage at/above this is a complete retrieval. */
+export const COMPLETENESS_COMPLETE_THRESHOLD = 0.8;
+/** IDF-weighted coverage at/above this (below complete) is partial. */
+export const COMPLETENESS_PARTIAL_THRESHOLD = 0.4;
+
+export type CompletenessVerdict = "complete" | "partial" | "sparse";
+
+/**
+ * Search-completeness guard (Feature E): a deterministic verdict over
+ * how well the returned results cover the query, plus the
+ * false-absence guard β€” uncovered terms the corpus DOES contain. A
+ * summarizer seeing a term in `uncoveredButPresentInCorpus` cannot
+ * honestly claim the vault has nothing on it.
+ */
+export interface CompletenessReport {
+ readonly verdict: CompletenessVerdict;
+ readonly idfWeightedCoverage: number;
+ readonly coveredTerms: ReadonlyArray<string>;
+ readonly uncoveredTerms: ReadonlyArray<string>;
+ readonly uncoveredButPresentInCorpus: ReadonlyArray<string>;
+}
+
+export function buildCompletenessReport(coverage: CoverageReport): CompletenessReport {
+ const covered = coverage.terms.filter((t) => t.covered).map((t) => t.term);
+ const uncovered = coverage.terms.filter((t) => !t.covered);
+ const verdict: CompletenessVerdict =
+ coverage.idfWeightedCoverage >= COMPLETENESS_COMPLETE_THRESHOLD
+ ? "complete"
+ : coverage.idfWeightedCoverage >= COMPLETENESS_PARTIAL_THRESHOLD
+ ? "partial"
+ : "sparse";
+ return Object.freeze({
+ verdict,
+ idfWeightedCoverage: coverage.idfWeightedCoverage,
+ coveredTerms: Object.freeze(covered),
+ uncoveredTerms: Object.freeze(uncovered.map((t) => t.term)),
+ uncoveredButPresentInCorpus: Object.freeze(
+ uncovered.filter((t) => t.df > 0).map((t) => t.term),
+ ),
+ });
+}
+
+export function buildCoverageReport(inputs: CoverageInputs): CoverageReport {
+ const terms: TermCoverage[] = inputs.significantTerms.map((term) => {
+ const df = inputs.dfByTerm.get(term) ?? 0;
+ return Object.freeze({
+ term,
+ df,
+ idf: idfForTerm(df, inputs.documentCount),
+ rare: isRareTerm(df, inputs.documentCount),
+ covered: inputs.coveredTerms.has(term),
+ });
+ });
+ let totalIdf = 0;
+ let coveredIdf = 0;
+ for (const t of terms) {
+ totalIdf += t.idf;
+ if (t.covered) coveredIdf += t.idf;
+ }
+ const rareTerms = terms.filter((t) => t.rare).map((t) => t.term);
+ const uncoveredRareTerms = terms.filter((t) => t.rare && !t.covered).map((t) => t.term);
+ return Object.freeze({
+ terms: Object.freeze(terms),
+ idfWeightedCoverage: totalIdf === 0 ? 1 : coveredIdf / totalIdf,
+ rareTerms: Object.freeze(rareTerms),
+ uncoveredRareTerms: Object.freeze(uncoveredRareTerms),
+ });
+}
diff --git a/src/core/search/evidence-pack.ts b/src/core/search/evidence-pack.ts
index 577e6265..c271be53 100644
--- a/src/core/search/evidence-pack.ts
+++ b/src/core/search/evidence-pack.ts
@@ -1,3 +1,10 @@
+import {
+ buildCompletenessReport,
+ buildCoverageReport,
+ significantTerms,
+ termIncludedIn,
+} from "./coverage.ts";
+import type { CompletenessReport, CoverageReport } from "./coverage.ts";
import type { BrainSearchResult } from "./types.ts";
export interface EvidenceRecord {
@@ -12,6 +19,28 @@ export interface EvidenceRecord {
readonly droppedCandidateReasons: ReadonlyArray<string>;
}
+/**
+ * One per-token recall-union record (recall-trust-suite, Feature C): a
+ * document fetched specifically because it covers a significant term
+ * the ranked result set left uncovered. Union records live in the pack
+ * only β€” the primary `results` contract stays untouched.
+ */
+export interface EvidenceUnionRecord {
+ readonly term: string;
+ readonly path: string;
+ readonly documentId: number;
+ readonly chunkId: number;
+}
+
+/**
+ * Verification extras computed by the coverage engine when the search
+ * runs in evidence-pack mode (recall-trust-suite, Features C and E).
+ */
+export interface EvidenceVerification {
+ readonly coverage: CoverageReport;
+ readonly unionRecords: ReadonlyArray<EvidenceUnionRecord>;
+}
+
export interface EvidencePack {
readonly significantTerms: ReadonlyArray<string>;
readonly matchedTerms: ReadonlyArray<string>;
@@ -23,38 +52,31 @@ export interface EvidencePack {
readonly reason: string;
}>;
readonly abstention: string | null;
+ /**
+ * IDF-weighted support coverage (Feature C): the share of the query's
+ * IDF mass the covered terms carry. Present only when the search ran
+ * with coverage verification.
+ */
+ readonly idfWeightedCoverage?: number;
+ /** Rare (high-signal) significant terms per the corpus statistics. */
+ readonly rareTerms?: ReadonlyArray<string>;
+ /** Rare terms no returned record covers β€” the abstention trigger. */
+ readonly uncoveredRareTerms?: ReadonlyArray<string>;
+ /** Per-token recall union for uncovered significant terms. */
+ readonly unionRecords?: ReadonlyArray<EvidenceUnionRecord>;
+ /**
+ * Search-completeness guard (Feature E): verdict + false-absence
+ * report from the same coverage engine. Present only when the search
+ * ran with coverage verification.
+ */
+ readonly completeness?: CompletenessReport;
}
-const STOPWORDS = new Set([
- "about",
- "and",
- "are",
- "for",
- "from",
- "how",
- "the",
- "this",
- "that",
- "what",
- "when",
- "where",
- "with",
-]);
-
const TERMINAL_STATE_RE =
/\b(?:archived|closed|deprecated|done|resolved|retired|superseded|terminal)\b/iu;
-function significantTerms(query: string): string[] {
- const terms = new Set<string>();
- for (const token of query.toLocaleLowerCase().split(/[^\p{L}\p{N}_-]+/u)) {
- if (token.length >= 3 && !STOPWORDS.has(token)) terms.add(token);
- }
- return [...terms];
-}
-
function includesTerm(result: BrainSearchResult, term: string): boolean {
- const haystack = `${result.path}\n${result.title ?? ""}\n${result.content}`.toLocaleLowerCase();
- return haystack.includes(term);
+ return termIncludedIn(`${result.path}\n${result.title ?? ""}\n${result.content}`, term);
}
function supportCoverage(
@@ -92,9 +114,23 @@ export function downrankTerminalEvidenceResults(
});
}
+function abstentionMessage(
+ missing: ReadonlyArray<string>,
+ verification: EvidenceVerification | undefined,
+): string | null {
+ // Rare-term gate (Feature C): an uncovered rare term is the strongest
+ // abstention signal β€” high-signal evidence is absent from the answer set.
+ const uncoveredRare = verification?.coverage.uncoveredRareTerms ?? [];
+ if (uncoveredRare.length > 0) {
+ return `Rare significant terms uncovered: ${uncoveredRare.join(", ")}`;
+ }
+ return missing.length > 0 ? `Unsupported significant terms: ${missing.join(", ")}` : null;
+}
+
export function buildEvidencePack(
query: string,
results: ReadonlyArray<BrainSearchResult>,
+ verification?: EvidenceVerification,
): EvidencePack {
const significant = Object.freeze(significantTerms(query));
const matchedSet = new Set<string>();
@@ -129,6 +165,17 @@ export function buildEvidencePack(
supportCoverage: supportCoverage(matched, significant),
records: Object.freeze(records),
droppedCandidates: Object.freeze([]),
- abstention: missing.length > 0 ? `Unsupported significant terms: ${missing.join(", ")}` : null,
+ abstention: abstentionMessage(missing, verification),
+ ...(verification !== undefined
+ ? {
+ idfWeightedCoverage: verification.coverage.idfWeightedCoverage,
+ rareTerms: verification.coverage.rareTerms,
+ uncoveredRareTerms: verification.coverage.uncoveredRareTerms,
+ unionRecords: verification.unionRecords,
+ completeness: buildCompletenessReport(verification.coverage),
+ }
+ : {}),
});
}
+
+export { buildCoverageReport, significantTerms };
diff --git a/src/core/search/feedback.ts b/src/core/search/feedback.ts
new file mode 100644
index 00000000..b9c24ac4
--- /dev/null
+++ b/src/core/search/feedback.ts
@@ -0,0 +1,327 @@
+/**
+ * Retrieval feedback loop (recall-trust-suite, Feature B).
+ *
+ * Explicit recall feedback is the operator (or a downstream agent)
+ * saying "this result helped" / "this result was noise". Each event is
+ * one small JSON file under `Brain/search/feedback/` β€” the same
+ * conflict-free one-file-per-signal pattern `Brain/inbox/` uses, so
+ * multi-device vaults never produce sync conflicts on a shared
+ * append-only file.
+ *
+ * Learned weights are a PURE FOLD over the event set: deterministic,
+ * order-insensitive, bounded to [LEARNED_WEIGHT_MIN, LEARNED_WEIGHT_MAX],
+ * and replayable from the events at any time. The derived file
+ * (`Brain/search/learned-weights.json`) is a cache of that fold β€”
+ * deleting it (reset) loses nothing. Operator configuration stays the
+ * base policy: the multipliers compose with the configured weights and
+ * cannot drift outside the documented bounds.
+ *
+ * Privacy: events carry an FNV-1a hash of the query, never the raw
+ * query text.
+ */
+
+import { mkdirSync, readdirSync, readFileSync, rmSync, writeFileSync, existsSync } from "node:fs";
+import { join } from "node:path";
+
+import type { BrainSearchResult, ResolvedSearchConfig, WeightProfile } from "./types.ts";
+
+/** Lower bound for one learned per-layer multiplier. */
+export const LEARNED_WEIGHT_MIN = 0.8;
+/** Upper bound for one learned per-layer multiplier. */
+export const LEARNED_WEIGHT_MAX = 1.2;
+/** Step scale for the fold: full agreement moves a layer by Β±this much. */
+export const LEARNED_WEIGHT_STEP = 0.5;
+
+/** Per-layer scoring contributions captured at retrieval time. */
+export interface LayerContributions {
+ readonly keyword: number;
+ readonly semantic: number;
+ readonly entity: number;
+ readonly recency: number;
+}
+
+export interface RecallFeedbackEvent {
+ /** Unix-ms timestamp the feedback was given. */
+ readonly ts: number;
+ /** FNV-1a hash of the normalised query β€” never the raw query text. */
+ readonly queryHash: string;
+ /** Vault-relative path of the result being judged. */
+ readonly resultPath: string;
+ readonly verdict: "up" | "down";
+ readonly contributions: LayerContributions;
+}
+
+export interface LearnedWeights extends WeightProfile {
+ /** Number of events the fold consumed. */
+ readonly events: number;
+ /** ISO timestamp of the most recent event in the fold. */
+ readonly updatedAt: string | null;
+}
+
+export const NEUTRAL_LEARNED_WEIGHTS: LearnedWeights = Object.freeze({
+ keywordMul: 1,
+ semanticMul: 1,
+ entityMul: 1,
+ recencyMul: 1,
+ events: 0,
+ updatedAt: null,
+});
+
+export function feedbackDir(vault: string): string {
+ return join(vault, "Brain", "search", "feedback");
+}
+
+export function learnedWeightsPath(vault: string): string {
+ return join(vault, "Brain", "search", "learned-weights.json");
+}
+
+/** Deterministic FNV-1a 32-bit hash, hex-encoded (same family as query-plan). */
+export function fnv1aHex(input: string): string {
+ let h = 0x811c9dc5;
+ for (let i = 0; i < input.length; i++) {
+ h ^= input.charCodeAt(i);
+ h = (h + ((h << 1) + (h << 4) + (h << 7) + (h << 8) + (h << 24))) >>> 0;
+ }
+ return h.toString(16).padStart(8, "0");
+}
+
+function round6(x: number): number {
+ return Math.round(x * 1e6) / 1e6;
+}
+
+/**
+ * Read the per-layer contributions off a search result. Keyword,
+ * semantic, and recency are first-class fields; the entity layer only
+ * surfaces through its `entity_match:` reason, so it is parsed back out.
+ */
+export function contributionsFromResult(result: BrainSearchResult): LayerContributions {
+ let entity = 0;
+ for (const reason of result.reasons) {
+ if (reason.startsWith("entity_match: ")) {
+ const parsed = Number(reason.slice("entity_match: ".length));
+ if (Number.isFinite(parsed)) entity = parsed;
+ break;
+ }
+ }
+ return Object.freeze({
+ keyword: result.keywordScore,
+ semantic: result.semanticScore,
+ entity,
+ recency: result.recencyBoost,
+ });
+}
+
+/**
+ * Record one feedback event as its own file and refresh the derived
+ * learned-weights file. The filename derives from the timestamp plus a
+ * content hash, so recording the identical event twice is idempotent.
+ */
+export function recordRecallFeedback(vault: string, event: RecallFeedbackEvent): string {
+ const dir = feedbackDir(vault);
+ mkdirSync(dir, { recursive: true });
+ const body = JSON.stringify(event, null, 2) + "\n";
+ const file = join(dir, `${event.ts}-${fnv1aHex(body)}.json`);
+ writeFileSync(file, body);
+ writeLearnedWeights(vault, computeLearnedWeights(loadFeedbackEvents(vault)));
+ return file;
+}
+
+/** Load all feedback events, sorted by timestamp then path (stable). */
+export function loadFeedbackEvents(vault: string): RecallFeedbackEvent[] {
+ const dir = feedbackDir(vault);
+ let files: string[];
+ try {
+ files = readdirSync(dir).filter((f) => f.endsWith(".json"));
+ } catch {
+ return [];
+ }
+ const out: RecallFeedbackEvent[] = [];
+ for (const f of files.toSorted()) {
+ try {
+ const parsed = JSON.parse(readFileSync(join(dir, f), "utf8")) as RecallFeedbackEvent;
+ const c = parsed.contributions;
+ // Every layer must be a finite number: a malformed contributions
+ // object would otherwise feed NaN into the fold's totals.
+ const contributionsValid =
+ c !== undefined &&
+ c !== null &&
+ [c.keyword, c.semantic, c.entity, c.recency].every(
+ (v) => typeof v === "number" && Number.isFinite(v),
+ );
+ if (
+ typeof parsed.ts === "number" &&
+ (parsed.verdict === "up" || parsed.verdict === "down") &&
+ typeof parsed.resultPath === "string" &&
+ contributionsValid
+ ) {
+ out.push(parsed);
+ }
+ } catch {
+ // One malformed file never breaks the fold.
+ }
+ }
+ out.sort((a, b) => a.ts - b.ts || a.resultPath.localeCompare(b.resultPath));
+ return out;
+}
+
+/**
+ * The deterministic fold. Per layer: each event contributes its
+ * contribution share (this layer's value over the event's total) signed
+ * by the verdict; the layer's multiplier is
+ * `1 + STEP * netSignal / totalEvents`, clamped to the documented
+ * bounds. Order-insensitive by construction (a sum), and a layer that
+ * never contributed stays exactly 1.
+ */
+export function computeLearnedWeights(events: ReadonlyArray<RecallFeedbackEvent>): LearnedWeights {
+ if (events.length === 0) return NEUTRAL_LEARNED_WEIGHTS;
+ const net = { keyword: 0, semantic: 0, entity: 0, recency: 0 };
+ let counted = 0;
+ let latestTs = 0;
+ for (const e of events) {
+ const c = e.contributions;
+ const total = c.keyword + c.semantic + c.entity + c.recency;
+ if (total <= 0) continue; // zero-contribution events carry no layer signal
+ counted++;
+ const sign = e.verdict === "up" ? 1 : -1;
+ net.keyword += (sign * c.keyword) / total;
+ net.semantic += (sign * c.semantic) / total;
+ net.entity += (sign * c.entity) / total;
+ net.recency += (sign * c.recency) / total;
+ if (e.ts > latestTs) latestTs = e.ts;
+ }
+ if (counted === 0) {
+ return Object.freeze({ ...NEUTRAL_LEARNED_WEIGHTS, events: events.length });
+ }
+ const mul = (n: number): number => {
+ const raw = 1 + (LEARNED_WEIGHT_STEP * n) / counted;
+ return round6(Math.min(LEARNED_WEIGHT_MAX, Math.max(LEARNED_WEIGHT_MIN, raw)));
+ };
+ return Object.freeze({
+ keywordMul: mul(net.keyword),
+ semanticMul: mul(net.semantic),
+ entityMul: mul(net.entity),
+ recencyMul: mul(net.recency),
+ events: events.length,
+ updatedAt: latestTs > 0 ? new Date(latestTs).toISOString() : null,
+ });
+}
+
+export function writeLearnedWeights(vault: string, weights: LearnedWeights): void {
+ mkdirSync(join(vault, "Brain", "search"), { recursive: true });
+ writeFileSync(learnedWeightsPath(vault), JSON.stringify(weights, null, 2) + "\n");
+}
+
+export function readLearnedWeights(vault: string): LearnedWeights | null {
+ try {
+ const parsed = JSON.parse(readFileSync(learnedWeightsPath(vault), "utf8")) as LearnedWeights;
+ // All four multipliers must be finite numbers β€” a partially-corrupt
+ // file must not feed NaN into the weight composition.
+ const muls = [parsed.keywordMul, parsed.semanticMul, parsed.entityMul, parsed.recencyMul];
+ if (!muls.every((m) => typeof m === "number" && Number.isFinite(m))) return null;
+ if (typeof parsed.events !== "number") return null;
+ return parsed;
+ } catch {
+ return null;
+ }
+}
+
+/** Delete the derived weights file. The events stay β€” the fold can replay. */
+export function resetLearnedWeights(vault: string): void {
+ rmSync(learnedWeightsPath(vault), { force: true });
+}
+
+/**
+ * Stable fingerprint of the learned-weights state for the query-cache
+ * key: "off" when no derived file exists, else a hash of its content.
+ */
+export function learnedWeightsFingerprint(vault: string): string {
+ const path = learnedWeightsPath(vault);
+ if (!existsSync(path)) return "off";
+ try {
+ return fnv1aHex(readFileSync(path, "utf8"));
+ } catch {
+ return "off";
+ }
+}
+
+/** True when every multiplier is exactly neutral (1.0). */
+export function isNeutralLearnedWeights(w: WeightProfile): boolean {
+ return w.keywordMul === 1 && w.semanticMul === 1 && w.entityMul === 1 && w.recencyMul === 1;
+}
+
+/**
+ * Compose the intent profile with the learned multipliers. Both factors
+ * are bounded ([0.7, 1.4] and [0.8, 1.2]), so the product is naturally
+ * bounded in [0.56, 1.68]; no extra clamp is needed and the composition
+ * stays transparent (each factor is visible in diagnostics).
+ */
+export function composeWeightProfiles(
+ intent: WeightProfile | undefined,
+ learned: WeightProfile,
+): WeightProfile {
+ const base = intent ?? { keywordMul: 1, semanticMul: 1, entityMul: 1, recencyMul: 1 };
+ return Object.freeze({
+ keywordMul: round6(base.keywordMul * learned.keywordMul),
+ semanticMul: round6(base.semanticMul * learned.semanticMul),
+ entityMul: round6(base.entityMul * learned.entityMul),
+ recencyMul: round6(base.recencyMul * learned.recencyMul),
+ });
+}
+
+/** Human/agent-readable summary of the non-neutral learned multipliers. */
+export function learnedWeightsReason(w: WeightProfile): string {
+ const parts: string[] = [];
+ if (w.keywordMul !== 1) parts.push(`kw=${w.keywordMul.toFixed(3)}`);
+ if (w.semanticMul !== 1) parts.push(`sem=${w.semanticMul.toFixed(3)}`);
+ if (w.entityMul !== 1) parts.push(`ent=${w.entityMul.toFixed(3)}`);
+ if (w.recencyMul !== 1) parts.push(`rec=${w.recencyMul.toFixed(3)}`);
+ return `learned_weights: ${parts.join(" ")}`;
+}
+
+export interface CaptureRecallFeedbackInput {
+ readonly query: string;
+ readonly resultPath: string;
+ readonly verdict: "up" | "down";
+ /** Injected clock for deterministic tests. Defaults to Date.now(). */
+ readonly nowMs?: number;
+}
+
+export interface CaptureRecallFeedbackOutcome {
+ readonly file: string;
+ readonly event: RecallFeedbackEvent;
+ readonly learned: LearnedWeights;
+ /** False when the judged path was not in the re-ran result set. */
+ readonly resultFound: boolean;
+}
+
+/**
+ * Shared CLI/MCP capture path: re-run the query, read the judged
+ * result's per-layer contributions at retrieval time, and record the
+ * event. When the path is no longer in the result set the event is
+ * still recorded β€” with zero contributions, which the fold skips for
+ * layer signal but keeps in the audit trail. `search.ts` is imported
+ * lazily because it imports this module for ranking integration (the
+ * same lazy-import seam search.ts itself uses for the indexer).
+ */
+export async function captureRecallFeedback(
+ config: ResolvedSearchConfig,
+ input: CaptureRecallFeedbackInput,
+): Promise<CaptureRecallFeedbackOutcome> {
+ const { search } = await import("./search.ts");
+ const outcome = await search(config, { query: input.query, limit: 50 });
+ const hit = outcome.results.find((r) => r.path === input.resultPath);
+ const contributions: LayerContributions = hit
+ ? contributionsFromResult(hit)
+ : Object.freeze({ keyword: 0, semantic: 0, entity: 0, recency: 0 });
+ const normalized = input.query.trim().replace(/\s+/gu, " ").toLowerCase();
+ const event: RecallFeedbackEvent = Object.freeze({
+ ts: input.nowMs ?? Date.now(),
+ queryHash: fnv1aHex(normalized),
+ resultPath: input.resultPath,
+ verdict: input.verdict,
+ contributions,
+ });
+ const file = recordRecallFeedback(config.vault, event);
+ const learned = readLearnedWeights(config.vault) ?? NEUTRAL_LEARNED_WEIGHTS;
+ return Object.freeze({ file, event, learned, resultFound: hit !== undefined });
+}
diff --git a/src/core/search/index.ts b/src/core/search/index.ts
index 0a311a63..2e931e72 100644
--- a/src/core/search/index.ts
+++ b/src/core/search/index.ts
@@ -65,6 +65,19 @@ export {
type IndexProgressEvent,
} from "./indexer.ts";
export { search } from "./search.ts";
+export {
+ captureRecallFeedback,
+ computeLearnedWeights,
+ feedbackDir,
+ learnedWeightsPath,
+ loadFeedbackEvents,
+ readLearnedWeights,
+ resetLearnedWeights,
+ LEARNED_WEIGHT_MIN,
+ LEARNED_WEIGHT_MAX,
+ type LearnedWeights,
+ type RecallFeedbackEvent,
+} from "./feedback.ts";
const DEFAULTS = {
chunkSize: 800,
@@ -357,6 +370,26 @@ export function resolveSearchConfig(opts: {
"search_cache_ttl_seconds",
{ min: 1 },
);
+ const relationPolarityEnabled = parseBool(
+ envOrConfig(
+ env,
+ config,
+ "OPEN_SECOND_BRAIN_SEARCH_RELATION_POLARITY",
+ "search_relation_polarity_enabled",
+ ),
+ true,
+ "search_relation_polarity_enabled",
+ );
+ const learnedWeightsEnabled = parseBool(
+ envOrConfig(
+ env,
+ config,
+ "OPEN_SECOND_BRAIN_SEARCH_LEARNED_WEIGHTS",
+ "search_learned_weights_enabled",
+ ),
+ false,
+ "search_learned_weights_enabled",
+ );
const recall: ResolvedRecallConfig = Object.freeze({
mmrLambda,
maxHops,
@@ -370,6 +403,8 @@ export function resolveSearchConfig(opts: {
synonymMaxTerms,
cacheEnabled,
cacheTtlSeconds,
+ relationPolarityEnabled,
+ learnedWeightsEnabled,
});
const base: ResolvedSearchConfig = Object.freeze({
diff --git a/src/core/search/relation-polarity.ts b/src/core/search/relation-polarity.ts
new file mode 100644
index 00000000..238e01a8
--- /dev/null
+++ b/src/core/search/relation-polarity.ts
@@ -0,0 +1,261 @@
+/**
+ * Relation-aware recall polarity (recall-trust-suite, Feature A).
+ *
+ * Typed relation edges (src/core/graph/relation-vocab.ts) participate in
+ * ranking with explicit polarity instead of being decorative metadata:
+ *
+ * - `superseded_by` marks the declaring page as a stale predecessor. When
+ * the predecessor matches a query, its score is demoted and the successor
+ * is boosted β€” pulled into the pool when it was not already retrieved β€”
+ * so a stale memory cannot outrank the memory that replaced it.
+ * - `contradicts` is relevant-but-not-endorsing: both endpoints gain a
+ * warning-style `why_retrieved` reason and neither score moves.
+ * - `related` / `extends` / `depends_on` / `refines` grant a small bounded
+ * directional boost to a co-retrieved target β€” always weaker than a
+ * direct text match.
+ *
+ * The pass is pure (no I/O): callers (search.ts) fetch the candidate
+ * documents' typed edges and a successor-chunk lookup, then hand both in.
+ * A pool with zero typed edges passes through bit-identically, so vaults
+ * without typed relations are unaffected.
+ */
+
+import type { BrainSearchResult } from "./types.ts";
+
+/** Multiplier applied to a matched predecessor's score. */
+export const SUPERSEDED_DEMOTION = 0.6;
+/** The successor inherits this share of the predecessor's original score. */
+export const SUCCESSOR_CARRY = 0.9;
+/** Additive boost per positive relation edge between co-retrieved candidates. */
+export const RELATION_BOOST_PER_EDGE = 0.02;
+/** Cap on the total positive relation boost one result can accumulate. */
+export const RELATION_BOOST_CAP = 0.04;
+
+const POSITIVE_RELATIONS = new Set(["related", "extends", "depends_on", "refines"]);
+
+/** One typed relation edge declared by a candidate document. */
+export interface RelationEdge {
+ readonly sourceDocumentId: number;
+ readonly relation: string;
+ /** Relation target as written in frontmatter (normalised wikilink id). */
+ readonly target: string;
+ /** Resolved target document id, or null when the target page is unknown. */
+ readonly targetDocumentId: number | null;
+}
+
+/** Representative document head used when pulling in an absent successor. */
+export interface SuccessorDoc {
+ readonly documentId: number;
+ readonly chunkId: number;
+ readonly path: string;
+ readonly title: string | null;
+ readonly content: string;
+ readonly startLine: number;
+ readonly endLine: number;
+}
+
+export interface RelationPolarityInputs {
+ readonly ranked: ReadonlyArray<BrainSearchResult>;
+ /** Typed edges declared by the ranked candidates' documents. */
+ readonly edges: ReadonlyArray<RelationEdge>;
+ /** Lookup for a successor document absent from the pool; null = unknown. */
+ readonly successorDoc: (documentId: number) => SuccessorDoc | null;
+}
+
+export interface RelationPolarityOptions {
+ /**
+ * History mode: keep matched predecessors undemoted and skip successor
+ * pull-in. Informational reasons still land so callers can see the edge.
+ */
+ readonly includeSuperseded?: boolean;
+}
+
+/**
+ * Per-result effect accumulators. Each is order-insensitive on its own
+ * (min, max, capped sum), and the final score composes them exactly
+ * once β€” so edge application order cannot change the outcome even for
+ * a node that is simultaneously a demoted predecessor, a carried
+ * successor, and a positive-relation target.
+ */
+interface Mutable {
+ result: BrainSearchResult;
+ reasons: string[];
+ /** Multiplier on the original score; min over demotion edges. */
+ demotionFactor: number;
+ /** Successor carry floor; max over carried predecessor scores. */
+ carriedScore: number;
+ /** Additive positive-relation boost; capped sum. */
+ positiveBoost: number;
+}
+
+function clamp01(x: number): number {
+ if (!Number.isFinite(x)) return 0;
+ if (x < 0) return 0;
+ if (x > 1) return 1;
+ return x;
+}
+
+function fmt(x: number): string {
+ return x.toFixed(3);
+}
+
+/**
+ * Apply relation polarity over the assembled candidate pool. Returns a new
+ * re-sorted array; the inputs are never mutated. With zero edges the pool
+ * is returned as-is (same array contents, same order).
+ */
+export function applyRelationPolarity(
+ inputs: RelationPolarityInputs,
+ opts: RelationPolarityOptions,
+): BrainSearchResult[] {
+ if (inputs.edges.length === 0) return [...inputs.ranked];
+ const includeSuperseded = opts.includeSuperseded === true;
+
+ const byDoc = new Map<number, Mutable[]>();
+ const pool: Mutable[] = inputs.ranked.map((result) => {
+ const m: Mutable = {
+ result,
+ reasons: [...result.reasons],
+ demotionFactor: 1,
+ carriedScore: 0,
+ positiveBoost: 0,
+ };
+ const list = byDoc.get(result.documentId);
+ if (list) list.push(m);
+ else byDoc.set(result.documentId, [m]);
+ return m;
+ });
+
+ const pulledIn = new Map<number, Mutable>();
+
+ const successorEntries = (edge: RelationEdge): Mutable[] => {
+ if (edge.targetDocumentId === null) return [];
+ const present = byDoc.get(edge.targetDocumentId);
+ if (present) return present;
+ const already = pulledIn.get(edge.targetDocumentId);
+ if (already) return [already];
+ const doc = inputs.successorDoc(edge.targetDocumentId);
+ if (!doc) return [];
+ const m: Mutable = {
+ result: Object.freeze({
+ documentId: doc.documentId,
+ chunkId: doc.chunkId,
+ path: doc.path,
+ title: doc.title,
+ content: doc.content,
+ startLine: doc.startLine,
+ endLine: doc.endLine,
+ score: 0,
+ keywordScore: 0,
+ semanticScore: 0,
+ linkBoost: 0,
+ recencyBoost: 0,
+ searchType: "link" as const,
+ reasons: Object.freeze([] as string[]),
+ }),
+ reasons: [],
+ demotionFactor: 1,
+ carriedScore: 0,
+ positiveBoost: 0,
+ };
+ pulledIn.set(doc.documentId, m);
+ return [m];
+ };
+
+ // Each branch only ACCUMULATES (min demotion factor, max carry, capped
+ // additive boost); the score composes from the accumulators exactly
+ // once below. Every accumulator is order-insensitive on its own, so
+ // edge application order cannot change the final score β€” even for a
+ // node that is simultaneously a demoted predecessor, a carried
+ // successor, and a positive-relation target.
+ for (const edge of inputs.edges) {
+ if (edge.targetDocumentId !== null && edge.targetDocumentId === edge.sourceDocumentId) {
+ continue; // self-edge: inert
+ }
+ const sources = byDoc.get(edge.sourceDocumentId) ?? [];
+ if (sources.length === 0) continue;
+
+ if (edge.relation === "superseded_by") {
+ for (const src of sources) {
+ pushUnique(src.reasons, `superseded_by: ${edge.target}`);
+ }
+ if (includeSuperseded || edge.targetDocumentId === null) continue;
+ const successors = successorEntries(edge);
+ if (successors.length === 0) continue; // unresolved successor: inert
+ for (const src of sources) {
+ const original = src.result.score;
+ src.demotionFactor = Math.min(src.demotionFactor, SUPERSEDED_DEMOTION);
+ const carried = clamp01(original * SUCCESSOR_CARRY);
+ for (const succ of successors) {
+ succ.carriedScore = Math.max(succ.carriedScore, carried);
+ pushUnique(succ.reasons, `supersedes_matched: ${src.result.path}`);
+ }
+ }
+ continue;
+ }
+
+ if (edge.relation === "contradicts") {
+ for (const src of sources) {
+ pushUnique(src.reasons, `contradicts: ${edge.target}`);
+ }
+ if (edge.targetDocumentId === null) continue;
+ const targets = byDoc.get(edge.targetDocumentId) ?? [];
+ for (const tgt of targets) {
+ for (const src of sources) {
+ pushUnique(tgt.reasons, `contradicted_by: ${src.result.path}`);
+ }
+ }
+ continue;
+ }
+
+ if (POSITIVE_RELATIONS.has(edge.relation)) {
+ if (edge.targetDocumentId === null) continue;
+ const targets = byDoc.get(edge.targetDocumentId) ?? [];
+ for (const tgt of targets) {
+ const head = Math.min(RELATION_BOOST_PER_EDGE, RELATION_BOOST_CAP - tgt.positiveBoost);
+ if (head <= 0) continue;
+ tgt.positiveBoost += head;
+ for (const src of sources) {
+ pushUnique(tgt.reasons, `relation_boost: ${edge.relation} ${src.result.path}`);
+ break; // one reason per edge, not per source chunk
+ }
+ }
+ }
+ // Unknown relation tokens (open vocabulary) carry no polarity: inert.
+ }
+
+ const out = [...pool, ...pulledIn.values()].map((m) => {
+ // Single composition point: demote the original score, let a
+ // successor carry floor it, then add the capped positive boost.
+ const score = clamp01(
+ Math.max(m.result.score * m.demotionFactor, m.carriedScore) + m.positiveBoost,
+ );
+ if (
+ score === m.result.score &&
+ m.reasons.length === m.result.reasons.length &&
+ m.positiveBoost === 0
+ ) {
+ return m.result;
+ }
+ const extras: string[] = [];
+ if (m.positiveBoost > 0) extras.push(`relation_polarity: +${fmt(m.positiveBoost)}`);
+ return Object.freeze({
+ ...m.result,
+ score,
+ reasons: Object.freeze([...m.reasons, ...extras]),
+ });
+ });
+
+ // Same tie-break family as the ranker: score desc, keywordScore desc,
+ // chunkId asc β€” deterministic for equal scores.
+ out.sort((a, b) => {
+ if (b.score !== a.score) return b.score - a.score;
+ if (b.keywordScore !== a.keywordScore) return b.keywordScore - a.keywordScore;
+ return a.chunkId - b.chunkId;
+ });
+ return out;
+}
+
+function pushUnique(list: string[], entry: string): void {
+ if (!list.includes(entry)) list.push(entry);
+}
diff --git a/src/core/search/search.ts b/src/core/search/search.ts
index ad76db05..613da30c 100644
--- a/src/core/search/search.ts
+++ b/src/core/search/search.ts
@@ -14,16 +14,27 @@ import { join } from "node:path";
import { parseFrontmatter } from "../vault.ts";
import { isVisible, normalizeVisibilityScope, pageVisibility } from "../graph/visibility.ts";
import { makeProvider } from "./embeddings/provider.ts";
+import {
+ composeWeightProfiles,
+ isNeutralLearnedWeights,
+ learnedWeightsFingerprint,
+ learnedWeightsReason,
+ readLearnedWeights,
+} from "./feedback.ts";
import { extractEntities } from "./entities.ts";
+import { buildCoverageReport, significantTerms, termIncludedIn } from "./coverage.ts";
import { buildEvidencePack, downrankTerminalEvidenceResults } from "./evidence-pack.ts";
+import type { EvidenceUnionRecord, EvidenceVerification } from "./evidence-pack.ts";
import { runFtsQueryDetailed } from "./fts.ts";
import { mmrRerank } from "./mmr.ts";
import { buildQueryPlan } from "./query-plan.ts";
import { buildCacheKey, getCachedOutcome, putCachedOutcome } from "./query-cache.ts";
import { deriveExpansionTerms, tokenizeForExpansion, DEFAULT_EXPANSION } from "./synonyms.ts";
import { filterByProperties } from "./property-filter.ts";
+import { applyRelationPolarity } from "./relation-polarity.ts";
import { rankResults } from "./ranker.ts";
import { readSessionFocus } from "./session-focus.ts";
+import { mtimeInRange, resolveTimeRange } from "./time-range.ts";
import { expandByTraversal, type TraversalOptions } from "./traversal.ts";
import { Store } from "./store.ts";
import { SearchError } from "./types.ts";
@@ -74,6 +85,8 @@ function configFingerprint(config: ResolvedSearchConfig): string {
intent: r.intentEnabled,
syn: r.synonymEnabled,
synMax: r.synonymMaxTerms,
+ relPol: r.relationPolarityEnabled,
+ lw: r.learnedWeightsEnabled,
});
}
@@ -184,6 +197,12 @@ export async function search(
opts.sessionFocus === undefined ? readSessionFocus(config, Date.now()) : opts.sessionFocus;
const keywordQuery = structuredKeywordQuery(query, structured);
const semanticLaneQuery = structuredSemanticQuery(structured);
+ // Time-aware recall (recall-trust-suite): resolve since/until up front
+ // so invalid input fails fast, before any store I/O.
+ const timeRange =
+ opts.since !== undefined || opts.until !== undefined
+ ? resolveTimeRange({ since: opts.since, until: opts.until }, Date.now())
+ : null;
// Query plan (v0.20.0): one structural pass yields the intent weight
// profile and the cache key. Pure; no I/O. Expanded terms (if any) are
@@ -199,7 +218,10 @@ export async function search(
// and TTL expiry invalidate it. Expansion terms are not in the key:
// they are determined by (query, index content) and any content
// change bumps the generation. The cache write is best-effort.
- const cacheEnabled = config.recall.cacheEnabled;
+ // A time-filtered query bypasses the cache: a relative range
+ // ("24h") resolves to a different absolute window on every call, so
+ // a cached row would serve a stale window within the TTL.
+ const cacheEnabled = config.recall.cacheEnabled && timeRange === null;
const ttlMs = config.recall.cacheTtlSeconds * 1000;
let cacheKey: string | null = null;
let generation = "";
@@ -218,7 +240,16 @@ export async function search(
keywordOnly: false,
sessionFocus,
};
- cacheKey = buildCacheKey(keyOpts, basePlan.planHash, configFingerprint(config));
+ // The learned-weights state changes results outside the static
+ // config, so its fingerprint joins the key (recall-trust-suite).
+ const lwFp = config.recall.learnedWeightsEnabled
+ ? learnedWeightsFingerprint(config.vault)
+ : "off";
+ cacheKey = buildCacheKey(
+ keyOpts,
+ basePlan.planHash,
+ `${configFingerprint(config)}|lw:${lwFp}`,
+ );
const hit = getCachedOutcome(store, cacheKey, generation, ttlMs, Date.now());
if (hit) return hit;
} catch {
@@ -270,7 +301,16 @@ export async function search(
for (const w of kwOutcome.warnings) warnings.push(w);
}
}
- const weightProfile = config.recall.intentEnabled ? plan.weightProfile : undefined;
+ const intentProfile = config.recall.intentEnabled ? plan.weightProfile : undefined;
+ // Learned recall weights (recall-trust-suite): opt-in multipliers
+ // derived from explicit feedback compose with the intent profile.
+ // Both factors are bounded, so the product is too; neutral learned
+ // weights leave ranking bit-identical.
+ const learned = config.recall.learnedWeightsEnabled ? readLearnedWeights(config.vault) : null;
+ const learnedActive = learned !== null && !isNeutralLearnedWeights(learned);
+ const weightProfile = learnedActive
+ ? composeWeightProfiles(intentProfile, learned)
+ : intentProfile;
// Semantic candidates (may be skipped).
let semHits: ReturnType<Store["semanticTopK"]> = [];
@@ -295,7 +335,10 @@ export async function search(
for (const h of semHits) allChunkIds.add(h.chunkId);
const idsList = Array.from(allChunkIds);
if (idsList.length === 0) {
- const evidencePack = opts.evidencePack === true ? buildEvidencePack(query, []) : undefined;
+ const evidencePack =
+ opts.evidencePack === true
+ ? buildEvidencePack(query, [], buildEvidenceVerification(store, query, [], pathPrefix))
+ : undefined;
return finalize(
Object.freeze({
results: Object.freeze([] as ReadonlyArray<BrainSearchResult>),
@@ -307,6 +350,19 @@ export async function search(
}
const hydrated = store.hydrateChunks(idsList);
+
+ // Time-aware recall (recall-trust-suite): drop out-of-range
+ // candidates BEFORE ranking so every later phase (traversal seeds,
+ // MMR, relation polarity) sees only in-range candidates.
+ if (timeRange !== null) {
+ const inRange = (chunkId: number): boolean => {
+ const h = hydrated.get(chunkId);
+ return h !== undefined && mtimeInRange(h.mtime, timeRange);
+ };
+ kwHits = kwHits.filter((h) => inRange(h.chunkId));
+ semHits = semHits.filter((h) => inRange(h.chunkId));
+ }
+
const inboundLinkSources = store.inboundLinkSources(idsList);
const tagsByDoc = store.tagsByChunkDocument(idsList);
@@ -428,7 +484,26 @@ export async function search(
const wideCap = Math.max(limit * 5, 50, limit * 3, 30);
if (wideCap > rankLimit) assembled = assemble(wideCap);
}
- const filtered = applyStructuredExclusions(assembled.visible, structured).slice(0, limit);
+ const excluded = applyStructuredExclusions(assembled.visible, structured);
+ // Relation polarity (recall-trust-suite): typed relation edges adjust
+ // the pool BEFORE the final slice so a demoted predecessor can fall
+ // out of the window and a pulled-in successor can enter it. A pool
+ // whose documents declare no typed edges passes through untouched.
+ const polarized = config.recall.relationPolarityEnabled
+ ? applyRelationPolarityPhase(store, excluded, opts.includeSuperseded === true)
+ : excluded;
+ const sliced = polarized.slice(0, limit);
+ // Explainability: when learned weights affected this ranking, every
+ // surfaced result says so (acceptance: "search explanations show
+ // when learned weights affected a result").
+ const filtered = learnedActive
+ ? sliced.map((r) =>
+ Object.freeze({
+ ...r,
+ reasons: Object.freeze([...r.reasons, learnedWeightsReason(learned)]),
+ }),
+ )
+ : sliced;
// Typed graph semantics (v3): surface the typed relations each
// result page declares in its frontmatter. Computed here from the
@@ -444,7 +519,13 @@ export async function search(
? downrankTerminalEvidenceResults(withStructuredReasons)
: withStructuredReasons;
const evidencePack =
- opts.evidencePack === true ? buildEvidencePack(query, finalResults) : undefined;
+ opts.evidencePack === true
+ ? buildEvidencePack(
+ query,
+ finalResults,
+ buildEvidenceVerification(store, query, finalResults, pathPrefix),
+ )
+ : undefined;
return finalize(
Object.freeze({
@@ -519,6 +600,117 @@ function applyTraversal(
);
}
+/** Cap on extra records fetched per uncovered term (Feature C union). */
+const UNION_RECORDS_PER_TERM = 2;
+/** Cap on the total recall-union fetch per query. */
+const UNION_RECORDS_TOTAL = 8;
+
+/**
+ * Coverage verification for evidence-pack mode (recall-trust-suite,
+ * Feature C): corpus document frequencies for the significant terms,
+ * the covered-term set over the returned results, and a bounded
+ * per-token recall union β€” for each term the ranked set left uncovered,
+ * fetch up to {@link UNION_RECORDS_PER_TERM} records that DO cover it
+ * (evidence can span records the primary ranking never surfaced).
+ */
+function buildEvidenceVerification(
+ store: Store,
+ query: string,
+ results: ReadonlyArray<BrainSearchResult>,
+ pathPrefix: string | undefined,
+): EvidenceVerification {
+ const terms = significantTerms(query);
+ const dfByTerm = store.documentFrequencies(terms);
+ const documentCount = store.counts().documents;
+ const covered = new Set<string>();
+ for (const r of results) {
+ const haystack = `${r.path}\n${r.title ?? ""}\n${r.content}`;
+ for (const t of terms) {
+ if (!covered.has(t) && termIncludedIn(haystack, t)) covered.add(t);
+ }
+ }
+ const coverage = buildCoverageReport({
+ significantTerms: terms,
+ coveredTerms: covered,
+ documentCount,
+ dfByTerm,
+ });
+
+ const unionRecords: EvidenceUnionRecord[] = [];
+ for (const t of coverage.terms) {
+ if (t.covered || t.df === 0) continue; // nothing in the corpus covers a df=0 term
+ if (unionRecords.length >= UNION_RECORDS_TOTAL) break;
+ const outcome = runFtsQueryDetailed(store, t.term, {
+ limit: UNION_RECORDS_PER_TERM,
+ pathPrefix,
+ });
+ const ids = outcome.hits.map((h) => h.chunkId);
+ const hydrated = store.hydrateChunks(ids);
+ for (const hit of outcome.hits) {
+ if (unionRecords.length >= UNION_RECORDS_TOTAL) break;
+ const h = hydrated.get(hit.chunkId);
+ if (!h) continue;
+ unionRecords.push(
+ Object.freeze({
+ term: t.term,
+ path: h.path,
+ documentId: h.documentId,
+ chunkId: h.chunkId,
+ }),
+ );
+ }
+ }
+ return Object.freeze({ coverage, unionRecords: Object.freeze(unionRecords) });
+}
+
+/**
+ * Fetch the typed relation edges declared by the pool's documents and
+ * delegate the polarity adjustment to the pure `applyRelationPolarity`.
+ * Successor pull-in reuses the traversal layer's representative-chunk
+ * mechanism (document head as the surfaced chunk).
+ */
+function applyRelationPolarityPhase(
+ store: Store,
+ ranked: ReadonlyArray<BrainSearchResult>,
+ includeSuperseded: boolean,
+): ReadonlyArray<BrainSearchResult> {
+ if (ranked.length === 0) return ranked;
+ const docIds = Array.from(new Set(ranked.map((r) => r.documentId)));
+ const edges = store.typedRelationEdgesForDocuments(docIds);
+ if (edges.length === 0) return ranked;
+
+ const present = new Set(docIds);
+ const successorIds = Array.from(
+ new Set(
+ edges
+ .map((e) => e.targetDocumentId)
+ .filter((id): id is number => id !== null && !present.has(id)),
+ ),
+ );
+ const reps = store.representativeChunks(successorIds);
+
+ return applyRelationPolarity(
+ {
+ ranked,
+ edges,
+ successorDoc: (docId) => {
+ const h = reps.get(docId);
+ if (!h) return null;
+ return {
+ documentId: h.documentId,
+ chunkId: h.chunkId,
+ path: h.path,
+ title: h.title,
+ content: h.content,
+ startLine: h.startLine,
+ endLine: h.endLine,
+ };
+ },
+ },
+ { includeSuperseded },
+ );
+}
+
function applyPropertyFilter(
ranked: ReadonlyArray<BrainSearchResult>,
filters: ReadonlyMap<string, ReadonlyArray<string>>,
diff --git a/src/core/search/store.ts b/src/core/search/store.ts
index 53610e23..da99e480 100644
--- a/src/core/search/store.ts
+++ b/src/core/search/store.ts
@@ -894,6 +894,91 @@ export class Store {
return out;
}
+ /**
+ * Typed relation edges declared by the given documents, with the
+ * target resolved to a document id when possible (recall-trust-suite,
+ * relation polarity). Wikilink-style relation targets are usually bare
+ * ids (`[[note]]` β†’ `note`) that the generic `resolveLinkTargets`
+ * exact-path pass cannot match against `note.md`, so this query also
+ * tries `<target>.md` and β€” when unambiguous β€” a basename match.
+ * Ambiguous basenames stay unresolved (deterministic inertness beats
+ * guessing the wrong page).
+ */
+ typedRelationEdgesForDocuments(documentIds: ReadonlyArray<number>): Array<{
+ readonly sourceDocumentId: number;
+ readonly relation: string;
+ readonly target: string;
+ readonly targetDocumentId: number | null;
+ }> {
+ if (documentIds.length === 0) return [];
+ const placeholders = documentIds.map(() => "?").join(",");
+ const rows = this.db
+ .query<
+ {
+ source_document_id: number;
+ relation: string;
+ target_path: string | null;
+ resolved_target_id: number | null;
+ },
+ number[]
+ >(
+ "SELECT l.source_document_id, l.relation, l.target_path, " +
+ " COALESCE(" +
+ " l.target_document_id, " +
+ " (SELECT d.id FROM documents d WHERE d.path = l.target_path || '.md'), " +
+ " (SELECT d.id FROM documents d WHERE d.path LIKE '%/' || l.target_path || '.md' " +
+ " AND 1 = (SELECT COUNT(*) FROM documents d2 " +
+ " WHERE d2.path LIKE '%/' || l.target_path || '.md'))" +
+ " ) AS resolved_target_id " +
+ "FROM links l " +
+ `WHERE l.source_document_id IN (${placeholders}) AND l.relation IS NOT NULL ` +
+ "ORDER BY l.id",
+ )
+ .all(...(documentIds as number[]));
+ const out: Array<{
+ sourceDocumentId: number;
+ relation: string;
+ target: string;
+ targetDocumentId: number | null;
+ }> = [];
+ for (const r of rows) {
+ const target = r.target_path ?? "";
+ if (target === "") continue;
+ out.push({
+ sourceDocumentId: r.source_document_id,
+ relation: r.relation,
+ target,
+ targetDocumentId: r.resolved_target_id,
+ });
+ }
+ return out;
+ }
+
+ /**
+ * Corpus document frequency per term (recall-trust-suite, coverage
+ * engine): how many distinct documents match each term in FTS. Each
+ * term is quoted so FTS5 metacharacters stay literal. A term that
+ * fails to query (e.g. tokenizer edge case) counts as 0 rather than
+ * failing the search.
+ */
+ documentFrequencies(terms: ReadonlyArray<string>): Map<string, number> {
+ const out = new Map<string, number>();
+ if (terms.length === 0) return out;
+ const q = this.db.query<{ n: number }, [string]>(
+ "SELECT COUNT(DISTINCT c.document_id) AS n " +
+ "FROM chunk_fts JOIN chunks c ON c.id = chunk_fts.rowid " +
+ "WHERE chunk_fts MATCH ?",
+ );
+ for (const term of terms) {
+ try {
+ out.set(term, q.get(`"${term.replace(/"/g, '""')}"`)?.n ?? 0);
+ } catch {
+ out.set(term, 0);
+ }
+ }
+ return out;
+ }
+
// ── search ─────────────────────────────────────────────────────────────────
ftsIntegrityCounts(): { readonly chunks: number; readonly ftsRows: number } {
diff --git a/src/core/search/time-range.ts b/src/core/search/time-range.ts
new file mode 100644
index 00000000..112e26ff
--- /dev/null
+++ b/src/core/search/time-range.ts
@@ -0,0 +1,119 @@
+/**
+ * Time-aware recall (recall-trust-suite, Feature D): parse the `since` /
+ * `until` query parameters into absolute unix-ms bounds.
+ *
+ * Accepted forms:
+ * - ISO datetime β€” `2026-05-01T10:30:00Z` (passed through)
+ * - ISO date β€” `2026-05-01` (day-start for `since`, day-end for
+ * `until`, UTC, so a bare until-date includes its day)
+ * - relative β€” `today`, `yesterday`, `last week`, `last month`
+ * - shorthand β€” `<n>h` / `<n>d` / `<n>w` back from now
+ *
+ * Pure against an injected clock β€” same input and now, same output β€”
+ * and deterministic across locales (no natural-language month names,
+ * no local timezone: everything resolves in UTC). Unparseable input
+ * throws `SearchError("INVALID_INPUT")` β€” explicit, never silent.
+ */
+
+import { SearchError } from "./types.ts";
+
+const HOUR_MS = 60 * 60 * 1000;
+const DAY_MS = 24 * HOUR_MS;
+const WEEK_MS = 7 * DAY_MS;
+
+/** `since` snaps to range starts, `until` to range ends (inclusive). */
+export type RangeEdge = "since" | "until";
+
+const ISO_DATE_RE = /^(\d{4})-(\d{2})-(\d{2})$/;
+const SHORTHAND_RE = /^(\d{1,4})([hdw])$/;
+
+function utcDayStart(ms: number): number {
+ const d = new Date(ms);
+ return Date.UTC(d.getUTCFullYear(), d.getUTCMonth(), d.getUTCDate());
+}
+
+function invalid(raw: string): SearchError {
+ return new SearchError(
+ "INVALID_INPUT",
+ `unparseable time point: ${JSON.stringify(raw)} ` +
+ "(expected ISO date/datetime, 'today', 'yesterday', 'last week', 'last month', or <n>h/<n>d/<n>w)",
+ );
+}
+
+/** Resolve one time point against the injected clock. Throws on junk. */
+export function parseTimePoint(raw: string, nowMs: number, edge: RangeEdge): number {
+ const text = raw.trim().toLowerCase();
+ if (text === "") throw invalid(raw);
+
+ if (text === "today") {
+ const start = utcDayStart(nowMs);
+ return edge === "since" ? start : nowMs;
+ }
+ if (text === "yesterday") {
+ const start = utcDayStart(nowMs) - DAY_MS;
+ return edge === "since" ? start : start + DAY_MS - 1;
+ }
+ if (text === "last week") return nowMs - WEEK_MS;
+ if (text === "last month") return nowMs - 30 * DAY_MS;
+
+ const shorthand = SHORTHAND_RE.exec(text);
+ if (shorthand) {
+ const n = Number(shorthand[1]);
+ const unit = shorthand[2] === "h" ? HOUR_MS : shorthand[2] === "d" ? DAY_MS : WEEK_MS;
+ return nowMs - n * unit;
+ }
+
+ const date = ISO_DATE_RE.exec(text);
+ if (date) {
+ const ms = Date.UTC(Number(date[1]), Number(date[2]) - 1, Number(date[3]));
+ // Reject phantom dates like 2026-13-45 that Date.UTC would roll over.
+ const check = new Date(ms);
+ if (
+ check.getUTCFullYear() !== Number(date[1]) ||
+ check.getUTCMonth() !== Number(date[2]) - 1 ||
+ check.getUTCDate() !== Number(date[3])
+ ) {
+ throw invalid(raw);
+ }
+ return edge === "since" ? ms : ms + DAY_MS - 1;
+ }
+
+ // Full ISO datetime (with time component). Require a "T" so bare
+ // words never sneak through. Date.parse treats an offset-less
+ // datetime as LOCAL time, which would make the resolved bounds
+ // machine-dependent β€” normalise to UTC by appending "Z" when no
+ // explicit designator is present, preserving the all-UTC contract.
+ if (text.includes("t")) {
+ const trimmed = raw.trim();
+ const hasOffset = /(?:z|[+-]\d{2}:?\d{2})$/i.test(trimmed);
+ const parsed = Date.parse(hasOffset ? trimmed : `${trimmed}Z`);
+ if (Number.isFinite(parsed)) return parsed;
+ }
+ throw invalid(raw);
+}
+
+export interface ResolvedTimeRange {
+ readonly sinceMs: number | null;
+ readonly untilMs: number | null;
+}
+
+/** Resolve both edges and validate their order. Absent fields stay open. */
+export function resolveTimeRange(
+ opts: { readonly since?: string; readonly until?: string },
+ nowMs: number,
+): ResolvedTimeRange {
+ const sinceMs = opts.since !== undefined ? parseTimePoint(opts.since, nowMs, "since") : null;
+ const untilMs = opts.until !== undefined ? parseTimePoint(opts.until, nowMs, "until") : null;
+ if (sinceMs !== null && untilMs !== null && sinceMs > untilMs) {
+ throw new SearchError("INVALID_INPUT", "'since' must not be after 'until'");
+ }
+ return Object.freeze({ sinceMs, untilMs });
+}
+
+/** True when a document mtime (unix seconds) falls inside the range. */
+export function mtimeInRange(mtimeSeconds: number, range: ResolvedTimeRange): boolean {
+ const ms = mtimeSeconds * 1000;
+ if (range.sinceMs !== null && ms < range.sinceMs) return false;
+ if (range.untilMs !== null && ms > range.untilMs) return false;
+ return true;
+}
diff --git a/src/core/search/types.ts b/src/core/search/types.ts
index bdb0b422..c40d64f0 100644
--- a/src/core/search/types.ts
+++ b/src/core/search/types.ts
@@ -204,6 +204,23 @@ export interface SearchOptions {
readonly sessionFocus?: SearchSessionFocus | null;
/** Opt-in verified evidence pack diagnostics. Omitted preserves the legacy search outcome shape. */
readonly evidencePack?: boolean;
+ /**
+ * History mode for relation polarity (recall-trust-suite). When true a
+ * matched predecessor (`superseded_by` declarer) keeps its rank and no
+ * successor is pulled in; informational reasons still land. Default
+ * false: stale predecessors are demoted below their successor.
+ */
+ readonly includeSuperseded?: boolean;
+ /**
+ * Time-aware recall (recall-trust-suite). Accepts ISO dates and
+ * datetimes, `today` / `yesterday` / `last week` / `last month`, and
+ * `<n>h` / `<n>d` / `<n>w` shorthand β€” see `time-range.ts`. Filters
+ * candidates by document mtime before ranking. Time-filtered queries
+ * bypass the query cache (a relative range resolves to a different
+ * absolute window every call).
+ */
+ readonly since?: string;
+ readonly until?: string;
}
export interface SearchOutcome {
@@ -275,6 +292,23 @@ export interface ResolvedRecallConfig {
*/
readonly cacheEnabled: boolean;
readonly cacheTtlSeconds: number;
+ /**
+ * Relation-aware recall polarity (recall-trust-suite). When true
+ * (default) typed relation edges affect ranking: `superseded_by`
+ * demotes the matched predecessor and boosts/pulls in the successor,
+ * `contradicts` adds warning reasons, positive relations grant a small
+ * bounded boost. Vaults without typed relations rank bit-identically
+ * either way; this switch exists as the explicit kill switch.
+ */
+ readonly relationPolarityEnabled: boolean;
+ /**
+ * Retrieval feedback loop (recall-trust-suite). Off by default: when
+ * true, learned per-layer multipliers derived from explicit recall
+ * feedback (`Brain/search/learned-weights.json`) compose with the
+ * intent weight profile during ranking. Bounded, deterministic,
+ * resettable β€” see `feedback.ts`.
+ */
+ readonly learnedWeightsEnabled: boolean;
}
export interface ResolvedSearchConfig {
diff --git a/src/mcp/search-tools.ts b/src/mcp/search-tools.ts
index f571dc9a..8dfdc52b 100644
--- a/src/mcp/search-tools.ts
+++ b/src/mcp/search-tools.ts
@@ -11,6 +11,7 @@
*/
import {
+ captureRecallFeedback,
evaluateSurfacingGate,
indexStatus,
resolveSearchConfig,
@@ -22,7 +23,7 @@ import type { BrainSearchResult, SearchOutcome } from "../core/search/index.ts";
import { withTimeout } from "../core/search/with-timeout.ts";
import { INTERNAL_ERROR, INVALID_PARAMS, MCPError } from "./protocol.ts";
import type { ServerContext, ToolDefinition } from "./tools.ts";
-import { coerceBoolOptional, coerceStringOptional } from "./coerce.ts";
+import { coerceBoolOptional, coerceStr, coerceStringOptional } from "./coerce.ts";
import { MCP_PREVIEW_BUDGET } from "./preview-budget.ts";
import { deriveRecallHint } from "../core/search/recall-hint.ts";
import { emitRecallTelemetry } from "../core/brain/recall-telemetry.ts";
@@ -39,6 +40,23 @@ const SEARCH_INPUT_SCHEMA: Record<string, unknown> = {
focus_query: { type: "string", minLength: 1, maxLength: 1000 },
focus_path_prefix: { type: "string", minLength: 1, maxLength: 256 },
evidence_pack: { type: "boolean" },
+ 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:
+ "Time-aware recall: only documents modified at/after this point. ISO date/datetime, 'today', 'yesterday', 'last week', 'last month', or <n>h/<n>d/<n>w.",
+ },
+ until: {
+ type: "string",
+ maxLength: 64,
+ description:
+ "Time-aware recall: only documents modified at/before this point. Same forms as 'since'.",
+ },
limit: { type: "integer", minimum: 1, maximum: MCP_LIMIT_MAX },
semantic: { type: "boolean" },
keyword_only: { type: "boolean" },
@@ -248,6 +266,9 @@ async function toolBrainSearch(
const keywordOnly = coerceBoolOptional(args, "keyword_only") ?? false;
const pathPrefix = coerceStringOptional(args, "path_prefix", 256);
const evidencePack = coerceBoolOptional(args, "evidence_pack") ?? false;
+ const includeSuperseded = coerceBoolOptional(args, "include_superseded") ?? false;
+ const since = coerceStringOptional(args, "since", 64);
+ const until = coerceStringOptional(args, "until", 64);
const telemetry = coerceBoolOptional(args, "telemetry") ?? false;
const telemetryHost = coerceStringOptional(args, "telemetry_host", 200) ?? "mcp";
const telemetrySessionId = coerceStringOptional(args, "session_id", 512);
@@ -289,6 +310,9 @@ async function toolBrainSearch(
...(structuredQuery !== undefined ? { structuredQuery } : {}),
...(sessionFocus !== undefined ? { sessionFocus } : {}),
...(evidencePack ? { evidencePack: true } : {}),
+ ...(includeSuperseded ? { includeSuperseded: true } : {}),
+ ...(since !== undefined ? { since } : {}),
+ ...(until !== undefined ? { until } : {}),
}),
SEARCH_TIMEOUT_MS,
searchTimeoutError,
@@ -398,6 +422,34 @@ function mcpEvidencePack(
})),
dropped_candidates: pack.droppedCandidates,
abstention: pack.abstention,
+ ...(pack.idfWeightedCoverage !== undefined
+ ? { idf_weighted_coverage: pack.idfWeightedCoverage }
+ : {}),
+ ...(pack.rareTerms !== undefined ? { rare_terms: pack.rareTerms } : {}),
+ ...(pack.uncoveredRareTerms !== undefined
+ ? { uncovered_rare_terms: pack.uncoveredRareTerms }
+ : {}),
+ ...(pack.unionRecords !== undefined
+ ? {
+ union_records: pack.unionRecords.map((r) => ({
+ term: r.term,
+ path: r.path,
+ document_id: r.documentId,
+ chunk_id: r.chunkId,
+ })),
+ }
+ : {}),
+ ...(pack.completeness !== undefined
+ ? {
+ completeness: {
+ verdict: pack.completeness.verdict,
+ idf_weighted_coverage: pack.completeness.idfWeightedCoverage,
+ covered_terms: pack.completeness.coveredTerms,
+ uncovered_terms: pack.completeness.uncoveredTerms,
+ uncovered_but_present_in_corpus: pack.completeness.uncoveredButPresentInCorpus,
+ },
+ }
+ : {}),
};
}
@@ -423,7 +475,64 @@ async function toolBrainRecallGate(
};
}
+const RECALL_FEEDBACK_INPUT_SCHEMA: Record<string, unknown> = {
+ type: "object",
+ properties: {
+ query: { type: "string", minLength: 1, maxLength: 2000 },
+ result_path: { type: "string", minLength: 1, maxLength: 512 },
+ verdict: { type: "string", enum: ["up", "down"] },
+ },
+ required: ["query", "result_path", "verdict"],
+ additionalProperties: false,
+};
+
+const RECALL_FEEDBACK_OUTPUT_SCHEMA: NonNullable<ToolDefinition["outputSchema"]> = {
+ type: "object",
+ properties: {
+ recorded: { type: "boolean" },
+ result_found: { type: "boolean" },
+ learned: { type: "object" },
+ },
+ required: ["recorded", "result_found", "learned"],
+};
+
+/**
+ * `brain_recall_feedback` (recall-trust-suite): record one explicit
+ * per-result recall feedback event. The judged result's per-layer
+ * contributions are captured by re-running the query; the learned
+ * weights refresh deterministically from the full event set.
+ */
+async function toolBrainRecallFeedback(
+ ctx: ServerContext,
+ args: Record<string, unknown>,
+): Promise<unknown> {
+ const query = coerceStr(args, "query")!;
+ const resultPath = coerceStr(args, "result_path")!;
+ const verdict = coerceStr(args, "verdict")!;
+ if (verdict !== "up" && verdict !== "down") {
+ throw new MCPError(INVALID_PARAMS, "argument 'verdict' must be 'up' or 'down'");
+ }
+ const config = resolveSearchConfig({
+ vault: ctx.vault,
+ configPath: ctx.configPath ?? undefined,
+ });
+ const outcome = await captureRecallFeedback(config, { query, resultPath, verdict });
+ return {
+ recorded: true,
+ result_found: outcome.resultFound,
+ learned: outcome.learned,
+ };
+}
+
export const SEARCH_TOOLS: ReadonlyArray<ToolDefinition> = Object.freeze([
+ {
+ name: "brain_recall_feedback",
+ description:
+ "Record explicit recall feedback (up/down) for one search result. Feeds the deterministic learned-weight fold; events land under Brain/search/feedback/.",
+ inputSchema: RECALL_FEEDBACK_INPUT_SCHEMA,
+ outputSchema: RECALL_FEEDBACK_OUTPUT_SCHEMA,
+ handler: toolBrainRecallFeedback,
+ },
{
name: "brain_recall_gate",
description:
diff --git a/tests/cli/search-feedback-cli.test.ts b/tests/cli/search-feedback-cli.test.ts
new file mode 100644
index 00000000..ffced1e9
--- /dev/null
+++ b/tests/cli/search-feedback-cli.test.ts
@@ -0,0 +1,93 @@
+/**
+ * CLI tests for `o2b search feedback` and `o2b search weights`
+ * (recall-trust-suite, Feature B).
+ */
+
+import { afterEach, beforeEach, expect, test } from "bun:test";
+import { existsSync, mkdirSync, mkdtempSync, readdirSync, rmSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+
+import { runCli } from "../helpers/run-cli.ts";
+import { feedbackDir, learnedWeightsPath } from "../../src/core/search/feedback.ts";
+
+let tmp: string;
+let vault: string;
+let config: string;
+
+beforeEach(async () => {
+ tmp = mkdtempSync(join(tmpdir(), "o2b-search-fb-cli-"));
+ vault = join(tmp, "vault");
+ mkdirSync(vault, { recursive: true });
+ config = join(tmp, "config.yaml");
+ writeFileSync(config, `vault: "${vault}"\n`);
+ writeFileSync(join(vault, "note.md"), "# Note\n\nthe quarterly ledger reconciliation runbook\n");
+ const out = await runCli(["search", "index"], {
+ env: { OPEN_SECOND_BRAIN_CONFIG: config },
+ });
+ expect(out.returncode).toBe(0);
+});
+
+afterEach(() => {
+ rmSync(tmp, { recursive: true, force: true });
+});
+
+test("search feedback records an event and search weights reports it", async () => {
+ const fb = await runCli(
+ [
+ "search",
+ "feedback",
+ "--query",
+ "quarterly ledger reconciliation",
+ "--result",
+ "note.md",
+ "--verdict",
+ "up",
+ "--json",
+ ],
+ { env: { OPEN_SECOND_BRAIN_CONFIG: config } },
+ );
+ expect(fb.returncode).toBe(0);
+ const fbJson = JSON.parse(fb.stdout) as { recorded: boolean; learned: { events: number } };
+ expect(fbJson.recorded).toBe(true);
+ expect(fbJson.learned.events).toBe(1);
+ expect(readdirSync(feedbackDir(vault))).toHaveLength(1);
+
+ const w = await runCli(["search", "weights", "--json"], {
+ env: { OPEN_SECOND_BRAIN_CONFIG: config },
+ });
+ expect(w.returncode).toBe(0);
+ const wJson = JSON.parse(w.stdout) as {
+ learned: { events: number } | null;
+ base: { keywordWeight: number };
+ enabled: boolean;
+ bounds: { min: number; max: number };
+ };
+ expect(wJson.learned?.events).toBe(1);
+ expect(wJson.base.keywordWeight).toBeGreaterThan(0);
+ expect(wJson.bounds.min).toBeLessThan(1);
+});
+
+test("search weights --reset removes the derived file but keeps events", async () => {
+ await runCli(
+ ["search", "feedback", "--query", "ledger", "--result", "note.md", "--verdict", "down"],
+ { env: { OPEN_SECOND_BRAIN_CONFIG: config } },
+ );
+ expect(existsSync(learnedWeightsPath(vault))).toBe(true);
+
+ const reset = await runCli(["search", "weights", "--reset"], {
+ env: { OPEN_SECOND_BRAIN_CONFIG: config },
+ });
+ expect(reset.returncode).toBe(0);
+ expect(existsSync(learnedWeightsPath(vault))).toBe(false);
+ expect(readdirSync(feedbackDir(vault))).toHaveLength(1);
+});
+
+test("search feedback rejects an invalid verdict with exit 2", async () => {
+ const out = await runCli(
+ ["search", "feedback", "--query", "ledger", "--result", "note.md", "--verdict", "maybe"],
+ { env: { OPEN_SECOND_BRAIN_CONFIG: config } },
+ );
+ expect(out.returncode).toBe(2);
+ expect(out.stderr).toContain("verdict");
+});
diff --git a/tests/cli/search.test.ts b/tests/cli/search.test.ts
index 255a4fe0..6e11c00a 100644
--- a/tests/cli/search.test.ts
+++ b/tests/cli/search.test.ts
@@ -247,3 +247,28 @@ test("the default verb is `query` when first positional is unknown", async () =>
expect(out.returncode).toBe(0);
expect(out.stdout).toContain("a.md");
});
+
+test("search --evidence-pack --json exposes verification fields (union, completeness)", async () => {
+ writeVaultFile("alpha-note.md", "# Alpha\n\nthe alpha subsystem owns the export pipeline");
+ writeVaultFile("zephyr-note.md", "# Zephyr\n\nthe zephyr daemon owns the import pipeline");
+ await runCli(["search", "index"], { env: { OPEN_SECOND_BRAIN_CONFIG: config } });
+
+ const out = await runCli(["search", "alpha zephyr", "--evidence-pack", "--json"], {
+ env: { OPEN_SECOND_BRAIN_CONFIG: config },
+ });
+ expect(out.returncode).toBe(0);
+ const json = JSON.parse(out.stdout) as {
+ evidence_pack: {
+ idf_weighted_coverage: number;
+ rare_terms: string[];
+ uncovered_rare_terms: string[];
+ union_records: Array<{ term: string; path: string }>;
+ completeness: { verdict: string; uncovered_but_present_in_corpus: string[] };
+ };
+ };
+ const pack = json.evidence_pack;
+ expect(typeof pack.idf_weighted_coverage).toBe("number");
+ expect(pack.union_records.map((r) => r.term).toSorted()).toEqual(["alpha", "zephyr"]);
+ expect(pack.completeness.verdict).toBe("sparse");
+ expect(pack.completeness.uncovered_but_present_in_corpus.toSorted()).toEqual(["alpha", "zephyr"]);
+});
diff --git a/tests/core/search/completeness.test.ts b/tests/core/search/completeness.test.ts
new file mode 100644
index 00000000..315f9659
--- /dev/null
+++ b/tests/core/search/completeness.test.ts
@@ -0,0 +1,96 @@
+/**
+ * Search-completeness guard (recall-trust-suite, Feature E).
+ *
+ * A deterministic completeness verdict over the returned results,
+ * computed from the same coverage engine Feature C uses: `complete`
+ * when the IDF-weighted coverage reaches 0.8, `partial` at 0.4, else
+ * `sparse`. The false-absence guard lists every uncovered term the
+ * corpus DOES contain, so a downstream summarizer cannot honestly claim
+ * "the vault has nothing on X" while X sits in an unreturned page.
+ */
+
+import { test, expect, beforeEach, afterEach, describe } from "bun:test";
+
+import {
+ buildCompletenessReport,
+ buildCoverageReport,
+ COMPLETENESS_COMPLETE_THRESHOLD,
+ COMPLETENESS_PARTIAL_THRESHOLD,
+} from "../../../src/core/search/coverage.ts";
+import { indexVault } from "../../../src/core/search/indexer.ts";
+import { search } from "../../../src/core/search/search.ts";
+import { createTempVault, makeConfig, writeMd } from "../../helpers/search-fixtures.ts";
+
+describe("buildCompletenessReport (pure)", () => {
+ const coverage = (covered: ReadonlyArray<string>, dfRare: number) =>
+ buildCoverageReport({
+ significantTerms: ["common", "rare"],
+ coveredTerms: new Set(covered),
+ documentCount: 100,
+ dfByTerm: new Map([
+ ["common", 90],
+ ["rare", dfRare],
+ ]),
+ });
+
+ test("all terms covered β†’ complete", () => {
+ const report = buildCompletenessReport(coverage(["common", "rare"], 1));
+ expect(report.verdict).toBe("complete");
+ expect(report.idfWeightedCoverage).toBe(1);
+ expect(report.uncoveredTerms).toEqual([]);
+ });
+
+ test("only the rare term covered β†’ still complete (IDF mass), only common β†’ sparse", () => {
+ expect(buildCompletenessReport(coverage(["rare"], 1)).verdict).toBe("complete");
+ expect(buildCompletenessReport(coverage(["common"], 1)).verdict).toBe("sparse");
+ });
+
+ test("thresholds are the documented constants", () => {
+ expect(COMPLETENESS_COMPLETE_THRESHOLD).toBe(0.8);
+ expect(COMPLETENESS_PARTIAL_THRESHOLD).toBe(0.4);
+ });
+
+ test("false-absence guard lists uncovered terms present in the corpus, not df=0 terms", () => {
+ const present = buildCompletenessReport(coverage(["common"], 5));
+ expect(present.uncoveredButPresentInCorpus).toEqual(["rare"]);
+ const absent = buildCompletenessReport(coverage(["common"], 0));
+ expect(absent.uncoveredButPresentInCorpus).toEqual([]);
+ expect(absent.uncoveredTerms).toEqual(["rare"]);
+ });
+});
+
+// ── search integration ───────────────────────────────────────────────────────
+
+let vault: string;
+let dbPath: string;
+let cleanup: () => void;
+
+beforeEach(() => {
+ ({ vault, dbPath, cleanup } = createTempVault("completeness"));
+});
+afterEach(() => cleanup());
+
+test("a fully covered query yields a complete verdict in the pack", async () => {
+ writeMd(vault, "doc.md", "# Doc\n\nalpha subsystem export pipeline");
+ const cfg = makeConfig({ vault, dbPath });
+ await indexVault(cfg);
+
+ const out = await search(cfg, { query: "alpha pipeline", limit: 5, evidencePack: true });
+ expect(out.evidencePack?.completeness?.verdict).toBe("complete");
+});
+
+test("zero results over terms the corpus contains trips the false-absence guard", async () => {
+ writeMd(vault, "alpha-note.md", "# Alpha\n\nthe alpha subsystem owns the export pipeline");
+ writeMd(vault, "zephyr-note.md", "# Zephyr\n\nthe zephyr daemon owns the import pipeline");
+ const cfg = makeConfig({ vault, dbPath });
+ await indexVault(cfg);
+
+ // AND semantics: no document holds both terms β†’ zero results, but
+ // BOTH terms exist in the corpus, so "nothing about alpha/zephyr"
+ // would be a false-absence claim.
+ const out = await search(cfg, { query: "alpha zephyr", limit: 5, evidencePack: true });
+ expect(out.results).toHaveLength(0);
+ const completeness = out.evidencePack?.completeness;
+ expect(completeness?.verdict).toBe("sparse");
+ expect(completeness?.uncoveredButPresentInCorpus?.toSorted()).toEqual(["alpha", "zephyr"]);
+});
diff --git a/tests/core/search/coverage.test.ts b/tests/core/search/coverage.test.ts
new file mode 100644
index 00000000..6e136a55
--- /dev/null
+++ b/tests/core/search/coverage.test.ts
@@ -0,0 +1,148 @@
+/**
+ * Verified multi-record recall (recall-trust-suite, Feature C).
+ *
+ * The coverage engine (`coverage.ts`) is the single source of truth for
+ * significant terms, per-term postings, corpus document frequency (IDF),
+ * and the rare-term classification. On top of it the evidence pack
+ * gains: per-token recall union (bounded extra records for uncovered
+ * terms), IDF-weighted support coverage, and a rare-term gate that
+ * populates the existing abstention field.
+ */
+
+import { test, expect, beforeEach, afterEach, describe } from "bun:test";
+
+import {
+ buildCoverageReport,
+ idfForTerm,
+ isRareTerm,
+ significantTerms,
+ termIncludedIn,
+} from "../../../src/core/search/coverage.ts";
+import { indexVault } from "../../../src/core/search/indexer.ts";
+import { search } from "../../../src/core/search/search.ts";
+import { createTempVault, makeConfig, writeMd } from "../../helpers/search-fixtures.ts";
+
+describe("coverage engine (pure)", () => {
+ test("significantTerms drops stopwords and short tokens", () => {
+ expect(significantTerms("what is the alpha zephyr")).toEqual(["alpha", "zephyr"]);
+ });
+
+ test("idf is monotonically decreasing in document frequency", () => {
+ const n = 100;
+ expect(idfForTerm(0, n)).toBeGreaterThan(idfForTerm(5, n));
+ expect(idfForTerm(5, n)).toBeGreaterThan(idfForTerm(100, n));
+ expect(idfForTerm(100, n)).toBeGreaterThan(0);
+ });
+
+ test("rare-term boundary: df within 2% of the corpus (min 1)", () => {
+ expect(isRareTerm(1, 100)).toBe(true);
+ expect(isRareTerm(2, 100)).toBe(true);
+ expect(isRareTerm(3, 100)).toBe(false);
+ // Tiny corpus: the floor keeps df=1 rare.
+ expect(isRareTerm(1, 10)).toBe(true);
+ expect(isRareTerm(2, 10)).toBe(false);
+ });
+
+ test("buildCoverageReport weights matched terms by IDF", () => {
+ const report = buildCoverageReport({
+ significantTerms: ["common", "rare"],
+ coveredTerms: new Set(["rare"]),
+ documentCount: 100,
+ dfByTerm: new Map([
+ ["common", 90],
+ ["rare", 1],
+ ]),
+ });
+ // Matching only the rare term yields coverage far above 0.5: the
+ // rare term carries far more IDF mass than the common one.
+ expect(report.idfWeightedCoverage).toBeGreaterThan(0.8);
+ expect(report.rareTerms).toEqual(["rare"]);
+ expect(report.uncoveredRareTerms).toEqual([]);
+ const common = report.terms.find((t) => t.term === "common")!;
+ expect(common.rare).toBe(false);
+ expect(common.covered).toBe(false);
+ });
+
+ test("an uncovered rare term is reported", () => {
+ const report = buildCoverageReport({
+ significantTerms: ["common", "rare"],
+ coveredTerms: new Set(["common"]),
+ documentCount: 100,
+ dfByTerm: new Map([
+ ["common", 90],
+ ["rare", 1],
+ ]),
+ });
+ expect(report.uncoveredRareTerms).toEqual(["rare"]);
+ expect(report.idfWeightedCoverage).toBeLessThan(0.2);
+ });
+
+ test("termIncludedIn folds case", () => {
+ expect(termIncludedIn("Alpha Beta", "alpha")).toBe(true);
+ expect(termIncludedIn("gamma", "alpha")).toBe(false);
+ });
+});
+
+// ── search integration ───────────────────────────────────────────────────────
+
+let vault: string;
+let dbPath: string;
+let cleanup: () => void;
+
+beforeEach(() => {
+ ({ vault, dbPath, cleanup } = createTempVault("coverage"));
+});
+afterEach(() => cleanup());
+
+test("per-token union gathers records for terms the ranked set left uncovered", async () => {
+ writeMd(vault, "alpha-note.md", "# Alpha\n\nthe alpha subsystem owns the export pipeline");
+ writeMd(vault, "zephyr-note.md", "# Zephyr\n\nthe zephyr daemon owns the import pipeline");
+ writeMd(vault, "filler.md", "# Filler\n\nunrelated prose about gardening");
+ const cfg = makeConfig({ vault, dbPath });
+ await indexVault(cfg);
+
+ // FTS joins tokens with implicit AND: no document contains both terms,
+ // so the primary result set is empty β€” exactly the evidence-spanning
+ // case the union exists for.
+ const out = await search(cfg, { query: "alpha zephyr", limit: 5, evidencePack: true });
+ expect(out.results).toHaveLength(0);
+ const pack = out.evidencePack!;
+ const unionTerms = (pack.unionRecords ?? []).map((r) => r.term).toSorted();
+ expect(unionTerms).toContain("alpha");
+ expect(unionTerms).toContain("zephyr");
+ const unionPaths = (pack.unionRecords ?? []).map((r) => r.path);
+ expect(unionPaths).toContain("alpha-note.md");
+ expect(unionPaths).toContain("zephyr-note.md");
+});
+
+test("the pack carries IDF-weighted coverage and the rare-term gate fills abstention", async () => {
+ writeMd(vault, "doc.md", "# Doc\n\nthe alpha subsystem export pipeline");
+ for (let i = 0; i < 5; i++) {
+ writeMd(vault, `common-${i}.md`, `# C${i}\n\nthe alpha subsystem note ${i}`);
+ }
+ const cfg = makeConfig({ vault, dbPath });
+ await indexVault(cfg);
+
+ const out = await search(cfg, { query: "alpha xylograph", limit: 5, evidencePack: true });
+ const pack = out.evidencePack!;
+ expect(typeof pack.idfWeightedCoverage).toBe("number");
+ expect(pack.idfWeightedCoverage!).toBeGreaterThanOrEqual(0);
+ expect(pack.idfWeightedCoverage!).toBeLessThanOrEqual(1);
+ // "xylograph" appears nowhere: rare (df=0) and uncovered β†’ the gate
+ // abstains explicitly.
+ expect(pack.uncoveredRareTerms).toContain("xylograph");
+ expect(pack.abstention).toContain("xylograph");
+});
+
+test("legacy evidence-pack fields stay byte-identical for callers that ignore the new ones", async () => {
+ writeMd(vault, "doc.md", "# Doc\n\nalpha beta gamma");
+ const cfg = makeConfig({ vault, dbPath });
+ await indexVault(cfg);
+
+ const out = await search(cfg, { query: "alpha gamma", limit: 5, evidencePack: true });
+ const pack = out.evidencePack!;
+ expect(pack.significantTerms).toEqual(["alpha", "gamma"]);
+ expect(pack.matchedTerms).toEqual(["alpha", "gamma"]);
+ expect(pack.missingTerms).toEqual([]);
+ expect(pack.supportCoverage).toBe(1);
+});
diff --git a/tests/core/search/feedback.test.ts b/tests/core/search/feedback.test.ts
new file mode 100644
index 00000000..b143fb0a
--- /dev/null
+++ b/tests/core/search/feedback.test.ts
@@ -0,0 +1,244 @@
+/**
+ * Retrieval feedback loop (recall-trust-suite, Feature B).
+ *
+ * Explicit per-result recall feedback lands as one JSON file per event
+ * under `Brain/search/feedback/` (the conflict-free inbox pattern), and
+ * a deterministic bounded fold derives per-layer learned multipliers
+ * into `Brain/search/learned-weights.json`. Search applies them only
+ * when the config opt-in is on, tags affected results with a
+ * `learned_weights:` reason, and folds the weights state into the
+ * query-cache key.
+ */
+
+import { test, expect, beforeEach, afterEach, describe } from "bun:test";
+import { existsSync, readdirSync } from "node:fs";
+
+import {
+ computeLearnedWeights,
+ contributionsFromResult,
+ feedbackDir,
+ learnedWeightsPath,
+ learnedWeightsFingerprint,
+ loadFeedbackEvents,
+ readLearnedWeights,
+ recordRecallFeedback,
+ resetLearnedWeights,
+ LEARNED_WEIGHT_MIN,
+ LEARNED_WEIGHT_MAX,
+ type RecallFeedbackEvent,
+} from "../../../src/core/search/feedback.ts";
+import { indexVault } from "../../../src/core/search/indexer.ts";
+import { search } from "../../../src/core/search/search.ts";
+import type { BrainSearchResult } from "../../../src/core/search/types.ts";
+import { createTempVault, makeConfig, writeMd } from "../../helpers/search-fixtures.ts";
+
+let vault: string;
+let dbPath: string;
+let cleanup: () => void;
+
+beforeEach(() => {
+ ({ vault, dbPath, cleanup } = createTempVault("feedback"));
+});
+afterEach(() => cleanup());
+
+function event(over: Partial<RecallFeedbackEvent>): RecallFeedbackEvent {
+ return {
+ ts: 1_700_000_000_000,
+ queryHash: "abcd1234",
+ resultPath: "note.md",
+ verdict: "up",
+ contributions: { keyword: 0.8, semantic: 0, entity: 0, recency: 0.05 },
+ ...over,
+ };
+}
+
+describe("feedback event store", () => {
+ test("recordRecallFeedback writes one JSON file per event and round-trips", () => {
+ const a = event({ ts: 1_700_000_000_000 });
+ const b = event({ ts: 1_700_000_000_001, verdict: "down" });
+ recordRecallFeedback(vault, a);
+ recordRecallFeedback(vault, b);
+ const files = readdirSync(feedbackDir(vault));
+ expect(files).toHaveLength(2);
+ expect(files.every((f) => f.endsWith(".json"))).toBe(true);
+ const events = loadFeedbackEvents(vault);
+ expect(events).toHaveLength(2);
+ expect(events[0]!.ts).toBe(a.ts);
+ expect(events[1]!.verdict).toBe("down");
+ });
+
+ test("recording the same event twice is idempotent (deterministic filename)", () => {
+ const a = event({});
+ recordRecallFeedback(vault, a);
+ recordRecallFeedback(vault, a);
+ expect(readdirSync(feedbackDir(vault))).toHaveLength(1);
+ });
+
+ test("loadFeedbackEvents on a vault without feedback returns empty", () => {
+ expect(loadFeedbackEvents(vault)).toEqual([]);
+ });
+});
+
+describe("learned-weight fold", () => {
+ test("no events β†’ neutral multipliers", () => {
+ const w = computeLearnedWeights([]);
+ expect(w.keywordMul).toBe(1);
+ expect(w.semanticMul).toBe(1);
+ expect(w.entityMul).toBe(1);
+ expect(w.recencyMul).toBe(1);
+ expect(w.events).toBe(0);
+ });
+
+ test("up-votes on keyword-driven results raise keywordMul; down-votes lower it", () => {
+ const ups = [
+ event({ ts: 1, contributions: { keyword: 1, semantic: 0, entity: 0, recency: 0 } }),
+ event({ ts: 2, contributions: { keyword: 1, semantic: 0, entity: 0, recency: 0 } }),
+ ];
+ const up = computeLearnedWeights(ups);
+ expect(up.keywordMul).toBeGreaterThan(1);
+ expect(up.semanticMul).toBe(1);
+
+ const downs = ups.map((e, i) => ({ ...e, ts: 10 + i, verdict: "down" as const }));
+ const down = computeLearnedWeights(downs);
+ expect(down.keywordMul).toBeLessThan(1);
+ });
+
+ test("multipliers never escape the documented bounds", () => {
+ const extreme = Array.from({ length: 50 }, (_, i) =>
+ event({
+ ts: i,
+ verdict: "down",
+ contributions: { keyword: 1, semantic: 1, entity: 1, recency: 1 },
+ }),
+ );
+ const w = computeLearnedWeights(extreme);
+ for (const mul of [w.keywordMul, w.semanticMul, w.entityMul, w.recencyMul]) {
+ expect(mul).toBeGreaterThanOrEqual(LEARNED_WEIGHT_MIN);
+ expect(mul).toBeLessThanOrEqual(LEARNED_WEIGHT_MAX);
+ }
+ });
+
+ test("the fold is deterministic and order-insensitive for the same event set", () => {
+ const events = [
+ event({ ts: 1, contributions: { keyword: 0.9, semantic: 0.1, entity: 0, recency: 0 } }),
+ event({
+ ts: 2,
+ verdict: "down",
+ contributions: { keyword: 0.1, semantic: 0.8, entity: 0, recency: 0 },
+ }),
+ event({ ts: 3, contributions: { keyword: 0, semantic: 0, entity: 0.5, recency: 0.5 } }),
+ ];
+ const a = computeLearnedWeights(events);
+ const b = computeLearnedWeights(events.toReversed());
+ expect(a).toEqual(b);
+ });
+
+ test("contributionsFromResult reads the scoring layers off a search result", () => {
+ const result = {
+ documentId: 1,
+ chunkId: 10,
+ path: "x.md",
+ title: null,
+ content: "",
+ startLine: 1,
+ endLine: 1,
+ score: 0.7,
+ keywordScore: 0.6,
+ semanticScore: 0.2,
+ linkBoost: 0,
+ recencyBoost: 0.05,
+ searchType: "hybrid",
+ reasons: ["fts5_bm25: 0.600", "semantic_cos: 0.200", "entity_match: 0.020"],
+ } as unknown as BrainSearchResult;
+ const c = contributionsFromResult(result);
+ expect(c.keyword).toBeCloseTo(0.6, 5);
+ expect(c.semantic).toBeCloseTo(0.2, 5);
+ expect(c.entity).toBeCloseTo(0.02, 5);
+ expect(c.recency).toBeCloseTo(0.05, 5);
+ });
+});
+
+describe("derived weights file", () => {
+ test("record + recompute persists learned weights; reset removes them but keeps events", () => {
+ recordRecallFeedback(vault, event({}));
+ const w = computeLearnedWeights(loadFeedbackEvents(vault));
+ expect(existsSync(learnedWeightsPath(vault))).toBe(true); // record() recomputes
+ expect(readLearnedWeights(vault)?.events).toBe(w.events);
+
+ resetLearnedWeights(vault);
+ expect(existsSync(learnedWeightsPath(vault))).toBe(false);
+ expect(loadFeedbackEvents(vault)).toHaveLength(1);
+ });
+
+ test("fingerprint changes when weights change and is stable otherwise", () => {
+ const before = learnedWeightsFingerprint(vault);
+ expect(learnedWeightsFingerprint(vault)).toBe(before);
+ recordRecallFeedback(vault, event({}));
+ expect(learnedWeightsFingerprint(vault)).not.toBe(before);
+ });
+});
+
+describe("search integration", () => {
+ test("learned weights shift scores only when the config opt-in is on", async () => {
+ writeMd(vault, "doc.md", "# Doc\n\nthe migration ledger covers warehouse sync");
+ // Two keyword-down events: learned keywordMul < 1.
+ recordRecallFeedback(
+ vault,
+ event({
+ ts: 1,
+ verdict: "down",
+ contributions: { keyword: 1, semantic: 0, entity: 0, recency: 0 },
+ }),
+ );
+ recordRecallFeedback(
+ vault,
+ event({
+ ts: 2,
+ verdict: "down",
+ contributions: { keyword: 1, semantic: 0, entity: 0, recency: 0 },
+ }),
+ );
+
+ const off = makeConfig({ vault, dbPath });
+ const on = makeConfig({ vault, dbPath, learnedWeightsEnabled: true });
+ await indexVault(off);
+
+ const plain = await search(off, { query: "migration ledger", limit: 3 });
+ const learned = await search(on, { query: "migration ledger", limit: 3 });
+ expect(plain.results).toHaveLength(1);
+ expect(learned.results).toHaveLength(1);
+ expect(learned.results[0]!.score).toBeLessThan(plain.results[0]!.score);
+ expect(learned.results[0]!.reasons.some((r) => r.startsWith("learned_weights:"))).toBe(true);
+ expect(plain.results[0]!.reasons.some((r) => r.startsWith("learned_weights:"))).toBe(false);
+ });
+
+ test("neutral learned weights leave results untagged", async () => {
+ writeMd(vault, "doc.md", "# Doc\n\nplain note about ledger sync");
+ const on = makeConfig({ vault, dbPath, learnedWeightsEnabled: true });
+ await indexVault(on);
+ const out = await search(on, { query: "ledger sync", limit: 3 });
+ expect(out.results[0]!.reasons.some((r) => r.startsWith("learned_weights:"))).toBe(false);
+ });
+});
+
+describe("malformed event hardening", () => {
+ test("an event with non-numeric contributions is skipped by the fold", () => {
+ recordRecallFeedback(vault, event({ ts: 1 }));
+ // Hand-write a malformed event file alongside the valid one.
+ const dir = feedbackDir(vault);
+ const malformed = JSON.stringify({
+ ts: 2,
+ queryHash: "ffff0000",
+ resultPath: "x.md",
+ verdict: "down",
+ contributions: { keyword: "high", semantic: null },
+ });
+ require("node:fs").writeFileSync(`${dir}/2-malformed.json`, malformed);
+ const events = loadFeedbackEvents(vault);
+ expect(events).toHaveLength(1); // the malformed file never enters the fold
+ const w = computeLearnedWeights(events);
+ for (const mul of [w.keywordMul, w.semanticMul, w.entityMul, w.recencyMul]) {
+ expect(Number.isFinite(mul)).toBe(true);
+ }
+ });
+});
diff --git a/tests/core/search/relation-polarity.test.ts b/tests/core/search/relation-polarity.test.ts
new file mode 100644
index 00000000..69587d89
--- /dev/null
+++ b/tests/core/search/relation-polarity.test.ts
@@ -0,0 +1,383 @@
+/**
+ * Relation-aware recall (recall-trust-suite, Feature A).
+ *
+ * Typed relation edges get recall polarity: `superseded_by` demotes the
+ * matched predecessor and pulls in / boosts its successor, `contradicts`
+ * surfaces with a warning-style reason and no score change, and the
+ * positive relations (`related` / `extends` / `depends_on` / `refines`)
+ * grant a small bounded boost between co-retrieved candidates. The pure
+ * pass lives in `relation-polarity.ts`; `search.ts` wires it over the
+ * assembled pool before the final slice.
+ */
+
+import { test, expect, beforeEach, afterEach, describe } from "bun:test";
+
+import {
+ applyRelationPolarity,
+ RELATION_BOOST_CAP,
+ RELATION_BOOST_PER_EDGE,
+ SUPERSEDED_DEMOTION,
+ SUCCESSOR_CARRY,
+ type RelationEdge,
+} from "../../../src/core/search/relation-polarity.ts";
+import { indexVault } from "../../../src/core/search/indexer.ts";
+import { search } from "../../../src/core/search/search.ts";
+import type { BrainSearchResult } from "../../../src/core/search/types.ts";
+import { createTempVault, makeConfig, writeMd } from "../../helpers/search-fixtures.ts";
+
+// ── unit: pure polarity pass ─────────────────────────────────────────────────
+
+function result(over: Partial<BrainSearchResult> & { documentId: number }): BrainSearchResult {
+ return Object.freeze({
+ chunkId: over.documentId * 10,
+ path: `doc-${over.documentId}.md`,
+ title: null,
+ content: "body",
+ startLine: 1,
+ endLine: 1,
+ score: 0.5,
+ keywordScore: 0.5,
+ semanticScore: 0,
+ linkBoost: 0,
+ recencyBoost: 0,
+ searchType: "keyword" as const,
+ reasons: Object.freeze(["fts5_bm25: 0.500"]),
+ ...over,
+ });
+}
+
+function edge(over: Partial<RelationEdge> & { sourceDocumentId: number }): RelationEdge {
+ return {
+ relation: "related",
+ target: "x",
+ targetDocumentId: null,
+ ...over,
+ };
+}
+
+describe("applyRelationPolarity (pure)", () => {
+ test("no edges β†’ identical results back", () => {
+ const pool = [result({ documentId: 1, score: 0.9 }), result({ documentId: 2, score: 0.4 })];
+ const out = applyRelationPolarity({ ranked: pool, edges: [], successorDoc: () => null }, {});
+ expect(out).toEqual(pool);
+ });
+
+ test("superseded_by demotes the predecessor and boosts a co-retrieved successor", () => {
+ const pool = [
+ result({ documentId: 1, score: 0.9, path: "old.md" }),
+ result({ documentId: 2, score: 0.3, path: "new.md" }),
+ ];
+ const edges = [
+ edge({
+ sourceDocumentId: 1,
+ relation: "superseded_by",
+ target: "new",
+ targetDocumentId: 2,
+ }),
+ ];
+ const out = applyRelationPolarity({ ranked: pool, edges, successorDoc: () => null }, {});
+ const oldHit = out.find((r) => r.path === "old.md")!;
+ const newHit = out.find((r) => r.path === "new.md")!;
+ expect(oldHit.score).toBeCloseTo(0.9 * SUPERSEDED_DEMOTION, 5);
+ expect(oldHit.reasons).toContain("superseded_by: new");
+ expect(newHit.score).toBeCloseTo(0.9 * SUCCESSOR_CARRY, 5);
+ expect(newHit.reasons).toContain("supersedes_matched: old.md");
+ // Successor outranks the demoted predecessor.
+ expect(out.findIndex((r) => r.path === "new.md")).toBeLessThan(
+ out.findIndex((r) => r.path === "old.md"),
+ );
+ });
+
+ test("superseded_by pulls in an absent successor via successorDoc", () => {
+ const pool = [result({ documentId: 1, score: 0.8, path: "old.md" })];
+ const edges = [
+ edge({
+ sourceDocumentId: 1,
+ relation: "superseded_by",
+ target: "new",
+ targetDocumentId: 7,
+ }),
+ ];
+ const out = applyRelationPolarity(
+ {
+ ranked: pool,
+ edges,
+ successorDoc: (docId) =>
+ docId === 7
+ ? {
+ documentId: 7,
+ chunkId: 70,
+ path: "new.md",
+ title: "New",
+ content: "successor body",
+ startLine: 1,
+ endLine: 1,
+ }
+ : null,
+ },
+ {},
+ );
+ const pulled = out.find((r) => r.path === "new.md");
+ expect(pulled).toBeDefined();
+ expect(pulled!.searchType).toBe("link");
+ expect(pulled!.score).toBeCloseTo(0.8 * SUCCESSOR_CARRY, 5);
+ expect(pulled!.reasons).toContain("supersedes_matched: old.md");
+ });
+
+ test("includeSuperseded keeps the predecessor undemoted and skips pull-in", () => {
+ const pool = [result({ documentId: 1, score: 0.9, path: "old.md" })];
+ const edges = [
+ edge({
+ sourceDocumentId: 1,
+ relation: "superseded_by",
+ target: "new",
+ targetDocumentId: 7,
+ }),
+ ];
+ const out = applyRelationPolarity(
+ { ranked: pool, edges, successorDoc: () => null },
+ { includeSuperseded: true },
+ );
+ expect(out).toHaveLength(1);
+ expect(out[0]!.score).toBeCloseTo(0.9, 5);
+ // The informational reason still lands.
+ expect(out[0]!.reasons).toContain("superseded_by: new");
+ });
+
+ test("an unresolved superseded_by target is inert: reason only, no demotion", () => {
+ const pool = [result({ documentId: 1, score: 0.9, path: "old.md" })];
+ const edges = [
+ edge({
+ sourceDocumentId: 1,
+ relation: "superseded_by",
+ target: "ghost",
+ targetDocumentId: null,
+ }),
+ ];
+ const out = applyRelationPolarity({ ranked: pool, edges, successorDoc: () => null }, {});
+ expect(out[0]!.score).toBeCloseTo(0.9, 5);
+ expect(out[0]!.reasons).toContain("superseded_by: ghost");
+ });
+
+ test("contradicts adds warning reasons on both endpoints and never changes scores", () => {
+ const pool = [
+ result({ documentId: 1, score: 0.9, path: "claim.md" }),
+ result({ documentId: 2, score: 0.4, path: "counter.md" }),
+ ];
+ const edges = [
+ edge({
+ sourceDocumentId: 1,
+ relation: "contradicts",
+ target: "counter",
+ targetDocumentId: 2,
+ }),
+ ];
+ const out = applyRelationPolarity({ ranked: pool, edges, successorDoc: () => null }, {});
+ const claim = out.find((r) => r.path === "claim.md")!;
+ const counter = out.find((r) => r.path === "counter.md")!;
+ expect(claim.score).toBeCloseTo(0.9, 5);
+ expect(counter.score).toBeCloseTo(0.4, 5);
+ expect(claim.reasons).toContain("contradicts: counter");
+ expect(counter.reasons).toContain("contradicted_by: claim.md");
+ });
+
+ test("positive relations grant a bounded directional boost to a co-retrieved target", () => {
+ const pool = [
+ result({ documentId: 1, score: 0.9, path: "feature.md" }),
+ result({ documentId: 2, score: 0.4, path: "base.md" }),
+ ];
+ const edges = [
+ edge({ sourceDocumentId: 1, relation: "extends", target: "base", targetDocumentId: 2 }),
+ edge({ sourceDocumentId: 1, relation: "depends_on", target: "base", targetDocumentId: 2 }),
+ edge({ sourceDocumentId: 1, relation: "refines", target: "base", targetDocumentId: 2 }),
+ ];
+ const out = applyRelationPolarity({ ranked: pool, edges, successorDoc: () => null }, {});
+ const base = out.find((r) => r.path === "base.md")!;
+ // Three edges at 0.02 each would be 0.06; the cap holds it at RELATION_BOOST_CAP.
+ expect(base.score).toBeCloseTo(0.4 + RELATION_BOOST_CAP, 5);
+ expect(base.reasons.some((r) => r.startsWith("relation_boost: extends"))).toBe(true);
+ });
+
+ test("self-edges are ignored", () => {
+ const pool = [result({ documentId: 1, score: 0.9, path: "self.md" })];
+ const edges = [
+ edge({ sourceDocumentId: 1, relation: "superseded_by", target: "self", targetDocumentId: 1 }),
+ ];
+ const out = applyRelationPolarity({ ranked: pool, edges, successorDoc: () => null }, {});
+ expect(out[0]!.score).toBeCloseTo(0.9, 5);
+ });
+});
+
+// ── integration: search() wiring ─────────────────────────────────────────────
+
+/** Clock-stable projection of a result (drops the recency layer's drift). */
+function stableProjection(r: BrainSearchResult) {
+ return {
+ path: r.path,
+ searchType: r.searchType,
+ keywordScore: r.keywordScore,
+ reasons: r.reasons.filter((reason) => !reason.startsWith("recency:")),
+ };
+}
+
+let vault: string;
+let dbPath: string;
+let cleanup: () => void;
+
+beforeEach(() => {
+ ({ vault, dbPath, cleanup } = createTempVault("relation-polarity"));
+});
+afterEach(() => cleanup());
+
+const OLD_PAGE = [
+ "---",
+ "title: Old deploy decision",
+ 'superseded_by: "[[new-deploy]]"',
+ "---",
+ "# Old deploy decision",
+ "",
+ "We deploy with the blue-green rollout strategy on fridays.",
+].join("\n");
+
+const NEW_PAGE = [
+ "---",
+ "title: New deploy decision",
+ "---",
+ "# New deploy decision",
+ "",
+ "Deployment notes for the canary path.",
+].join("\n");
+
+test("search surfaces the successor above the demoted predecessor", async () => {
+ writeMd(vault, "old.md", OLD_PAGE);
+ writeMd(vault, "new-deploy.md", NEW_PAGE);
+ const cfg = makeConfig({ vault, dbPath });
+
+ await indexVault(cfg);
+ const out = await search(cfg, { query: "blue-green rollout strategy", limit: 5 });
+ const oldIdx = out.results.findIndex((r) => r.path === "old.md");
+ const newIdx = out.results.findIndex((r) => r.path === "new-deploy.md");
+ expect(oldIdx).toBeGreaterThanOrEqual(0);
+ expect(newIdx).toBeGreaterThanOrEqual(0);
+ expect(newIdx).toBeLessThan(oldIdx);
+ expect(out.results[oldIdx]!.reasons).toContain("superseded_by: new-deploy");
+ expect(out.results[newIdx]!.reasons).toContain("supersedes_matched: old.md");
+});
+
+test("includeSuperseded restores the undemoted order", async () => {
+ writeMd(vault, "old.md", OLD_PAGE);
+ writeMd(vault, "new-deploy.md", NEW_PAGE);
+ const cfg = makeConfig({ vault, dbPath });
+
+ await indexVault(cfg);
+ const out = await search(cfg, {
+ query: "blue-green rollout strategy",
+ limit: 5,
+ includeSuperseded: true,
+ });
+ const oldIdx = out.results.findIndex((r) => r.path === "old.md");
+ const newIdx = out.results.findIndex((r) => r.path === "new-deploy.md");
+ expect(oldIdx).toBeGreaterThanOrEqual(0);
+ // The predecessor stays on top: it is the direct text match.
+ if (newIdx >= 0) expect(oldIdx).toBeLessThan(newIdx);
+});
+
+test("contradicts surfaces a warning reason without reordering", async () => {
+ writeMd(
+ vault,
+ "claim.md",
+ [
+ "---",
+ "title: Claim",
+ 'contradicts: "[[counter]]"',
+ "---",
+ "# Claim",
+ "",
+ "The retention window for kanban telemetry is thirty days.",
+ ].join("\n"),
+ );
+ writeMd(
+ vault,
+ "counter.md",
+ "# Counter\n\nThe retention window for kanban telemetry is ninety days.",
+ );
+ const cfg = makeConfig({ vault, dbPath });
+
+ await indexVault(cfg);
+ const out = await search(cfg, { query: "retention window kanban telemetry", limit: 5 });
+ const claim = out.results.find((r) => r.path === "claim.md");
+ const counter = out.results.find((r) => r.path === "counter.md");
+ expect(claim).toBeDefined();
+ expect(counter).toBeDefined();
+ expect(claim!.reasons).toContain("contradicts: counter");
+ expect(counter!.reasons).toContain("contradicted_by: claim.md");
+});
+
+test("a vault without typed relations ranks bit-identically with the pass on or off", async () => {
+ writeMd(vault, "x.md", "# X\n\nplain note about orchard pruning in spring");
+ writeMd(vault, "y.md", "# Y\n\nanother note about orchard irrigation [[x]]");
+ const on = makeConfig({ vault, dbPath });
+ const off = makeConfig({ vault, dbPath, relationPolarityEnabled: false });
+
+ await indexVault(on);
+ const a = await search(on, { query: "orchard pruning", limit: 5 });
+ const b = await search(off, { query: "orchard pruning", limit: 5 });
+ // Project away the recency layer's clock drift between the two calls;
+ // order, paths, types, and reasons must match exactly.
+ expect(a.results.map(stableProjection)).toEqual(b.results.map(stableProjection));
+});
+
+test("disabling relation polarity in config skips demotion entirely", async () => {
+ writeMd(vault, "old.md", OLD_PAGE);
+ writeMd(vault, "new-deploy.md", NEW_PAGE);
+ const cfg = makeConfig({ vault, dbPath, relationPolarityEnabled: false });
+
+ await indexVault(cfg);
+ const out = await search(cfg, { query: "blue-green rollout strategy", limit: 5 });
+ const oldHit = out.results.find((r) => r.path === "old.md")!;
+ expect(oldHit.reasons.some((r) => r.startsWith("superseded_by:"))).toBe(false);
+});
+
+function overlapSuccessor(docId: number) {
+ return docId === 9
+ ? {
+ documentId: 9,
+ chunkId: 90,
+ path: "next.md",
+ title: "Next",
+ content: "successor",
+ startLine: 1,
+ endLine: 1,
+ }
+ : null;
+}
+
+test("a node that is both demoted predecessor and positive target composes order-independently", () => {
+ // doc 1 matches, declares superseded_by -> doc 9 (pulled in), and is
+ // ALSO the target of a positive relation from doc 2. The demotion,
+ // carry, and boost must compose to the same score regardless of the
+ // order the edges arrive in.
+ const pool = [
+ result({ documentId: 1, score: 0.9, path: "both.md" }),
+ result({ documentId: 2, score: 0.5, path: "extender.md" }),
+ ];
+ const edges = [
+ edge({ sourceDocumentId: 1, relation: "superseded_by", target: "next", targetDocumentId: 9 }),
+ edge({ sourceDocumentId: 2, relation: "extends", target: "both", targetDocumentId: 1 }),
+ ];
+ const forward = applyRelationPolarity(
+ { ranked: pool, edges, successorDoc: overlapSuccessor },
+ {},
+ );
+ const reversed = applyRelationPolarity(
+ { ranked: pool, edges: edges.toReversed(), successorDoc: overlapSuccessor },
+ {},
+ );
+ expect(forward.map((r) => ({ path: r.path, score: r.score }))).toEqual(
+ reversed.map((r) => ({ path: r.path, score: r.score })),
+ );
+ // Composition contract: demotion applies to the original score, the
+ // positive boost adds on top of the demoted base.
+ const both = forward.find((r) => r.path === "both.md")!;
+ expect(both.score).toBeCloseTo(0.9 * SUPERSEDED_DEMOTION + RELATION_BOOST_PER_EDGE, 5);
+});
diff --git a/tests/core/search/store.test.ts b/tests/core/search/store.test.ts
index f944ee1d..9d8a22ca 100644
--- a/tests/core/search/store.test.ts
+++ b/tests/core/search/store.test.ts
@@ -48,6 +48,8 @@ function makeConfig(overrides?: Partial<ResolvedSearchConfig>): ResolvedSearchCo
synonymMaxTerms: 3,
cacheEnabled: false,
cacheTtlSeconds: 300,
+ relationPolarityEnabled: true,
+ learnedWeightsEnabled: false,
}),
...overrides,
});
diff --git a/tests/core/search/store.vec.test.ts b/tests/core/search/store.vec.test.ts
index 549964cb..1ca2825b 100644
--- a/tests/core/search/store.vec.test.ts
+++ b/tests/core/search/store.vec.test.ts
@@ -51,6 +51,8 @@ function semanticConfig(
synonymMaxTerms: 3,
cacheEnabled: false,
cacheTtlSeconds: 300,
+ relationPolarityEnabled: true,
+ learnedWeightsEnabled: false,
}),
...overrides,
});
diff --git a/tests/core/search/time-range.test.ts b/tests/core/search/time-range.test.ts
new file mode 100644
index 00000000..8cc2293f
--- /dev/null
+++ b/tests/core/search/time-range.test.ts
@@ -0,0 +1,152 @@
+/**
+ * Time-aware recall (recall-trust-suite, Feature D).
+ *
+ * `since` / `until` accept ISO dates, relative phrases (`yesterday`,
+ * `last week`), and duration shorthand (`24h`, `7d`, `2w`). The parser
+ * (`time-range.ts`) is pure against an injected clock; search filters
+ * hydrated candidates by document mtime before ranking and bypasses the
+ * query cache while a range is active (a relative range resolves to a
+ * different absolute window every call).
+ */
+
+import { test, expect, beforeEach, afterEach, describe } from "bun:test";
+import { utimesSync } from "node:fs";
+
+import { parseTimePoint, resolveTimeRange } from "../../../src/core/search/time-range.ts";
+import { indexVault } from "../../../src/core/search/indexer.ts";
+import { search } from "../../../src/core/search/search.ts";
+import { Store } from "../../../src/core/search/store.ts";
+import { SearchError } from "../../../src/core/search/types.ts";
+import { createTempVault, makeConfig, writeMd } from "../../helpers/search-fixtures.ts";
+
+// A fixed clock: 2026-06-02T12:00:00.000Z
+const NOW = Date.UTC(2026, 5, 2, 12, 0, 0, 0);
+const DAY = 24 * 60 * 60 * 1000;
+
+describe("parseTimePoint", () => {
+ test("ISO datetime passes through", () => {
+ expect(parseTimePoint("2026-05-01T10:30:00Z", NOW, "since")).toBe(
+ Date.UTC(2026, 4, 1, 10, 30, 0, 0),
+ );
+ });
+
+ test("a bare ISO date is day-start for since and day-end for until", () => {
+ expect(parseTimePoint("2026-05-01", NOW, "since")).toBe(Date.UTC(2026, 4, 1));
+ expect(parseTimePoint("2026-05-01", NOW, "until")).toBe(Date.UTC(2026, 4, 2) - 1);
+ });
+
+ test("today and yesterday resolve against the injected clock", () => {
+ expect(parseTimePoint("today", NOW, "since")).toBe(Date.UTC(2026, 5, 2));
+ expect(parseTimePoint("yesterday", NOW, "since")).toBe(Date.UTC(2026, 5, 1));
+ expect(parseTimePoint("yesterday", NOW, "until")).toBe(Date.UTC(2026, 5, 2) - 1);
+ });
+
+ test("last week / last month are rolling windows", () => {
+ expect(parseTimePoint("last week", NOW, "since")).toBe(NOW - 7 * DAY);
+ expect(parseTimePoint("last month", NOW, "since")).toBe(NOW - 30 * DAY);
+ });
+
+ test("duration shorthand: hours, days, weeks", () => {
+ expect(parseTimePoint("24h", NOW, "since")).toBe(NOW - 24 * 60 * 60 * 1000);
+ expect(parseTimePoint("7d", NOW, "since")).toBe(NOW - 7 * DAY);
+ expect(parseTimePoint("2w", NOW, "since")).toBe(NOW - 14 * DAY);
+ });
+
+ test("unparseable input throws INVALID_INPUT", () => {
+ for (const bad of ["soon", "5 parsecs", "2026-13-45", ""]) {
+ expect(() => parseTimePoint(bad, NOW, "since")).toThrow(SearchError);
+ }
+ });
+});
+
+describe("resolveTimeRange", () => {
+ test("absent fields resolve to an open range", () => {
+ expect(resolveTimeRange({}, NOW)).toEqual({ sinceMs: null, untilMs: null });
+ });
+
+ test("since after until is rejected", () => {
+ expect(() => resolveTimeRange({ since: "today", until: "2026-01-01" }, NOW)).toThrow(
+ SearchError,
+ );
+ });
+});
+
+// ── search integration ───────────────────────────────────────────────────────
+
+let vault: string;
+let dbPath: string;
+let cleanup: () => void;
+
+beforeEach(() => {
+ ({ vault, dbPath, cleanup } = createTempVault("time-range"));
+});
+afterEach(() => cleanup());
+
+async function seedOldAndFresh(): Promise<void> {
+ const oldAbs = writeMd(vault, "old.md", "# Old\n\nharvest report for the orchard ledger");
+ writeMd(vault, "fresh.md", "# Fresh\n\nharvest notes for the orchard ledger");
+ // The old document's mtime is 10 days in the past.
+ const tenDaysAgo = new Date(Date.now() - 10 * DAY);
+ utimesSync(oldAbs, tenDaysAgo, tenDaysAgo);
+}
+
+test("since excludes documents older than the window", async () => {
+ await seedOldAndFresh();
+ const cfg = makeConfig({ vault, dbPath });
+ await indexVault(cfg);
+
+ const all = await search(cfg, { query: "orchard ledger harvest", limit: 5 });
+ expect(all.results.map((r) => r.path).toSorted()).toEqual(["fresh.md", "old.md"]);
+
+ const recent = await search(cfg, { query: "orchard ledger harvest", limit: 5, since: "7d" });
+ expect(recent.results.map((r) => r.path)).toEqual(["fresh.md"]);
+});
+
+test("until excludes documents newer than the window", async () => {
+ await seedOldAndFresh();
+ const cfg = makeConfig({ vault, dbPath });
+ await indexVault(cfg);
+
+ const old = await search(cfg, { query: "orchard ledger harvest", limit: 5, until: "7d" });
+ expect(old.results.map((r) => r.path)).toEqual(["old.md"]);
+});
+
+test("an invalid since raises INVALID_INPUT through search", async () => {
+ writeMd(vault, "a.md", "# A\n\nbody");
+ const cfg = makeConfig({ vault, dbPath });
+ await indexVault(cfg);
+ await expect(search(cfg, { query: "body", since: "whenever" })).rejects.toThrow(SearchError);
+});
+
+test("time-filtered queries bypass the query cache", async () => {
+ await seedOldAndFresh();
+ const cfg = makeConfig({ vault, dbPath, cacheEnabled: true });
+ await indexVault(cfg);
+
+ await search(cfg, { query: "orchard ledger harvest", limit: 5 });
+ await search(cfg, { query: "orchard ledger harvest", limit: 5, since: "7d" });
+
+ const store = await Store.open(cfg, { mode: "read", loadVec: false });
+ try {
+ // eslint-disable-next-line @typescript-eslint/no-explicit-any
+ const rows = (store as any).db.query("SELECT COUNT(*) AS n FROM query_cache").get() as {
+ n: number;
+ };
+ expect(rows.n).toBe(1); // only the unfiltered query was cached
+ } finally {
+ await store.close();
+ }
+});
+
+test("an offset-less ISO datetime resolves as UTC, identical to its Z-suffixed form", () => {
+ expect(parseTimePoint("2026-05-01T10:30:00", NOW, "since")).toBe(
+ parseTimePoint("2026-05-01T10:30:00Z", NOW, "since"),
+ );
+ expect(parseTimePoint("2026-05-01T10:30:00", NOW, "since")).toBe(
+ Date.UTC(2026, 4, 1, 10, 30, 0, 0),
+ );
+ // An explicit offset is honoured.
+ expect(parseTimePoint("2026-05-01T12:30:00+02:00", NOW, "since")).toBe(
+ Date.UTC(2026, 4, 1, 10, 30, 0, 0),
+ );
+});
diff --git a/tests/helpers/search-fixtures.ts b/tests/helpers/search-fixtures.ts
index 85f7cb11..07624870 100644
--- a/tests/helpers/search-fixtures.ts
+++ b/tests/helpers/search-fixtures.ts
@@ -61,6 +61,10 @@ export function makeConfig(opts: {
synonymEnabled?: boolean;
/** Persistent query cache; defaults to false (opt-in). */
cacheEnabled?: boolean;
+ /** Relation-aware recall polarity; defaults to true. */
+ relationPolarityEnabled?: boolean;
+ /** Learned recall weights from feedback; defaults to false (opt-in). */
+ learnedWeightsEnabled?: boolean;
}): ResolvedSearchConfig {
const baseSemantic: ResolvedEmbeddingConfig = Object.freeze({
enabled: false,
@@ -103,6 +107,8 @@ export function makeConfig(opts: {
synonymMaxTerms: 3,
cacheEnabled: opts.cacheEnabled ?? false,
cacheTtlSeconds: 300,
+ relationPolarityEnabled: opts.relationPolarityEnabled ?? true,
+ learnedWeightsEnabled: opts.learnedWeightsEnabled ?? false,
}),
});
}
diff --git a/tests/mcp/mcp.test.ts b/tests/mcp/mcp.test.ts
index ea62b415..7c7eac7b 100644
--- a/tests/mcp/mcp.test.ts
+++ b/tests/mcp/mcp.test.ts
@@ -244,6 +244,7 @@ describe("tool listing", () => {
"payment_request_status",
"payment_request_consume",
// Search (added in v0.10.0; recall gate added in v0.27.0).
+ "brain_recall_feedback",
"brain_recall_gate",
"brain_search",
// Schema admin + watchdog recovery probes.
@@ -500,7 +501,8 @@ describe("stdio loop", () => {
// + 3 procedural-learning tools (v0.30.0) = 68.
// + brain_procedural_graph (v0.31.0) = 69.
// + brain_attention_flows (v0.31.0) = 70.
- expect(list.result.tools.length).toBe(70);
+ // + brain_recall_feedback (recall-trust-suite) = 71.
+ expect(list.result.tools.length).toBe(71);
});
test("returns parse error for invalid JSON", async () => {
diff --git a/tests/mcp/recall-feedback-tool.test.ts b/tests/mcp/recall-feedback-tool.test.ts
new file mode 100644
index 00000000..2293f132
--- /dev/null
+++ b/tests/mcp/recall-feedback-tool.test.ts
@@ -0,0 +1,66 @@
+/**
+ * `brain_recall_feedback` (recall-trust-suite, Feature B): MCP-connected
+ * agents record explicit per-result recall feedback. The event lands as
+ * one JSON file under `Brain/search/feedback/` and the derived learned
+ * weights refresh deterministically.
+ */
+
+import { afterEach, beforeEach, describe, expect, test } from "bun:test";
+import { mkdtempSync, rmSync, readdirSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+
+import { SEARCH_TOOLS } from "../../src/mcp/search-tools.ts";
+import { indexVault, resolveSearchConfig } from "../../src/core/search/index.ts";
+import { feedbackDir } from "../../src/core/search/feedback.ts";
+import { atomicWriteFileSync } from "../../src/core/fs-atomic.ts";
+
+let vault: string;
+let configHome: string;
+let ctx: { vault: string; configPath: string };
+
+beforeEach(async () => {
+ vault = mkdtempSync(join(tmpdir(), "o2b-recall-fb-vault-"));
+ configHome = mkdtempSync(join(tmpdir(), "o2b-recall-fb-cfg-"));
+ const configPath = join(configHome, "config.yaml");
+ atomicWriteFileSync(configPath, `vault: ${vault}\n`);
+ writeFileSync(join(vault, "note.md"), "# Note\n\nthe quarterly ledger reconciliation runbook\n");
+ ctx = { vault, configPath };
+ await indexVault(resolveSearchConfig({ vault, configPath }), {});
+});
+
+afterEach(() => {
+ rmSync(vault, { recursive: true, force: true });
+ rmSync(configHome, { recursive: true, force: true });
+});
+
+describe("brain_recall_feedback", () => {
+ test("records one event file and returns the refreshed learned weights", async () => {
+ const tool = SEARCH_TOOLS.find((t) => t.name === "brain_recall_feedback");
+ expect(tool).toBeDefined();
+ // eslint-disable-next-line @typescript-eslint/no-explicit-any
+ const out = (await tool!.handler(ctx as any, {
+ query: "quarterly ledger reconciliation",
+ result_path: "note.md",
+ verdict: "up",
+ })) as {
+ recorded: boolean;
+ learned: { keywordMul: number; events: number };
+ };
+ expect(out.recorded).toBe(true);
+ expect(out.learned.events).toBe(1);
+ expect(readdirSync(feedbackDir(vault))).toHaveLength(1);
+ });
+
+ test("rejects an invalid verdict", async () => {
+ const tool = SEARCH_TOOLS.find((t) => t.name === "brain_recall_feedback")!;
+ // eslint-disable-next-line @typescript-eslint/no-explicit-any
+ await expect(
+ tool.handler(ctx as any, {
+ query: "ledger",
+ result_path: "note.md",
+ verdict: "meh",
+ }),
+ ).rejects.toThrow();
+ });
+});