Release v2.7.0: harden retrieval broker

CHANGELOG.md

@@ -7,6 +7,58 @@ onward the project follows SemVer normally: patch releases are
 bug-fix-only, minor releases are backward-compatible additions, and
 breaking changes require a major bump.
 
+## v2.7.0: Retrieval that knows when to stay silent
+
+This release hardens the semantic broker around the cases that ordinary
+retrieval benchmarks miss: unrelated memories that should not be injected,
+near-miss traps, cited incumbents that have been superseded, and ranking policy
+that used to disappear whenever a cross-encoder reranker ran.
+
+The final release candidate raises comprehensive BrainBench from **91.3% to
+92.4%** over 264 scenarios. Its importance dimension moves **92.1% → 97.4%**
+and retrieval **56.6% → 97.0%**, with calibration and dedup unchanged. On the
+new workflow fixtures it scores **79.0%** over a stratified 150-scenario slice;
+the 100-scenario update stream reaches **89.3%** overall and resolves the newer
+fact over its cited incumbent in **33/33** applicable cases.
+
+### Added
+
+- **Absolute-evidence abstention for new brains.** The old whole-bundle gate
+  read a normalized composite whose best candidate was strong by construction,
+  so it could not distinguish a useful hit from the best item in an unrelated
+  corpus. New project configs use a per-embedder auto floor on raw cosine.
+  Existing configs keep the gate off unless they opt in, and lean/cross-model
+  retrieval is exempt because lexical relevance is not on the calibrated
+  cosine scale.
+- **Cross-encoder arbitration for borderline bundles.** The evidence band is
+  now resolved by the reranker, and the same implementation is used by the CLI,
+  MCP server, and warm embed daemon. A rejected bundle becomes a true skipped,
+  zero-token result instead of leaking low-confidence capsules downstream.
+- **Supersession-aware ranking.** Newer near-restatements beat older cited
+  incumbents, with correction-language and lexical-identity support for larger
+  rewrites. Same-batch co-writes are protected, and ambiguous low-similarity
+  pairs consult query relevance so historical questions still retrieve the
+  fact that was true at the requested time.
+- **Post-rerank usefulness policy.** Learned citation/regret tiers and
+  supersession hints ride on each capsule and are reapplied after cross-encoder
+  scoring. This prevents relevance-only rerankers from silently erasing broker
+  policy while retaining their ordering within each policy tier.
+
+### Fixed
+
+- The CLI now has reranker parity with the MCP and daemon paths; semantic
+  benchmark runs no longer measure a different ranking pipeline from shipped
+  commands.
+- Reranker initialization failures are reported before Kimetsu fails open to
+  bi-encoder ordering, instead of silently making an intended cross-encoder run
+  look successful.
+- User-defined Hugging Face rerankers honor `HF_HOME`, allowing benchmark and
+  sandbox workspaces to share one cache instead of repeatedly downloading the
+  same model into each current working directory.
+- Reranker retention and band admission are evaluated on raw cross-encoder
+  evidence before supersession penalties, usefulness ordering, or output caps,
+  so policy cannot accidentally change whether a bundle is admitted.
+
 ## v2.6.1: Dependency security sweep
 
 A security-only patch release. Clears every open advisory against the

Cargo.toml

@@ -15,7 +15,7 @@ resolver = "3"
 # everything below except the per-crate `description`, `keywords`,
 # and `categories` which live in each `[package]` block since
 # crates.io enforces them per crate.
-version = "2.6.1"
+version = "2.7.0"
 edition = "2024"
 # Rust ecosystem dual-license (matches tokio, serde, fastembed-rs,
 # etc.). UNLICENSED would block crates.io entirely.

crates/kimetsu-agent/Cargo.toml

@@ -27,8 +27,8 @@ aws-sigv4.workspace = true
 aws-smithy-runtime-api.workspace = true
 blake3.workspace = true
 http.workspace = true
-kimetsu-brain = { path = "../kimetsu-brain", version = "2.6.1" }
-kimetsu-core = { path = "../kimetsu-core", version = "2.6.1" }
+kimetsu-brain = { path = "../kimetsu-brain", version = "2.7.0" }
+kimetsu-core = { path = "../kimetsu-core", version = "2.7.0" }
 regex.workspace = true
 reqwest.workspace = true
 rusqlite.workspace = true

crates/kimetsu-agent/src/pipeline.rs

