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.jsonindex 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.jsonindex 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/.gitignoreindex 64dd831f..2085cc2a 100644--- a/.gitignore+++ b/.gitignore@@ -24,3 +24,4 @@ node_modules/sandbox-vault/.codegraph/.orphaned_at+.claude/scheduled_tasks.lockdiff --git a/CHANGELOG.md b/CHANGELOG.mdindex 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.2diff --git a/README.md b/README.mdindex 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 profileo2b brain agent-query --agent claude --json # Source-agent provenance queryo2b brain agent-diff --mode diff --agent claude --agent codexo2b 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 weightso2b search focus set --query "current task" --path Notes/Projecto2b secrets list --json # Inspect $secret:NAME references without printing valueso2b help --json # Machine-readable command/flag manifestdiff --git a/docs/brainstorm/recall-trust-suite/cli-output/claude.md b/docs/brainstorm/recall-trust-suite/cli-output/claude.mdnew file mode 100644index 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.mdnew file mode 100644index 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.mdnew file mode 100644index 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.mdnew file mode 100644index 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.mdnew file mode 100644index 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.mdindex 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=openfilters 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 termsand `-excluded` tokens; `vec:` and `hyde:` provide semantic text lanes when thediff --git a/docs/mcp.md b/docs/mcp.mdindex 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.jsonindex 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.jsonindex 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.yamlindex 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: truediff --git a/plugins/codex/.codex-plugin/plugin.json b/plugins/codex/.codex-plugin/plugin.jsonindex 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.yamlindex 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: truediff --git a/pyproject.toml b/pyproject.tomlindex 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.tsindex 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>): Promireturn 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): voprocess.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.tsnew file mode 100644index 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.tsindex 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.tsnew file mode 100644index 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.tsindex 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.tsnew file mode 100644index 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.tsindex 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.tsindex 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.tsnew file mode 100644index 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.tsindex 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.tsindex 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.tsnew file mode 100644index 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.tsindex 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.tsnew file mode 100644index 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.tsnew file mode 100644index 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.tsnew file mode 100644index 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.tsnew file mode 100644index 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.tsindex 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>): ResolvedSearchCosynonymMaxTerms: 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.tsindex 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.tsnew file mode 100644index 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.tsindex 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.tsindex 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.tsnew file mode 100644index 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();+ });+});