mostlyright-data 0.9.0__py3-none-any.whl

mostlyright/data_harness/local_search/service.py

@@ -0,0 +1,784 @@
+"""Read-only local search across separately sealed public and private indexes.
+
+The two stores are captured and verified independently.  Their results meet only as immutable
+identities in this module; no combined index is written.  Similarity orders candidates but grants
+nothing: private reuse still requires the closed fact filters and one fresh exact-Build replay,
+while public use still requires the source facts gate.
+"""
+
+from __future__ import annotations
+
+import json
+from collections.abc import Mapping
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Any
+
+from mostlyright.data_harness.canonical import canonical_sha256, sha256_bytes
+from mostlyright.data_harness.local_search.contracts import (
+    BuildField,
+    BuildIndexEntry,
+    BuildRecipeLineage,
+    BuildSourceFacts,
+    BuildTimeCoverage,
+    LocalSearchContractError,
+    SealedProfileFactsV1,
+)
+from mostlyright.data_harness.local_search.query_trace import (
+    PrivateBuildQueryTrace,
+    build_private_query_trace,
+)
+from mostlyright.data_harness.local_search.retrieval import (
+    BuildFilters,
+    retrieve_build_candidates,
+)
+from mostlyright.data_harness.local_search.sealed import (
+    CapturedBuildIndexSnapshot,
+    capture_build_index_snapshot,
+)
+from mostlyright.data_harness.pipeline import (
+    RECIPE_MANIFEST_VERSION,
+    BuildError,
+    VerifiedSnapshot,
+    open_verified_snapshot,
+)
+from mostlyright.data_harness.sources.catalog.embedding import (
+    EmbeddingBackend,
+    LexicalHashingBackend,
+    resolve_local_neural_backend,
+)
+from mostlyright.data_harness.sources.catalog.gating import CatalogRequirement
+from mostlyright.data_harness.sources.catalog.packed_retrieval import (
+    CatalogSearchWorkLimits,
+    detect_public_store_kind,
+)
+from mostlyright.data_harness.sources.catalog.query_trace import (
+    CatalogPackedQueryTrace,
+    CatalogQueryTraceV2,
+    PackedCatalogAnswer,
+    _recommend_loaded,
+    _trace_candidates,
+    query_packed_catalog_with_trace,
+)
+from mostlyright.data_harness.sources.catalog.retrieval import _rank_retrieval
+from mostlyright.data_harness.sources.catalog.retrieval_manifest import (
+    LoadedRetrievalCatalog,
+    load_retrieval_catalog,
+)
+from mostlyright.data_harness.sources.contracts import SourceContractError
+
+LOCAL_SEARCH_TRACE_VERSION = "harness-combined-local-search-trace.v1"
+LOCAL_SEARCH_PAYLOAD_VERSION = "mr-data-local-search.v1"
+
+#: ``public_incomplete`` exists so a public retrieval that ran out of its stated budget can never
+#: be presented as an answer. Without it the only honest outcomes left would be ``no_match`` (the
+#: catalog holds nothing like this -- a claim the search never established) or ``use_source`` from
+#: whatever fraction of the ranges the budget happened to reach.
+_RECOMMENDATION_KINDS = frozenset({"reuse_build", "use_source", "no_match", "public_incomplete"})
+_PUBLIC_STORE_KINDS = frozenset({"packed", "retrieval_v2"})
+_BUILD_DISPOSITIONS = frozenset({"not_selected", "verified", "rejected"})
+_BUILD_DIAGNOSTICS = frozenset(
+    {"build_locator_invalid", "build_verification_failed", "build_identity_mismatch"}
+)
+
+
+@dataclass(frozen=True)
+class VerifiedBuildEvidence:
+    """The three identities corroborated by one replay-verified selected Build snapshot."""
+
+    facts_sha256: str
+    candidate_sha256: str
+    table_sha256: str
+
+    def to_dict(self) -> dict[str, str]:
+        return {
+            "facts_sha256": self.facts_sha256,
+            "candidate_sha256": self.candidate_sha256,
+            "table_sha256": self.table_sha256,
+        }
+
+
+@dataclass(frozen=True)
+class BuildSelectionTrace:
+    """Typed outcome of the sole fresh-Build verification opportunity."""
+
+    selected_facts_sha256: str | None
+    disposition: str
+    diagnostic: str | None
+    verified: VerifiedBuildEvidence | None
+
+    def __post_init__(self) -> None:
+        if self.disposition not in _BUILD_DISPOSITIONS:
+            raise LocalSearchContractError(
+                "LOCAL_SEARCH_SERVICE_DISPOSITION",
+                "trace.build_selection.disposition",
+                "must be not_selected, verified, or rejected",
+            )
+        if self.disposition == "not_selected":
+            valid = (
+                self.selected_facts_sha256 is None
+                and self.diagnostic is None
+                and self.verified is None
+            )
+        elif self.disposition == "verified":
+            valid = (
+                self.selected_facts_sha256 is not None
+                and self.diagnostic is None
+                and self.verified is not None
+                and self.verified.facts_sha256 == self.selected_facts_sha256
+            )
+        else:
+            valid = (
+                self.selected_facts_sha256 is not None
+                and self.diagnostic in _BUILD_DIAGNOSTICS
+                and self.verified is None
+            )
+        if not valid:
+            raise LocalSearchContractError(
+                "LOCAL_SEARCH_SERVICE_DISPOSITION",
+                "trace.build_selection",
+                "selection identities, diagnostic, and disposition disagree",
+            )
+
+    def to_dict(self) -> dict[str, Any]:
+        return {
+            "selected_facts_sha256": self.selected_facts_sha256,
+            "disposition": self.disposition,
+            "diagnostic": self.diagnostic,
+            "verified": None if self.verified is None else self.verified.to_dict(),
+        }
+
+
+@dataclass(frozen=True)
+class CombinedLocalSearchTrace:
+    """Canonical evidence for both independent queries and the final precedence decision."""
+
+    public_store_kind: str
+    public_manifest_sha256: str
+    private_manifest_sha256: str
+    public_backend_coordinate: str
+    private_backend_coordinate: str
+    question_digest: str
+    question_sha256: str
+    question_binding_sha256: str
+    filters_sha256: str
+    public: CatalogQueryTraceV2 | CatalogPackedQueryTrace
+    private: PrivateBuildQueryTrace
+    build_selection: BuildSelectionTrace
+    recommendation_kind: str
+    schema_version: str = LOCAL_SEARCH_TRACE_VERSION
+
+    def __post_init__(self) -> None:
+        if self.schema_version != LOCAL_SEARCH_TRACE_VERSION:
+            raise LocalSearchContractError(
+                "LOCAL_SEARCH_SERVICE_VERSION",
+                "trace.schema_version",
+                f"must equal {LOCAL_SEARCH_TRACE_VERSION!r}",
+            )
+        if self.public_store_kind not in _PUBLIC_STORE_KINDS:
+            raise LocalSearchContractError(
+                "LOCAL_SEARCH_SERVICE_STORE",
+                "trace.public_store_kind",
+                "must name the packed or the v2 public store",
+            )
+        packed = self.public_store_kind == "packed"
+        if packed is not isinstance(self.public, CatalogPackedQueryTrace):
+            raise LocalSearchContractError(
+                "LOCAL_SEARCH_SERVICE_STORE",
+                "trace.public",
+                "the public evidence must be the evidence of the store it names",
+            )
+        if self.recommendation_kind not in _RECOMMENDATION_KINDS:
+            raise LocalSearchContractError(
+                "LOCAL_SEARCH_SERVICE_RECOMMENDATION",
+                "trace.recommendation_kind",
+                "must be reuse_build, use_source, no_match, or public_incomplete",
+            )
+        bindings = (
+            self.public_manifest_sha256
+            == (self.public.head_sha256 if packed else self.public.retrieval_manifest_sha256),
+            self.private_manifest_sha256 == self.private.private_index_manifest_sha256,
+            self.public_backend_coordinate == self.public.backend_coordinate,
+            self.private_backend_coordinate == self.private.backend_coordinate,
+            self.question_digest == self.public.question_digest,
+            self.question_sha256 == self.private.question_sha256,
+            self.question_binding_sha256
+            == canonical_sha256(
+                {
+                    "public_question_digest": self.public.question_digest,
+                    "private_question_sha256": self.private.question_sha256,
+                }
+            ),
+            self.filters_sha256 == self.private.filters_sha256,
+            self.build_selection.selected_facts_sha256 == self.private.selected_facts_sha256,
+        )
+        if not all(bindings):
+            raise LocalSearchContractError(
+                "LOCAL_SEARCH_SERVICE_BINDING",
+                "trace",
+                "combined trace disagrees with a retained query result",
+            )
+        if self.build_selection.disposition == "verified":
+            selected = tuple(
+                candidate
+                for candidate in self.private.candidates
+                if candidate.facts_sha256 == self.private.selected_facts_sha256
+            )
+            verified = self.build_selection.verified
+            if (
+                len(selected) != 1
+                or verified is None
+                or selected[0].candidate_sha256 != verified.candidate_sha256
+                or selected[0].table_sha256 != verified.table_sha256
+                or selected[0].facts_sha256 != verified.facts_sha256
+            ):
+                raise LocalSearchContractError(
+                    "LOCAL_SEARCH_SERVICE_BINDING",
+                    "trace.build_selection.verified",
+                    "verified Build identities must match the selected private candidate",
+                )
+        expected_kind = (
+            "reuse_build"
+            if self.build_selection.disposition == "verified"
+            else "public_incomplete"
+            if packed and self.public.status == "incomplete"
+            else "use_source"
+            if self.public.admitted
+            else "no_match"
+        )
+        if self.recommendation_kind != expected_kind:
+            raise LocalSearchContractError(
+                "LOCAL_SEARCH_SERVICE_PRECEDENCE",
+                "trace.recommendation_kind",
+                "must follow reuse_build, public_incomplete, use_source, no_match precedence",
+            )
+
+    @property
+    def digest(self) -> str:
+        return canonical_sha256(self.to_dict())
+
+    def to_dict(self) -> dict[str, Any]:
+        return {
+            "schema_version": self.schema_version,
+            "public_store_kind": self.public_store_kind,
+            "public_manifest_sha256": self.public_manifest_sha256,
+            "private_manifest_sha256": self.private_manifest_sha256,
+            "public_backend_coordinate": self.public_backend_coordinate,
+            "private_backend_coordinate": self.private_backend_coordinate,
+            "question_digest": self.question_digest,
+            "question_sha256": self.question_sha256,
+            "question_binding_sha256": self.question_binding_sha256,
+            "filters_sha256": self.filters_sha256,
+            "public": self.public.to_dict(),
+            "private": self.private.to_dict(),
+            "build_selection": self.build_selection.to_dict(),
+            "recommendation_kind": self.recommendation_kind,
+        }
+
+
+@dataclass(frozen=True)
+class CapturedLocalSearch:
+    """One response plus the exact independent in-memory observations that produced it."""
+
+    payload: dict[str, Any]
+    trace: CombinedLocalSearchTrace
+    public_snapshot: LoadedRetrievalCatalog | PackedCatalogAnswer
+    private_snapshot: CapturedBuildIndexSnapshot
+    verified_build: VerifiedBuildEvidence | None
+
+
+def capture_local_search(
+    *,
+    public_index_root: Path,
+    expected_public_manifest_sha256: str,
+    private_index_root: Path,
+    expected_private_manifest_sha256: str,
+    build_root: Path,
+    question: str,
+    source_requirement: CatalogRequirement,
+    build_filters: BuildFilters,
+    public_backend: str,
+    allow_lexical_fallback: bool,
+    private_backend: str,
+    neural_model_root: Path | None = None,
+    public_packed_receipt: Mapping[str, Any] | None = None,
+    catalog_work_limits: CatalogSearchWorkLimits | None = None,
+    limit: int = 5,
+) -> CapturedLocalSearch:
+    """Return one deterministic recommendation from separately verified local stores.
+
+    The public store is dispatched by what is installed at its root. A range-local packed head is
+    answered by the bounded packed reader and *requires* both its publication receipt and a closed
+    work contract; a v2 retrieval manifest is answered by its sealed reader and accepts neither.
+    There is deliberately no default work contract: an omitted budget is a refusal, never an
+    unbounded search nobody asked for.
+    """
+
+    if not isinstance(build_root, Path):
+        raise LocalSearchContractError("LOCAL_SEARCH_TYPE", "build_root", "must be a pathlib.Path")
+    store_kind = detect_public_store_kind(public_index_root)
+    packed = store_kind == "packed"
+    if packed and (public_packed_receipt is None or catalog_work_limits is None):
+        raise LocalSearchContractError(
+            "LOCAL_SEARCH_SERVICE_WORK_LIMITS",
+            "catalog_work_limits",
+            "a packed public store is searched only under its receipt and a stated work budget",
+        )
+    if not packed and (public_packed_receipt is not None or catalog_work_limits is not None):
+        raise LocalSearchContractError(
+            "LOCAL_SEARCH_SERVICE_WORK_LIMITS",
+            "catalog_work_limits",
+            "a v2 public store takes neither a packed receipt nor packed work limits",
+        )
+    if not packed and store_kind != "retrieval_v2":
+        raise LocalSearchContractError(
+            "LOCAL_SEARCH_SERVICE_STORE",
+            "public_index_root",
+            "combined local search answers from a packed head or a v2 retrieval manifest",
+        )
+    public_neural_backend, private_encoder = _resolve_backends(
+        public_backend=public_backend,
+        private_backend=private_backend,
+        neural_model_root=neural_model_root,
+        allow_lexical_fallback=allow_lexical_fallback,
+    )
+    if packed:
+        assert public_packed_receipt is not None and catalog_work_limits is not None
+        public_snapshot: LoadedRetrievalCatalog | PackedCatalogAnswer = (
+            query_packed_catalog_with_trace(
+                directory=public_index_root,
+                expected_head_sha256=expected_public_manifest_sha256,
+                receipt=public_packed_receipt,
+                backend=_packed_query_backend(
+                    public_backend=public_backend,
+                    neural=public_neural_backend,
+                    allow_lexical_fallback=allow_lexical_fallback,
+                ),
+                question=question,
+                requirement=source_requirement,
+                work_limits=catalog_work_limits,
+                limit=limit,
+            )
+        )
+        public_trace: CatalogQueryTraceV2 | CatalogPackedQueryTrace = public_snapshot.trace
+        public_recommendation = None
+    else:
+        public_snapshot = load_retrieval_catalog(
+            public_index_root,
+            expected_manifest_sha256=expected_public_manifest_sha256,
+            neural_backend=public_neural_backend,
+        )
+        public_recommendation, public_trace = _query_public_snapshot(
+            public_snapshot,
+            manifest_sha256=expected_public_manifest_sha256,
+            backend=public_backend,
+            allow_lexical_fallback=allow_lexical_fallback,
+            question=question,
+            requirement=source_requirement,
+            limit=limit,
+        )
+    private_snapshot = capture_build_index_snapshot(
+        private_index_root,
+        expected_manifest_sha256=expected_private_manifest_sha256,
+    )
+    private_retrieval = retrieve_build_candidates(
+        private_snapshot.entries,
+        filters=build_filters,
+        question=question,
+        backend=private_encoder,
+        limit=limit,
+    )
+    private_trace = build_private_query_trace(
+        private_index_manifest_sha256=expected_private_manifest_sha256,
+        entries=private_snapshot.entries,
+        retrieval=private_retrieval,
+    )
+    selection = _verify_selected_build(
+        private_snapshot,
+        selected_facts_sha256=private_trace.selected_facts_sha256,
+        build_root=build_root,
+    )
+    recommendation = (
+        _packed_recommendation(selection, answer=public_snapshot)
+        if packed
+        else _recommendation(
+            selection,
+            public_recommendation=public_recommendation,
+            public_snapshot=public_snapshot,
+        )
+    )
+    trace = CombinedLocalSearchTrace(
+        public_store_kind=store_kind,
+        public_manifest_sha256=expected_public_manifest_sha256,
+        private_manifest_sha256=expected_private_manifest_sha256,
+        public_backend_coordinate=public_trace.backend_coordinate,
+        private_backend_coordinate=private_trace.backend_coordinate,
+        question_digest=canonical_sha256({"question": question}),
+        question_sha256=sha256_bytes(question.encode("utf-8")),
+        question_binding_sha256=canonical_sha256(
+            {
+                "public_question_digest": public_trace.question_digest,
+                "private_question_sha256": private_trace.question_sha256,
+            }
+        ),
+        filters_sha256=build_filters.digest,
+        public=public_trace,
+        private=private_trace,
+        build_selection=selection,
+        recommendation_kind=recommendation["kind"],
+    )
+    payload = {
+        "schema_version": LOCAL_SEARCH_PAYLOAD_VERSION,
+        "status": (
+            "local_search_incomplete"
+            if recommendation["kind"] == "public_incomplete"
+            else "local_search_complete"
+        ),
+        "recommendation": recommendation,
+        "trace": trace.to_dict(),
+    }
+    return CapturedLocalSearch(
+        payload=payload,
+        trace=trace,
+        public_snapshot=public_snapshot,
+        private_snapshot=private_snapshot,
+        verified_build=selection.verified,
+    )
+
+
+def _resolve_backends(
+    *,
+    public_backend: str,
+    private_backend: str,
+    neural_model_root: Path | None,
+    allow_lexical_fallback: bool,
+) -> tuple[EmbeddingBackend | None, EmbeddingBackend]:
+    """Resolve only built-in lexical or governed local-neural implementations."""
+
+    allowed = frozenset({"lexical", "neural"})
+    for name, value in (
+        ("public_backend", public_backend),
+        ("private_backend", private_backend),
+    ):
+        if type(value) is not str or value not in allowed:
+            raise LocalSearchContractError(
+                "LOCAL_SEARCH_SERVICE_BACKEND",
+                name,
+                "must select the closed lexical or neural backend",
+            )
+    if type(allow_lexical_fallback) is not bool:
+        raise LocalSearchContractError(
+            "LOCAL_SEARCH_TYPE",
+            "allow_lexical_fallback",
+            "must be a boolean",
+        )
+    needs_neural = public_backend == "neural" or private_backend == "neural"
+    if not needs_neural:
+        if neural_model_root is not None:
+            raise LocalSearchContractError(
+                "LOCAL_SEARCH_SERVICE_BACKEND",
+                "neural_model_root",
+                "must be absent when neither search path selects neural",
+            )
+        return None, LexicalHashingBackend()
+    if neural_model_root is not None and not isinstance(neural_model_root, Path):
+        raise LocalSearchContractError(
+            "LOCAL_SEARCH_TYPE", "neural_model_root", "must be a pathlib.Path or null"
+        )
+    if (
+        public_backend == "neural"
+        and private_backend == "lexical"
+        and allow_lexical_fallback
+        and neural_model_root is None
+    ):
+        return None, LexicalHashingBackend()
+    try:
+        neural = resolve_local_neural_backend(neural_model_root)
+    except SourceContractError as error:
+        public_only_fallback = (
+            public_backend == "neural" and private_backend == "lexical" and allow_lexical_fallback
+        )
+        typed_unavailable = error.code in {
+            "NEURAL_MODEL_ROOT_REQUIRED",
+            "NEURAL_MODEL_ROOT_UNAVAILABLE",
+            "NEURAL_RUNTIME_UNAVAILABLE",
+            "NEURAL_TUPLE_UNAVAILABLE",
+        }
+        if public_only_fallback and typed_unavailable:
+            return None, LexicalHashingBackend()
+        raise
+    return (
+        neural if public_backend == "neural" else None,
+        neural if private_backend == "neural" else LexicalHashingBackend(),
+    )
+
+
+def _packed_query_backend(
+    *,
+    public_backend: str,
+    neural: EmbeddingBackend | None,
+    allow_lexical_fallback: bool,
+) -> EmbeddingBackend:
+    """Pick the one concrete encoder a packed search will run. Never discover one.
+
+    A packed generation publishes exactly which backend coordinates it has packs for, and the
+    reader refuses a coordinate it does not publish -- so this only has to answer which of the two
+    governed local encoders the caller selected, under the same explicit fallback rule the v2 path
+    uses.
+    """
+
+    if public_backend == "lexical":
+        return LexicalHashingBackend()
+    if neural is not None:
+        return neural
+    if not allow_lexical_fallback:
+        raise LocalSearchContractError(
+            "LOCAL_SEARCH_SERVICE_BACKEND",
+            "public_backend",
+            "a neural packed search without an authorized fallback needs its resolved backend",
+        )
+    return LexicalHashingBackend()
+
+
+def _packed_recommendation(
+    selection: BuildSelectionTrace, *, answer: PackedCatalogAnswer
+) -> dict[str, Any]:
+    """Precedence over a packed public store, with incompleteness surfaced rather than swallowed."""
+
+    if selection.verified is not None:
+        return {"kind": "reuse_build", **selection.verified.to_dict()}
+    if answer.status == "incomplete":
+        return {"kind": "public_incomplete", "incomplete_code": answer.incomplete_code}
+    if not answer.trace.admitted:
+        return {"kind": "no_match"}
+    coordinate = answer.trace.admitted[0]
+    entry = next(item for item in answer.entries if item.coordinate == coordinate)
+    traced = next(item for item in answer.trace.candidates if item.entry_coordinate == coordinate)
+    return {
+        "kind": "use_source",
+        "entry_coordinate": coordinate,
+        "entry_digest": entry.digest,
+        "semantic_facts_digest": traced.semantic_facts_digest,
+    }
+
+
+def _query_public_snapshot(
+    snapshot: LoadedRetrievalCatalog,
+    *,
+    manifest_sha256: str,
+    backend: str,
+    allow_lexical_fallback: bool,
+    question: str,
+    requirement: CatalogRequirement,
+    limit: int,
+):
+    entry_ids, representation, backend_coordinate, fallback_reason = _rank_retrieval(
+        snapshot,
+        question,
+        backend=backend,
+        allow_lexical_fallback=allow_lexical_fallback,
+        limit=limit,
+    )
+    recommendation = _recommend_loaded(
+        snapshot,
+        entry_ids,
+        question=question,
+        requirement=requirement,
+    )
+    representation_manifest = (
+        snapshot.manifest.neural if representation == "neural" else snapshot.manifest.lexical
+    )
+    if representation_manifest is None:  # pragma: no cover - the ranker guards this state
+        raise LocalSearchContractError(
+            "LOCAL_SEARCH_SERVICE_BINDING",
+            "public.representation",
+            "selected representation is absent from the verified manifest",
+        )
+    by_coordinate = {entry.coordinate: entry for entry in snapshot.lexical.entries}
+    trace = CatalogQueryTraceV2(
+        retrieval_manifest_sha256=manifest_sha256,
+        representation=representation,
+        representation_artifact_sha256=representation_manifest.artifact_sha256,
+        backend_coordinate=backend_coordinate,
+        fallback_reason=fallback_reason,
+        requested_backend=backend,
+        lexical_fallback_allowed=allow_lexical_fallback,
+        question_digest=recommendation.question_digest,
+        requirement_digest=recommendation.requirement_digest,
+        candidates=_trace_candidates(recommendation, by_coordinate),
+        admitted=recommendation.admitted,
+        escalated=recommendation.escalated,
+        refused=recommendation.refused,
+    )
+    return recommendation, trace
+
+
+def _verify_selected_build(
+    snapshot: CapturedBuildIndexSnapshot,
+    *,
+    selected_facts_sha256: str | None,
+    build_root: Path,
+) -> BuildSelectionTrace:
+    if selected_facts_sha256 is None:
+        return BuildSelectionTrace(None, "not_selected", None, None)
+    indexed = next(
+        (entry for entry in snapshot.entries if entry.facts_sha256 == selected_facts_sha256),
+        None,
+    )
+    locations = tuple(
+        item.relative_path
+        for item in snapshot.locators.locators
+        if item.facts_sha256 == selected_facts_sha256
+    )
+    if indexed is None or len(locations) != 1:
+        return BuildSelectionTrace(selected_facts_sha256, "rejected", "build_locator_invalid", None)
+    try:
+        with open_verified_snapshot(build_root / locations[0]) as verified_snapshot:
+            observed = _entry_from_verified_snapshot(verified_snapshot)
+            verified_snapshot.validate()
+    except (BuildError, LocalSearchContractError, OSError, TypeError, ValueError):
+        return BuildSelectionTrace(
+            selected_facts_sha256, "rejected", "build_verification_failed", None
+        )
+    expected_identities = (
+        indexed.facts_sha256,
+        indexed.candidate_sha256,
+        indexed.table_sha256,
+    )
+    observed_identities = (
+        observed.facts_sha256,
+        observed.candidate_sha256,
+        observed.table_sha256,
+    )
+    if observed_identities != expected_identities:
+        return BuildSelectionTrace(
+            selected_facts_sha256, "rejected", "build_identity_mismatch", None
+        )
+    evidence = VerifiedBuildEvidence(*observed_identities)
+    return BuildSelectionTrace(selected_facts_sha256, "verified", None, evidence)
+
+
+def _entry_from_verified_snapshot(snapshot: VerifiedSnapshot) -> BuildIndexEntry:
+    """Re-derive index facts from the sole retained exact-Build verification."""
+
+    verified = snapshot.verified
+    inspection = snapshot.inspection()
+    profile_raw = snapshot.member_bytes("evidence/profile.json")
+    profile = _object(profile_raw)
+    lineage = _object(snapshot.member_bytes("evidence/lineage.json"))
+    source_values = _array(snapshot.member_bytes("evidence/sources.json"))
+    requirements_raw = _optional_member(snapshot, "requirements.json")
+    requirements = None if requirements_raw is None else _object(requirements_raw)
+
+    columns = tuple(profile["columns"])
+    types = profile["types"]
+    null_counts = profile["null_counts"]
+    sources = []
+    for value in source_values:
+        rights = value["rights"]
+        sources.append(
+            BuildSourceFacts(
+                source_id=value["source_id"],
+                content_sha256=value["sha256"],
+                rights_status=rights["status"],
+                rights_evidence_sha256=canonical_sha256(rights),
+            )
+        )
+    return BuildIndexEntry(
+        question=inspection.question,
+        question_sha256=sha256_bytes(inspection.question.encode("utf-8")),
+        requirements_sha256=(
+            verified.manifest["plan_sha256"]
+            if requirements_raw is None
+            else sha256_bytes(requirements_raw)
+        ),
+        grain=inspection.grain,
+        time_coverage=_time_coverage(requirements),
+        fields=tuple(BuildField(name, str(types[name])) for name in columns),
+        sources=tuple(sorted(sources, key=lambda item: item.source_id)),
+        profile=SealedProfileFactsV1(
+            evidence_sha256=sha256_bytes(profile_raw),
+            row_count=profile["row_count"],
+            columns=columns,
+            logical_types=tuple(str(types[name]) for name in columns),
+            null_counts=tuple(null_counts[name] for name in columns),
+        ),
+        recipe_lineage=_recipe_lineage(snapshot, verified.manifest_version),
+        candidate_sha256=verified.candidate_digest,
+        table_sha256=verified.table_sha256,
+        validation_policy_sha256=verified.validation_policy_digest,
+        lineage_sha256=canonical_sha256(lineage),
+    )
+
+
+def _optional_member(snapshot: VerifiedSnapshot, path: str) -> bytes | None:
+    paths = {
+        member.get("path")
+        for member in snapshot.verified.manifest.get("members", ())
+        if isinstance(member, dict)
+    }
+    return snapshot.member_bytes(path) if path in paths else None
+
+
+def _recipe_lineage(snapshot: VerifiedSnapshot, manifest_version: str) -> BuildRecipeLineage | None:
+    if manifest_version != RECIPE_MANIFEST_VERSION:
+        return None
+    recipe = _object(snapshot.member_bytes("recipe.json"))
+    execution = _object(snapshot.member_bytes("recipe-execution.json"))
+    return BuildRecipeLineage(
+        recipe_id=recipe["recipe_id"],
+        recipe_version=recipe["recipe_version"],
+        recipe_sha256=canonical_sha256(recipe),
+        predecessor_candidate_sha256=execution["predecessor_candidate_digest"],
+    )
+
+
+def _time_coverage(requirements: dict[str, Any] | None) -> BuildTimeCoverage | None:
+    if requirements is None:
+        return None
+    value = requirements["time_range"]
+    return BuildTimeCoverage(value["start_inclusive"][:10], value["end_exclusive"][:10])
+
+
+def _object(raw: bytes) -> dict[str, Any]:
+    value = json.loads(raw)
+    if not isinstance(value, dict):
+        raise ValueError("verified member must contain an object")
+    return value
+
+
+def _array(raw: bytes) -> list[Any]:
+    value = json.loads(raw)
+    if not isinstance(value, list):
+        raise ValueError("verified member must contain an array")
+    return value
+
+
+def _recommendation(selection, *, public_recommendation, public_snapshot):
+    if selection.verified is not None:
+        return {"kind": "reuse_build", **selection.verified.to_dict()}
+    if not public_recommendation.admitted:
+        return {"kind": "no_match"}
+    coordinate = public_recommendation.admitted[0]
+    entry = next(item for item in public_snapshot.lexical.entries if item.coordinate == coordinate)
+    return {
+        "kind": "use_source",
+        "entry_coordinate": entry.coordinate,
+        "entry_digest": entry.digest,
+        "facts_digest": entry.facts_digest,
+        "publisher": entry.publisher,
+        "title": entry.title,
+        "data_formats": list(entry.data_formats),
+        "access_kind": entry.access_kind,
+    }
+
+
+__all__ = [
+    "LOCAL_SEARCH_PAYLOAD_VERSION",
+    "LOCAL_SEARCH_TRACE_VERSION",
+    "BuildSelectionTrace",
+    "CapturedLocalSearch",
+    "CombinedLocalSearchTrace",
+    "VerifiedBuildEvidence",
+    "capture_local_search",
+]