@@ -249,6 +249,7 @@ pub fn run_coding(options: CodingRunOptions) -> KimetsuResult<CodingRunResult> {
             excluded: Vec::new(),
             skipped: false,
             top_score: 0.0,
+            top_abs_evidence: 0.0,
             evidence_coverage: 1.0,
             uncovered_terms: Vec::new(),
             chronological: false,
@@ -261,6 +262,7 @@ pub fn run_coding(options: CodingRunOptions) -> KimetsuResult<CodingRunResult> {
             excluded: Vec::new(),
             skipped: false,
             top_score: 0.0,
+            top_abs_evidence: 0.0,
             evidence_coverage: 1.0,
             uncovered_terms: Vec::new(),
             chronological: false,
@@ -3148,6 +3150,8 @@ mod tests {
             relevance: 0.8,
             scope_weight: 1.0,
             score: 0.75,
+            superseded_hint: false,
+            rerank_policy_tier: 0,
         }
     }
 
@@ -3160,6 +3164,7 @@ mod tests {
             excluded: Vec::new(),
             skipped: false,
             top_score: 0.75,
+            top_abs_evidence: 0.0,
             evidence_coverage: 1.0,
             uncovered_terms: Vec::new(),
             chronological: false,
@@ -3528,6 +3533,7 @@ mod tests {
             excluded: Vec::new(),
             skipped: true,
             top_score: 0.0,
+            top_abs_evidence: 0.0,
             evidence_coverage: 1.0,
             uncovered_terms: Vec::new(),
             chronological: false,
@@ -3547,6 +3553,7 @@ mod tests {
             excluded: Vec::new(),
             skipped: false,
             top_score: 0.0,
+            top_abs_evidence: 0.0,
             evidence_coverage: 1.0,
             uncovered_terms: Vec::new(),
             chronological: false,

crates/kimetsu-brain/Cargo.toml

@@ -50,7 +50,7 @@ hf-hub = { version = "0.5", optional = true, default-features = false, features
 # already native (ort). The lean build never links it.
 usearch = { version = "2", optional = true }
 ignore.workspace = true
-kimetsu-core = { path = "../kimetsu-core", version = "2.6.1" }
+kimetsu-core = { path = "../kimetsu-core", version = "2.7.0" }
 # v0.4.5: regex backs the secret-redaction patterns in
 # `kimetsu_brain::redact`. The crate is already a workspace pin
 # elsewhere; we just opt this crate into it now.

crates/kimetsu-brain/src/backend.rs

@@ -462,6 +462,8 @@ fn fetch_graph_candidates(
                 relevance: 0.0,
                 scope_weight,
                 score: 0.0,
+                superseded_hint: false,
+                rerank_policy_tier: 0,
             },
         });
     }

crates/kimetsu-brain/src/benchmark.rs

@@ -687,6 +687,7 @@ mod tests {
             excluded: Vec::new(),
             skipped: false,
             top_score: 0.0,
+            top_abs_evidence: 0.0,
             evidence_coverage: 1.0,
             uncovered_terms: Vec::new(),
             chronological: false,
@@ -782,6 +783,7 @@ mod tests {
             excluded: Vec::new(),
             skipped: false,
             top_score: 0.0,
+            top_abs_evidence: 0.0,
             evidence_coverage: 1.0,
             uncovered_terms: Vec::new(),
             chronological: false,
@@ -822,6 +824,7 @@ mod tests {
             excluded: Vec::new(),
             skipped: false,
             top_score: 0.0,
+            top_abs_evidence: 0.0,
             evidence_coverage: 1.0,
             uncovered_terms: Vec::new(),
             chronological: false,
@@ -860,6 +863,7 @@ mod tests {
             excluded: Vec::new(),
             skipped: false,
             top_score: 0.0,
+            top_abs_evidence: 0.0,
             evidence_coverage: 1.0,
             uncovered_terms: Vec::new(),
             chronological: false,
@@ -904,6 +908,8 @@ mod tests {
             relevance: 1.0,
             scope_weight: 1.0,
             score,
+            superseded_hint: false,
+            rerank_policy_tier: 0,
         }
     }
 }

crates/kimetsu-brain/src/bitemporal.rs

@@ -174,6 +174,8 @@ pub fn as_of_capsules(memories: &[AsOfMemory]) -> Vec<ContextCapsule> {
             relevance: 0.0,
             scope_weight: 0.0,
             score: 0.0,
+            superseded_hint: false,
+            rerank_policy_tier: 0,
         })
         .collect()
 }