ltcai 11.5.2 → 11.7.0

package/lattice_brain/graph/provenance.py

@@ -1,524 +0,0 @@
-from __future__ import annotations
-
-from typing import TYPE_CHECKING
-
-# ruff: noqa: F403,F405
-from ._kg_common import *  # noqa: F403,F401
-
-# The cross-mixin surface (`_connect`, `_upsert_node`, …) is declared in
-# `_kg_contract.KnowledgeGraphCore`. It is a typing-only base: at runtime this
-# is `object`, so the MRO of `KnowledgeGraphStore` is unchanged.
-if TYPE_CHECKING:
-    from ._kg_contract import KnowledgeGraphCore as _Core
-else:
-    _Core = object
-
-
-
-class KnowledgeGraphProvenanceMixin(_Core):
-    def record_provenance(
-        self,
-        *,
-        node_id: str,
-        source_type: str,
-        pipeline: str = "unified-ingestion",
-        source_uri: Optional[str] = None,
-        content_hash: Optional[str] = None,
-        title: Optional[str] = None,
-        owner: Optional[str] = None,
-        workspace_id: Optional[str] = None,
-        captured_at: Optional[str] = None,
-        modified_at: Optional[str] = None,
-        embedded: bool = False,
-        linked: bool = False,
-        duplicate: bool = False,
-        agent_used: Optional[str] = None,
-        chunk_count: int = 0,
-        permissions: Optional[Dict[str, Any]] = None,
-        metadata: Optional[Dict[str, Any]] = None,
-    ) -> Dict[str, Any]:
-        """Record where an ingested node came from (upsert by origin).
-
-        Row identity is ``(node, content, source_type, source_uri, pipeline)``
-        — deliberately *not* the wall clock. Through 11.0.x the basis included
-        a second-resolution timestamp, which made the record's identity depend
-        on when it happened: re-ingesting unchanged content twice inside the
-        same second collapsed onto one row, and one second later appended a
-        duplicate. That is not an audit trail, it is a race — the same class of
-        defect as the 11.0.0 review-item ids — and it grew this table (and the
-        "recent ingestions" list built from it) without bound on every re-scan
-        of an unchanged folder or vault.
-
-        With the clock out of the basis, re-ingesting the same content from the
-        same origin *updates* one record (``created_at`` moves to the latest
-        sighting, so "recently seen" stays true), while genuinely new content or
-        a genuinely different origin — another source URI, another pipeline —
-        still appends its own record. The timestamp is data on the row, never
-        part of its identity. Every individual ingest event remains visible in
-        the audit log (``kg_ingest``), which is where per-event history belongs.
-        """
-        now = _now()
-        prov_basis = "|".join([
-            node_id,
-            content_hash or "",
-            source_type,
-            source_uri or "",
-            pipeline,
-        ])
-        prov_id = f"prov:{_sha256_text(prov_basis)[:24]}"
-        with self._connect() as conn:
-            conn.execute(
-                """
-                    INSERT OR REPLACE INTO ingestion_provenance(
-                      id, node_id, source_type, source_uri, content_hash, title, pipeline,
-                      owner, workspace_id, captured_at, modified_at, embedded, linked,
-                      duplicate, agent_used, chunk_count, permissions_json, metadata_json, created_at)
-                    VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
-                    """,
-                (
-                    prov_id,
-                    node_id,
-                    source_type,
-                    source_uri,
-                    content_hash,
-                    title,
-                    pipeline,
-                    owner,
-                    workspace_id,
-                    captured_at,
-                    modified_at,
-                    1 if embedded else 0,
-                    1 if linked else 0,
-                    1 if duplicate else 0,
-                    agent_used,
-                    int(chunk_count or 0),
-                    _json(permissions or {}),
-                    _json(metadata or {}),
-                    now,
-                ),
-            )
-        return {"id": prov_id, "node_id": node_id, "created_at": now}
-
-    @staticmethod
-    def _provenance_row(row: sqlite3.Row) -> Dict[str, Any]:
-        return {
-            "id": row["id"],
-            "node_id": row["node_id"],
-            "source_type": row["source_type"],
-            "source_uri": row["source_uri"],
-            "content_hash": row["content_hash"],
-            "title": row["title"],
-            "pipeline": row["pipeline"],
-            "owner": row["owner"],
-            "workspace_id": row["workspace_id"],
-            "captured_at": row["captured_at"],
-            "modified_at": row["modified_at"],
-            "embedded": bool(row["embedded"]),
-            "linked": bool(row["linked"]),
-            "duplicate": bool(row["duplicate"]),
-            "agent_used": row["agent_used"],
-            "chunk_count": row["chunk_count"],
-            "permissions": _safe_loads(row["permissions_json"]),
-            "metadata": _safe_loads(row["metadata_json"]),
-            "created_at": row["created_at"],
-        }
-
-    def get_provenance(self, node_id: str) -> Optional[Dict[str, Any]]:
-        """Return the most recent provenance record for a node, or None."""
-        with self._connect() as conn:
-            row = conn.execute(
-                "SELECT * FROM ingestion_provenance WHERE node_id = ? "
-                "ORDER BY created_at DESC, rowid DESC LIMIT 1",
-                (node_id,),
-            ).fetchone()
-            return self._provenance_row(row) if row else None
-
-    def list_provenance(
-        self, *, limit: int = 100, source_type: Optional[str] = None
-    ) -> Dict[str, Any]:
-        """Recent provenance records (newest first), optionally by source_type."""
-        limit = max(1, min(int(limit or 100), 1000))
-        with self._connect() as conn:
-            if source_type:
-                rows = conn.execute(
-                    "SELECT * FROM ingestion_provenance WHERE source_type = ? "
-                    "ORDER BY created_at DESC, rowid DESC LIMIT ?",
-                    (source_type, limit),
-                ).fetchall()
-            else:
-                rows = conn.execute(
-                    "SELECT * FROM ingestion_provenance "
-                    "ORDER BY created_at DESC, rowid DESC LIMIT ?",
-                    (limit,),
-                ).fetchall()
-            return {
-                "items": [self._provenance_row(r) for r in rows],
-                "count": len(rows),
-            }
-
-    def provenance_coverage(self) -> Dict[str, Any]:
-        """How much of the brain is explainable: nodes with vs without
-        provenance, per node type — the honesty metric for 'every source goes
-        through the pipeline'. Pre-v4 nodes ingested before provenance existed
-        legitimately count as uncovered."""
-        nt, _ = self._read_tables()
-        with self._connect() as conn:
-            total = conn.execute(f"SELECT COUNT(*) FROM {nt}").fetchone()[0]
-            covered = conn.execute(
-                f"SELECT COUNT(*) FROM {nt} WHERE id IN (SELECT DISTINCT node_id FROM ingestion_provenance)"
-            ).fetchone()[0]
-            uncovered_by_type = {
-                row["type"]: row["c"]
-                for row in conn.execute(
-                    f"""
-                        SELECT type, COUNT(*) AS c FROM {nt}
-                        WHERE id NOT IN (SELECT DISTINCT node_id FROM ingestion_provenance)
-                        GROUP BY type ORDER BY c DESC LIMIT 20
-                        """
-                ).fetchall()
-            }
-            by_source = {
-                row["source_type"]: row["c"]
-                for row in conn.execute(
-                    "SELECT source_type, COUNT(*) AS c FROM ingestion_provenance GROUP BY source_type"
-                ).fetchall()
-            }
-        return {
-            "total_nodes": total,
-            "nodes_with_provenance": covered,
-            "coverage_ratio": round(covered / total, 4) if total else None,
-            "uncovered_by_type": uncovered_by_type,
-            "provenance_by_source_type": by_source,
-        }
-
-    def provenance_stats(self) -> Dict[str, Any]:
-        """Aggregate provenance counts for the Knowledge Graph status surface."""
-        with self._connect() as conn:
-            total = conn.execute(
-                "SELECT COUNT(*) AS c FROM ingestion_provenance"
-            ).fetchone()["c"]
-            by_source = {
-                r["source_type"]: r["c"]
-                for r in conn.execute(
-                    "SELECT source_type, COUNT(*) AS c FROM ingestion_provenance GROUP BY source_type"
-                ).fetchall()
-            }
-            embedded = conn.execute(
-                "SELECT COUNT(*) AS c FROM ingestion_provenance WHERE embedded = 1"
-            ).fetchone()["c"]
-            duplicates = conn.execute(
-                "SELECT COUNT(*) AS c FROM ingestion_provenance WHERE duplicate = 1"
-            ).fetchone()["c"]
-            last = conn.execute(
-                "SELECT created_at FROM ingestion_provenance ORDER BY created_at DESC LIMIT 1"
-            ).fetchone()
-        return {
-            "total": total,
-            "by_source_type": by_source,
-            "embedded": embedded,
-            "duplicates": duplicates,
-            "last_ingested_at": last["created_at"] if last else None,
-        }
-
-    def schema_versions(self) -> Dict[str, Any]:
-        """Versions an exporter stamps and an importer validates against."""
-        try:
-            from .schema import EMBED_DIM as _EMBED_DIM
-            from .schema import KG_SCHEMA_V2_VERSION as _V2
-        except Exception:  # pragma: no cover - kg_schema always importable in practice
-            _EMBED_DIM, _V2 = 1024, 2
-        return {
-            "graph_schema_version": GRAPH_SCHEMA_VERSION,
-            "db_format_version": _KG_DB_FORMAT_VERSION,
-            "kg_v2_schema_version": _V2,
-            "projection_version": _PROJECTION_VERSION,
-            "embed_dim": _EMBED_DIM,
-        }
-
-    def export_graph_data(
-        self,
-        *,
-        workspace_id: Optional[str] = None,
-        include_legacy_global: bool = False,
-    ) -> Dict[str, Any]:
-        """Raw, lossless logical export of the graph (nodes/edges/chunks/sources/
-        provenance). Vector embeddings are intentionally omitted — the importer
-        re-derives them with *its own* embedder (:meth:`import_graph_data`
-        embeds on write and then reindexes, reporting the result under
-        ``index``) — so the artifact stays portable and small. Use
-        :meth:`backup_database` for a faithful binary copy incl. embeddings.
-
-        ``workspace_id`` REALLY filters (v4): the artifact contains only nodes
-        scoped to that workspace, with edges/chunks/provenance restricted to the
-        surviving nodes. Legacy-global rows require the explicit
-        ``include_legacy_global=True`` migration/compatibility opt-in. Pre-v4
-        this parameter was stamped into the header while the data exported
-        everything — a header that lied.
-        """
-        with self._connect() as conn:
-
-            def rows(table: str):
-                return [
-                    dict(r) for r in conn.execute(f"SELECT * FROM {table}").fetchall()
-                ]
-
-            if workspace_id:
-                scope_sql = "workspace_id = ?"
-                if include_legacy_global:
-                    scope_sql += " OR workspace_id IS NULL"
-                keep_ids = {
-                    row["id"]
-                    for row in conn.execute(
-                        f"SELECT id FROM nodes_v2 WHERE {scope_sql}",
-                        (workspace_id,),
-                    ).fetchall()
-                }
-                nodes = [n for n in rows("nodes") if n["id"] in keep_ids]
-                edges = [
-                    e
-                    for e in rows("edges")
-                    if e["from_node"] in keep_ids and e["to_node"] in keep_ids
-                ]
-                chunks = [c for c in rows("chunks") if c["source_node"] in keep_ids]
-                provenance = [
-                    p for p in rows("ingestion_provenance") if p["node_id"] in keep_ids
-                ]
-                data = {
-                    "nodes": nodes,
-                    "edges": edges,
-                    "chunks": chunks,
-                    "knowledge_sources": rows("knowledge_sources"),
-                    "provenance": provenance,
-                }
-            else:
-                data = {
-                    "nodes": rows("nodes"),
-                    "edges": rows("edges"),
-                    "chunks": rows("chunks"),
-                    "knowledge_sources": rows("knowledge_sources"),
-                    "provenance": rows("ingestion_provenance"),
-                }
-        data["counts"] = {k: len(v) for k, v in data.items()}
-        return data
-
-    def _reindex_after_import(self) -> Dict[str, Any]:
-        """Bring the vector index in line with what was just imported.
-
-        A logical artifact carries no embeddings (see :meth:`export_graph_data`)
-        so they have to be re-derived on this machine. The write door
-        (``_upsert_node`` / ``_upsert_chunk``) already embeds inline, which
-        makes this pass a *verification* in the common case — but "the index is
-        consistent after an import" has to be a guarantee the import makes, not
-        an accident of where the embedding call happens to live. It also
-        records the embedder fingerprint, which the inline write path never
-        does; without it ``index_status()`` reports ``recorded: None`` and the
-        ``stale_embedder`` honesty signal is dead after every import.
-
-        Never raises. The graph rows are already committed at this point, so an
-        embedding provider that dies here means "content imported, recall
-        degraded" — reported with the repo's existing ``vector_freshness``
-        vocabulary (``ready`` / ``pending`` / ``stale_embedder`` /
-        ``unavailable``) plus an explicit ``degraded`` flag — never a rollback
-        of work that already landed, and never a silent success.
-        """
-        reindexed = 0
-        try:
-            outcome = self.rebuild_vector_index(full=False) or {}
-            reindexed = int(outcome.get("items_indexed") or 0)
-        except Exception as exc:  # noqa: BLE001 — the import already committed
-            return {
-                "status": "unavailable",
-                "degraded": True,
-                "detail": (
-                    "imported content is stored, but the vector index could not "
-                    f"be rebuilt ({exc}); search stays lexical-only for the new "
-                    "items until a rebuild succeeds"
-                ),
-                "reindexed_items": 0,
-            }
-        report = self.vector_freshness() or {}
-        status = str(report.get("status") or "unavailable")
-        return {
-            "status": status,
-            "degraded": status != "ready",
-            "detail": report.get("detail"),
-            "pending_items": int(report.get("pending_items") or 0),
-            "total_items": int(report.get("total_items") or 0),
-            "reindexed_items": reindexed,
-        }
-
-    def import_graph_data(
-        self, data: Dict[str, Any], *, mode: str = "merge", dry_run: bool = False
-    ) -> Dict[str, Any]:
-        """Import a logical export back into the store.
-
-        ``mode='merge'`` upserts on top of existing data (id collisions update);
-        ``mode='replace'`` clears the graph first (including the derived vector
-        rows — the re-import re-embeds them inside the same transaction, so a
-        failed artifact rolls back to the previous index rather than an empty
-        one). ``dry_run=True`` reports the plan without writing. Refuses
-        artifacts from a NEWER graph schema than this build.
-
-        A completed import carries an ``index`` block reporting the state of
-        the re-derived vector index (see :meth:`_reindex_after_import`); when
-        ``index["degraded"]`` is true, retrieval for the imported scope is
-        lexical-only until the index is rebuilt.
-        """
-        nodes = data.get("nodes") or []
-        edges = data.get("edges") or []
-        chunks = data.get("chunks") or []
-        sources = data.get("knowledge_sources") or []
-        provenance = data.get("provenance") or []
-
-        header = data.get("header") or {}
-        incoming_schema = header.get("graph_schema_version")
-        if isinstance(incoming_schema, int) and incoming_schema > GRAPH_SCHEMA_VERSION:
-            raise ValueError(
-                f"Artifact graph_schema_version {incoming_schema} is newer than this "
-                f"build ({GRAPH_SCHEMA_VERSION}); refusing to import."
-            )
-
-        plan = {
-            "mode": mode,
-            "nodes": len(nodes),
-            "edges": len(edges),
-            "chunks": len(chunks),
-            "knowledge_sources": len(sources),
-            "provenance": len(provenance),
-        }
-        if dry_run:
-            plan["dry_run"] = True
-            return plan
-
-        with self._connect() as conn:
-            if mode == "replace":
-                # Keep replacement imports transactional. The old clear_all()
-                # path committed before the import started, so a malformed
-                # artifact could leave a cleared or partially rebuilt graph.
-                # These deletes roll back with the rest of the import.
-                for table in (
-                    "local_file_index",
-                    "knowledge_sources",
-                    "chunks",
-                    "edges",
-                    "nodes",
-                    "vector_embeddings",
-                ):
-                    conn.execute(f"DELETE FROM {table}")
-                if KGStoreV2 is not None:
-                    conn.execute("DELETE FROM edges_v2")
-                    conn.execute("DELETE FROM nodes_v2")
-            for n in nodes:
-                self._upsert_node(
-                    conn,
-                    n["id"],
-                    n["type"],
-                    n.get("title") or "",
-                    summary=n.get("summary") or "",
-                    metadata=_safe_loads(n.get("metadata_json")),
-                    raw=_safe_loads(n.get("raw_json")),
-                )
-            for c in chunks:
-                self._upsert_chunk(
-                    conn,
-                    chunk_id=c["id"],
-                    source_node=c["source_node"],
-                    text=c.get("text") or "",
-                    metadata=_safe_loads(c.get("metadata_json")),
-                )
-            for e in edges:
-                e_meta = _safe_loads(e.get("metadata_json")) or {}
-                leg_label = e_meta.get("legacy_label")
-                if not leg_label:
-                    orig = e.get("type") or ""
-                    if orig:
-                        # preserve whatever label came from export (legacy or canon)
-                        leg_label = orig
-                self._upsert_edge(
-                    conn,
-                    e["from_node"],
-                    e["to_node"],
-                    e["type"],
-                    weight=float(e.get("weight") or 1.0),
-                    metadata=e_meta,
-                    legacy_label=leg_label,
-                )
-            for s in sources:
-                conn.execute(
-                    """
-                        INSERT OR REPLACE INTO knowledge_sources(
-                          id, root_path, os_type, drive_id, label, status, include_ocr,
-                          watch_enabled, consent_json, created_at, updated_at, last_scanned_at)
-                        VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
-                        """,
-                    (
-                        s["id"],
-                        s["root_path"],
-                        s["os_type"],
-                        s.get("drive_id"),
-                        s.get("label"),
-                        s.get("status") or "active",
-                        int(s.get("include_ocr") or 0),
-                        int(s.get("watch_enabled") or 0),
-                        s.get("consent_json") or "{}",
-                        s.get("created_at") or _now(),
-                        s.get("updated_at") or _now(),
-                        s.get("last_scanned_at"),
-                    ),
-                )
-            for p in provenance:
-                conn.execute(
-                    """
-                        INSERT OR REPLACE INTO ingestion_provenance(
-                          id, node_id, source_type, source_uri, content_hash, title, pipeline,
-                          owner, workspace_id, captured_at, modified_at, embedded, linked,
-                          duplicate, agent_used, chunk_count, permissions_json, metadata_json, created_at)
-                        VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
-                        """,
-                    (
-                        p["id"],
-                        p["node_id"],
-                        p["source_type"],
-                        p.get("source_uri"),
-                        p.get("content_hash"),
-                        p.get("title"),
-                        p.get("pipeline") or "import",
-                        p.get("owner"),
-                        p.get("workspace_id"),
-                        p.get("captured_at"),
-                        p.get("modified_at"),
-                        int(p.get("embedded") or 0),
-                        int(p.get("linked") or 0),
-                        int(p.get("duplicate") or 0),
-                        p.get("agent_used"),
-                        int(p.get("chunk_count") or 0),
-                        p.get("permissions_json") or "{}",
-                        p.get("metadata_json") or "{}",
-                        p.get("created_at") or _now(),
-                    ),
-                )
-        plan["imported"] = True
-        plan["index"] = self._reindex_after_import()
-        return plan
-
-    def backup_database(self, dest_path) -> Path:
-        """Write a clean, standalone snapshot of the live DB to ``dest_path``.
-
-        Uses ``VACUUM INTO`` (after a full WAL checkpoint) so the snapshot is a
-        defragmented, rollback-journal-mode database with no companion -wal/-shm
-        — which restores cleanly by a plain file copy. Captures all data incl.
-        the vector_embeddings BLOBs.
-        """
-        dest = Path(dest_path)
-        dest.parent.mkdir(parents=True, exist_ok=True)
-        if dest.exists():
-            dest.unlink()  # VACUUM INTO requires the target to not exist
-        # Raw connection, not ``_connect()``: VACUUM cannot run inside a
-        # transaction, and ``_connect()`` wraps its block in one.
-        conn = self.storage_engine.connect()
-        try:
-            conn.execute("PRAGMA wal_checkpoint(FULL)")
-            conn.execute("VACUUM INTO ?", (str(dest),))
-        finally:
-            conn.close()
-        return dest

