mostlyright-data 0.9.0__py3-none-any.whl

mostlyright/data_harness/local_search/query_trace.py

@@ -0,0 +1,266 @@
+"""Canonical immutable-fact evidence for one private Build-index query."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Any
+
+from mostlyright.data_harness.canonical import canonical_sha256
+from mostlyright.data_harness.local_search.contracts import (
+    BuildIndexEntry,
+    LocalSearchContractError,
+)
+from mostlyright.data_harness.local_search.retrieval import (
+    MAX_RETRIEVAL_LIMIT,
+    BuildRetrieval,
+)
+
+PRIVATE_BUILD_QUERY_TRACE_VERSION = "harness-private-build-query-trace.v1"
+
+
+@dataclass(frozen=True)
+class TracedBuildDisposition:
+    """Immutable identities and fact-filter outcome for one considered Build."""
+
+    facts_sha256: str
+    candidate_sha256: str
+    table_sha256: str
+    disposition: str
+    failed_filters: tuple[str, ...]
+
+    def __post_init__(self) -> None:
+        for name in ("facts_sha256", "candidate_sha256", "table_sha256"):
+            _digest(getattr(self, name), f"trace.candidates.{name}")
+        if self.disposition not in {"eligible", "ineligible"}:
+            raise LocalSearchContractError(
+                "LOCAL_SEARCH_TRACE_DISPOSITION",
+                "trace.candidates.disposition",
+                "must be eligible or ineligible",
+            )
+        _strings(self.failed_filters, "trace.candidates.failed_filters", maximum=7)
+        if tuple(sorted(self.failed_filters)) != self.failed_filters:
+            raise LocalSearchContractError(
+                "LOCAL_SEARCH_TRACE_ORDER",
+                "trace.candidates.failed_filters",
+                "must be sorted in exact text order",
+            )
+        expected = "ineligible" if self.failed_filters else "eligible"
+        if self.disposition != expected:
+            raise LocalSearchContractError(
+                "LOCAL_SEARCH_TRACE_DISPOSITION",
+                "trace.candidates.disposition",
+                "must be derived from failed_filters",
+            )
+
+    def to_dict(self) -> dict[str, Any]:
+        return {
+            "facts_sha256": self.facts_sha256,
+            "candidate_sha256": self.candidate_sha256,
+            "table_sha256": self.table_sha256,
+            "disposition": self.disposition,
+            "failed_filters": list(self.failed_filters),
+        }
+
+
+@dataclass(frozen=True)
+class PrivateBuildQueryTrace:
+    """Reproducible query evidence made solely from immutable identities."""
+
+    private_index_manifest_sha256: str
+    backend_coordinate: str
+    question_sha256: str
+    filters_sha256: str
+    candidates: tuple[TracedBuildDisposition, ...]
+    ordered_candidates: tuple[str, ...]
+    selected_facts_sha256: str | None
+    schema_version: str = PRIVATE_BUILD_QUERY_TRACE_VERSION
+
+    def __post_init__(self) -> None:
+        if self.schema_version != PRIVATE_BUILD_QUERY_TRACE_VERSION:
+            raise LocalSearchContractError(
+                "LOCAL_SEARCH_TRACE_VERSION",
+                "trace.schema_version",
+                f"must equal {PRIVATE_BUILD_QUERY_TRACE_VERSION!r}",
+            )
+        for name in (
+            "private_index_manifest_sha256",
+            "question_sha256",
+            "filters_sha256",
+        ):
+            _digest(getattr(self, name), f"trace.{name}")
+        _coordinate(self.backend_coordinate)
+        if not isinstance(self.candidates, tuple) or any(
+            not isinstance(item, TracedBuildDisposition) for item in self.candidates
+        ):
+            raise LocalSearchContractError(
+                "LOCAL_SEARCH_TRACE_TYPE",
+                "trace.candidates",
+                "must be an immutable tuple of traced Build dispositions",
+            )
+        candidate_ids = tuple(item.facts_sha256 for item in self.candidates)
+        if candidate_ids != tuple(sorted(candidate_ids)) or len(set(candidate_ids)) != len(
+            candidate_ids
+        ):
+            raise LocalSearchContractError(
+                "LOCAL_SEARCH_TRACE_ORDER",
+                "trace.candidates",
+                "must have unique facts identities in exact sorted order",
+            )
+        _digests(
+            self.ordered_candidates,
+            "trace.ordered_candidates",
+            maximum=MAX_RETRIEVAL_LIMIT,
+        )
+        if len(set(self.ordered_candidates)) != len(self.ordered_candidates):
+            raise LocalSearchContractError(
+                "LOCAL_SEARCH_TRACE_DUPLICATE",
+                "trace.ordered_candidates",
+                "facts identities must be unique",
+            )
+        eligible = {item.facts_sha256 for item in self.candidates if item.disposition == "eligible"}
+        if not set(self.ordered_candidates) <= eligible:
+            raise LocalSearchContractError(
+                "LOCAL_SEARCH_TRACE_ELIGIBILITY",
+                "trace.ordered_candidates",
+                "may contain only facts-eligible identities",
+            )
+        expected_selection = self.ordered_candidates[0] if self.ordered_candidates else None
+        if self.selected_facts_sha256 != expected_selection:
+            raise LocalSearchContractError(
+                "LOCAL_SEARCH_TRACE_SELECTION",
+                "trace.selected_facts_sha256",
+                "must be the first ordered identity or null for an empty order",
+            )
+
+    @property
+    def digest(self) -> str:
+        return canonical_sha256(self.to_dict())
+
+    def to_dict(self) -> dict[str, Any]:
+        return {
+            "schema_version": self.schema_version,
+            "private_index_manifest_sha256": self.private_index_manifest_sha256,
+            "backend_coordinate": self.backend_coordinate,
+            "question_sha256": self.question_sha256,
+            "filters_sha256": self.filters_sha256,
+            "candidates": [item.to_dict() for item in self.candidates],
+            "ordered_candidates": list(self.ordered_candidates),
+            "selected_facts_sha256": self.selected_facts_sha256,
+        }
+
+
+def build_private_query_trace(
+    *,
+    private_index_manifest_sha256: str,
+    entries: tuple[BuildIndexEntry, ...],
+    retrieval: BuildRetrieval,
+) -> PrivateBuildQueryTrace:
+    """Bind one private retrieval result to its index and complete fact dispositions."""
+
+    _digest(private_index_manifest_sha256, "private_index_manifest_sha256")
+    if not isinstance(entries, tuple) or any(
+        not isinstance(item, BuildIndexEntry) for item in entries
+    ):
+        raise LocalSearchContractError(
+            "LOCAL_SEARCH_TRACE_TYPE", "entries", "must be an immutable tuple of Build facts"
+        )
+    if not isinstance(retrieval, BuildRetrieval):
+        raise LocalSearchContractError(
+            "LOCAL_SEARCH_TRACE_TYPE", "retrieval", "must be a BuildRetrieval"
+        )
+    by_identity = {entry.facts_sha256: entry for entry in entries}
+    if len(by_identity) != len(entries):
+        raise LocalSearchContractError(
+            "LOCAL_SEARCH_TRACE_DUPLICATE", "entries", "facts identities must be unique"
+        )
+    verdict_ids = {item.facts_sha256 for item in retrieval.filter_verdicts}
+    if verdict_ids != set(by_identity):
+        raise LocalSearchContractError(
+            "LOCAL_SEARCH_TRACE_BINDING",
+            "retrieval.filter_verdicts",
+            "must cover exactly the supplied immutable Build facts",
+        )
+    for verdict in retrieval.filter_verdicts:
+        entry = by_identity[verdict.facts_sha256]
+        if verdict.candidate_sha256 != entry.candidate_sha256:
+            raise LocalSearchContractError(
+                "LOCAL_SEARCH_TRACE_BINDING",
+                "retrieval.filter_verdicts",
+                "candidate identities must match the supplied immutable Build facts",
+            )
+    candidates = tuple(
+        TracedBuildDisposition(
+            facts_sha256=verdict.facts_sha256,
+            candidate_sha256=by_identity[verdict.facts_sha256].candidate_sha256,
+            table_sha256=by_identity[verdict.facts_sha256].table_sha256,
+            disposition=verdict.disposition,
+            failed_filters=tuple(
+                sorted(check.filter_name for check in verdict.checks if check.outcome == "fail")
+            ),
+        )
+        for verdict in retrieval.filter_verdicts
+    )
+    return PrivateBuildQueryTrace(
+        private_index_manifest_sha256=private_index_manifest_sha256,
+        backend_coordinate=retrieval.backend_coordinate,
+        question_sha256=retrieval.question_sha256,
+        filters_sha256=retrieval.filters_sha256,
+        candidates=candidates,
+        ordered_candidates=retrieval.ordered_facts_sha256,
+        selected_facts_sha256=(
+            retrieval.ordered_facts_sha256[0] if retrieval.ordered_facts_sha256 else None
+        ),
+    )
+
+
+def _digest(value: Any, path: str) -> None:
+    if (
+        not isinstance(value, str)
+        or len(value) != 64
+        or any(character not in "0123456789abcdef" for character in value)
+    ):
+        raise LocalSearchContractError(
+            "LOCAL_SEARCH_TRACE_DIGEST", path, "must be a lowercase SHA-256"
+        )
+
+
+def _digests(value: Any, path: str, *, maximum: int) -> None:
+    if not isinstance(value, tuple) or len(value) > maximum:
+        raise LocalSearchContractError(
+            "LOCAL_SEARCH_TRACE_TYPE", path, f"must be a tuple of at most {maximum} digests"
+        )
+    for index, digest in enumerate(value):
+        _digest(digest, f"{path}[{index}]")
+
+
+def _strings(value: Any, path: str, *, maximum: int) -> None:
+    if not isinstance(value, tuple) or len(value) > maximum:
+        raise LocalSearchContractError(
+            "LOCAL_SEARCH_TRACE_TYPE", path, f"must be a tuple of at most {maximum} strings"
+        )
+    if any(not isinstance(item, str) or not item or len(item) > 64 for item in value):
+        raise LocalSearchContractError(
+            "LOCAL_SEARCH_TRACE_TYPE", path, "items must be bounded non-empty strings"
+        )
+
+
+def _coordinate(value: Any) -> None:
+    if (
+        not isinstance(value, str)
+        or not 1 <= len(value) <= 1_024
+        or "@" not in value
+        or any(ord(character) < 32 or character in "\x7f\u0085\u2028\u2029" for character in value)
+    ):
+        raise LocalSearchContractError(
+            "LOCAL_SEARCH_TRACE_BACKEND",
+            "trace.backend_coordinate",
+            "must be the bounded exact one-line backend coordinate",
+        )
+
+
+__all__ = [
+    "PRIVATE_BUILD_QUERY_TRACE_VERSION",
+    "PrivateBuildQueryTrace",
+    "TracedBuildDisposition",
+    "build_private_query_trace",
+]