package/lattice_brain/graph/rerank.py

@@ -1,163 +0,0 @@
-"""Optional cross-encoder rerank for hybrid retrieval (v9.9.5).
-
-Default path is identity (fused score preserved) — no model download, no
-latency tax, no unearned claims. Opt in with::
-
-    LATTICEAI_CROSS_ENCODER_RERANK=1
-    # optional model id (sentence-transformers CrossEncoder):
-    LATTICEAI_CROSS_ENCODER_MODEL=cross-encoder/ms-marco-MiniLM-L-6-v2
-
-When the env kill-switch is off, or ``sentence_transformers`` / the model is
-unavailable, :func:`rerank_matches` returns the candidates unchanged and
-reports ``mode="identity"``. Failures never raise into the search path.
-"""
-
-from __future__ import annotations
-
-import logging
-import os
-from typing import Any, Dict, List, Optional
-
-logger = logging.getLogger(__name__)
-
-CROSS_ENCODER_RERANK_ENV = "LATTICEAI_CROSS_ENCODER_RERANK"
-CROSS_ENCODER_MODEL_ENV = "LATTICEAI_CROSS_ENCODER_MODEL"
-DEFAULT_CROSS_ENCODER_MODEL = "cross-encoder/ms-marco-MiniLM-L-6-v2"
-
-_model_cache: Dict[str, Any] = {}
-
-
-def _rerank_enabled() -> bool:
-    raw = os.getenv(CROSS_ENCODER_RERANK_ENV, "").strip().lower()
-    return raw in {"1", "true", "yes", "on"}
-
-
-def _model_id() -> str:
-    raw = os.getenv(CROSS_ENCODER_MODEL_ENV, "").strip()
-    return raw or DEFAULT_CROSS_ENCODER_MODEL
-
-
-def _candidate_text(match: Dict[str, Any]) -> str:
-    parts = [
-        str(match.get("title") or ""),
-        str(match.get("summary") or ""),
-        str((match.get("metadata") or {}).get("snippet") or ""),
-    ]
-    return " ".join(p for p in parts if p).strip() or str(match.get("node_id") or "")
-
-
-def _load_cross_encoder(model_id: str) -> Any:
-    if model_id in _model_cache:
-        return _model_cache[model_id]
-    from sentence_transformers import CrossEncoder  # type: ignore
-
-    model = CrossEncoder(model_id)
-    _model_cache[model_id] = model
-    return model
-
-
-def identity_rerank(
-    query: str,
-    candidates: List[Dict[str, Any]],
-    *,
-    top_k: Optional[int] = None,
-) -> Dict[str, Any]:
-    """Preserve fused ordering; stamp identity scores for an honest contract."""
-    del query  # identity path does not use the query text
-    ranked = list(candidates)
-    for item in ranked:
-        item["rerank_score"] = float(item.get("score") or item.get("fused_score") or 0.0)
-    if top_k is not None:
-        ranked = ranked[: max(1, int(top_k))]
-    return {
-        "matches": ranked,
-        "mode": "identity",
-        "model": None,
-        "detail": None,
-    }
-
-
-def cross_encoder_rerank(
-    query: str,
-    candidates: List[Dict[str, Any]],
-    *,
-    top_k: Optional[int] = None,
-    model_id: Optional[str] = None,
-) -> Dict[str, Any]:
-    """Score (query, candidate) pairs with a CrossEncoder when available."""
-    if not candidates:
-        return {
-            "matches": [],
-            "mode": "cross_encoder",
-            "model": model_id or _model_id(),
-            "detail": None,
-        }
-    mid = model_id or _model_id()
-    try:
-        model = _load_cross_encoder(mid)
-    except Exception as exc:  # noqa: BLE001 — never break search
-        logger.info("cross-encoder unavailable (%s); falling back to identity", exc)
-        result = identity_rerank(query, candidates, top_k=top_k)
-        result["detail"] = f"cross_encoder_unavailable: {exc}"
-        return result
-
-    pairs = [[str(query or ""), _candidate_text(c)] for c in candidates]
-    try:
-        scores = model.predict(pairs)
-    except Exception as exc:  # noqa: BLE001
-        logger.warning("cross-encoder predict failed: %s", exc)
-        result = identity_rerank(query, candidates, top_k=top_k)
-        result["detail"] = f"cross_encoder_predict_failed: {exc}"
-        return result
-
-    ranked = list(candidates)
-    # strict=False on purpose: a cross-encoder that returns fewer scores than
-    # candidates leaves the tail un-reranked at its fused score, which is a
-    # better outcome than dropping the whole rerank.
-    for item, score in zip(ranked, scores, strict=False):
-        item["rerank_score"] = float(score)
-        # Surface the rerank score as the primary ranking key while keeping
-        # the pre-rerank fused score under scores.fused for audit.
-        scores_map = item.setdefault("scores", {})
-        if isinstance(scores_map, dict):
-            scores_map.setdefault("fused", float(item.get("score") or 0.0))
-            scores_map["rerank"] = float(score)
-        item["score"] = float(score)
-    ranked.sort(key=lambda m: (-float(m.get("rerank_score") or 0.0), str(m.get("node_id") or "")))
-    if top_k is not None:
-        ranked = ranked[: max(1, int(top_k))]
-    for rank, match in enumerate(ranked, start=1):
-        match["rank"] = rank
-    return {
-        "matches": ranked,
-        "mode": "cross_encoder",
-        "model": mid,
-        "detail": None,
-    }
-
-
-def rerank_matches(
-    query: str,
-    candidates: List[Dict[str, Any]],
-    *,
-    top_k: Optional[int] = None,
-    force: Optional[bool] = None,
-) -> Dict[str, Any]:
-    """Public entry: cross-encoder when enabled, else identity.
-
-    ``force=True/False`` overrides the env kill-switch (tests only).
-    """
-    enabled = _rerank_enabled() if force is None else bool(force)
-    if not enabled:
-        return identity_rerank(query, candidates, top_k=top_k)
-    return cross_encoder_rerank(query, candidates, top_k=top_k)
-
-
-__all__ = [
-    "CROSS_ENCODER_MODEL_ENV",
-    "CROSS_ENCODER_RERANK_ENV",
-    "DEFAULT_CROSS_ENCODER_MODEL",
-    "cross_encoder_rerank",
-    "identity_rerank",
-    "rerank_matches",
-]