mostlyright-data 0.9.0__py3-none-any.whl

mostlyright/data_harness/local_search/retrieval.py

@@ -0,0 +1,700 @@
+"""Fact-gated retrieval over immutable private Build-index entries.
+
+The filter grammar in this module is closed data: one AND-only object containing named filters.
+There is no generic operator, expression, regular-expression, SQL, or Python-evaluation seam.
+Every predicate reads only :class:`BuildIndexEntry` facts; missing optional facts fail the filter
+that needs them.  Ranking is added separately below so similarity can order an already eligible
+set but can never create membership in it.
+"""
+
+from __future__ import annotations
+
+import re
+from collections.abc import Mapping, Sequence
+from dataclasses import dataclass
+from typing import Any, ClassVar
+
+from mostlyright.data_harness.canonical import canonical_json_bytes, canonical_sha256, sha256_bytes
+from mostlyright.data_harness.local_search.contracts import (
+    _RIGHTS_STATUSES,
+    BuildField,
+    BuildIndexEntry,
+    BuildTimeCoverage,
+    LocalSearchContractError,
+)
+
+BUILD_FILTER_VERSION = "harness-private-build-filter.v1"
+MAX_FILTER_ITEMS = 64
+MAX_FILTER_TEXT = 512
+MAX_QUERY_CHARS = 4_096
+MAX_RETRIEVAL_LIMIT = 100
+
+_DIGEST = re.compile(r"^[0-9a-f]{64}$")
+_IDENTIFIER = re.compile(r"^[A-Za-z0-9][A-Za-z0-9._-]{0,255}$")
+_FILTER_KEYS = frozenset(
+    {
+        "schema_version",
+        "grain",
+        "time_overlap",
+        "required_fields",
+        "sources",
+        "rights_statuses",
+        "recipe",
+        "exact_digest",
+    }
+)
+_DIGEST_KINDS = frozenset(
+    {"facts", "candidate", "dataset", "requirements", "validation_policy", "lineage"}
+)
+_FILTER_ORDER = (
+    "grain",
+    "time_overlap",
+    "required_fields",
+    "sources",
+    "rights_statuses",
+    "recipe",
+    "exact_digest",
+)
+
+
+class _CanonicalFilter:
+    schema_version: ClassVar[str] | str
+
+    def to_dict(self) -> dict[str, Any]:
+        raise NotImplementedError
+
+    @property
+    def canonical_bytes(self) -> bytes:
+        return canonical_json_bytes(self.to_dict())
+
+    @property
+    def digest(self) -> str:
+        return canonical_sha256(self.to_dict())
+
+
+@dataclass(frozen=True)
+class SourceIdentityFilter(_CanonicalFilter):
+    """One exact source identity required to appear in the sealed Build facts."""
+
+    source_id: str
+    content_sha256: str
+
+    def __post_init__(self) -> None:
+        _identifier(self.source_id, "filters.sources.source_id")
+        _digest(self.content_sha256, "filters.sources.content_sha256")
+
+    def to_dict(self) -> dict[str, str]:
+        return {"source_id": self.source_id, "content_sha256": self.content_sha256}
+
+
+@dataclass(frozen=True)
+class RecipeIdentityFilter(_CanonicalFilter):
+    """The complete immutable recipe identity a reusable Build must carry."""
+
+    recipe_id: str
+    recipe_version: int
+    recipe_sha256: str
+
+    def __post_init__(self) -> None:
+        _identifier(self.recipe_id, "filters.recipe.recipe_id")
+        _integer(self.recipe_version, "filters.recipe.recipe_version", minimum=1)
+        _digest(self.recipe_sha256, "filters.recipe.recipe_sha256")
+
+    def to_dict(self) -> dict[str, Any]:
+        return {
+            "recipe_id": self.recipe_id,
+            "recipe_version": self.recipe_version,
+            "recipe_sha256": self.recipe_sha256,
+        }
+
+
+@dataclass(frozen=True)
+class ExactDigestFilter(_CanonicalFilter):
+    """One explicitly named immutable Build identity and its exact digest."""
+
+    kind: str
+    sha256: str
+
+    def __post_init__(self) -> None:
+        _choice(self.kind, _DIGEST_KINDS, "filters.exact_digest.kind")
+        _digest(self.sha256, "filters.exact_digest.sha256")
+
+    def to_dict(self) -> dict[str, str]:
+        return {"kind": self.kind, "sha256": self.sha256}
+
+
+@dataclass(frozen=True)
+class BuildFilters(_CanonicalFilter):
+    """The complete AND-only private Build filter grammar."""
+
+    grain: tuple[str, ...] | None = None
+    time_overlap: BuildTimeCoverage | None = None
+    required_fields: tuple[BuildField, ...] = ()
+    sources: tuple[SourceIdentityFilter, ...] = ()
+    rights_statuses: tuple[str, ...] = ()
+    recipe: RecipeIdentityFilter | None = None
+    exact_digest: ExactDigestFilter | None = None
+    schema_version: str = BUILD_FILTER_VERSION
+
+    def __post_init__(self) -> None:
+        if self.schema_version != BUILD_FILTER_VERSION:
+            raise LocalSearchContractError(
+                "LOCAL_SEARCH_FILTER_VERSION",
+                "filters.schema_version",
+                f"must equal {BUILD_FILTER_VERSION!r}",
+            )
+        if self.grain is not None:
+            _text_tuple(self.grain, "filters.grain", nonempty=True, ordered=False)
+        _optional_type(self.time_overlap, BuildTimeCoverage, "filters.time_overlap")
+        _typed_tuple(self.required_fields, BuildField, "filters.required_fields")
+        _typed_tuple(self.sources, SourceIdentityFilter, "filters.sources")
+        _text_tuple(self.rights_statuses, "filters.rights_statuses", nonempty=False, ordered=True)
+        for index, status in enumerate(self.rights_statuses):
+            _choice(status, _RIGHTS_STATUSES, f"filters.rights_statuses[{index}]")
+        _optional_type(self.recipe, RecipeIdentityFilter, "filters.recipe")
+        _optional_type(self.exact_digest, ExactDigestFilter, "filters.exact_digest")
+        _unique(tuple(item.name for item in self.required_fields), "filters.required_fields")
+        _unique(tuple(item.source_id for item in self.sources), "filters.sources")
+        _sorted_unique(
+            tuple((item.source_id, item.content_sha256) for item in self.sources),
+            "filters.sources",
+        )
+
+    def to_dict(self) -> dict[str, Any]:
+        payload: dict[str, Any] = {"schema_version": self.schema_version}
+        if self.grain is not None:
+            payload["grain"] = list(self.grain)
+        if self.time_overlap is not None:
+            payload["time_overlap"] = self.time_overlap.to_dict()
+        if self.required_fields:
+            payload["required_fields"] = [item.to_dict() for item in self.required_fields]
+        if self.sources:
+            payload["sources"] = [item.to_dict() for item in self.sources]
+        if self.rights_statuses:
+            payload["rights_statuses"] = list(self.rights_statuses)
+        if self.recipe is not None:
+            payload["recipe"] = self.recipe.to_dict()
+        if self.exact_digest is not None:
+            payload["exact_digest"] = self.exact_digest.to_dict()
+        return payload
+
+
+@dataclass(frozen=True)
+class BuildFilterCheck:
+    """One named fact predicate's bounded result."""
+
+    filter_name: str
+    outcome: str
+
+    def __post_init__(self) -> None:
+        _choice(self.filter_name, frozenset(_FILTER_ORDER), "filter_check.filter_name")
+        _choice(self.outcome, frozenset({"pass", "fail"}), "filter_check.outcome")
+
+    def to_dict(self) -> dict[str, str]:
+        return {"filter_name": self.filter_name, "outcome": self.outcome}
+
+
+@dataclass(frozen=True)
+class BuildFilterVerdict:
+    """Stable immutable identities plus the complete applied-filter disposition."""
+
+    facts_sha256: str
+    candidate_sha256: str
+    disposition: str
+    checks: tuple[BuildFilterCheck, ...]
+
+    def __post_init__(self) -> None:
+        _digest(self.facts_sha256, "filter_verdict.facts_sha256")
+        _digest(self.candidate_sha256, "filter_verdict.candidate_sha256")
+        _choice(
+            self.disposition,
+            frozenset({"eligible", "ineligible"}),
+            "filter_verdict.disposition",
+        )
+        _typed_tuple(self.checks, BuildFilterCheck, "filter_verdict.checks")
+        names = tuple(item.filter_name for item in self.checks)
+        expected = tuple(name for name in _FILTER_ORDER if name in names)
+        if names != expected or len(set(names)) != len(names):
+            raise LocalSearchContractError(
+                "LOCAL_SEARCH_FILTER_CHECKS",
+                "filter_verdict.checks",
+                "must be unique and in the closed filter order",
+            )
+        expected_disposition = (
+            "ineligible" if any(item.outcome == "fail" for item in self.checks) else "eligible"
+        )
+        if self.disposition != expected_disposition:
+            raise LocalSearchContractError(
+                "LOCAL_SEARCH_FILTER_DISPOSITION",
+                "filter_verdict.disposition",
+                "must be derived from the complete filter checks",
+            )
+
+    def to_dict(self) -> dict[str, Any]:
+        return {
+            "facts_sha256": self.facts_sha256,
+            "candidate_sha256": self.candidate_sha256,
+            "disposition": self.disposition,
+            "checks": [item.to_dict() for item in self.checks],
+        }
+
+
+@dataclass(frozen=True)
+class BuildRetrieval:
+    """Score-free result of fact gating followed by deterministic ordering."""
+
+    question_sha256: str
+    filters_sha256: str
+    backend_coordinate: str
+    filter_verdicts: tuple[BuildFilterVerdict, ...]
+    ordered_facts_sha256: tuple[str, ...]
+
+    def __post_init__(self) -> None:
+        _digest(self.question_sha256, "retrieval.question_sha256")
+        _digest(self.filters_sha256, "retrieval.filters_sha256")
+        _backend_coordinate(self.backend_coordinate)
+        _typed_tuple(
+            self.filter_verdicts,
+            BuildFilterVerdict,
+            "retrieval.filter_verdicts",
+            maximum=100_000,
+        )
+        verdict_ids = tuple(item.facts_sha256 for item in self.filter_verdicts)
+        if verdict_ids != tuple(sorted(verdict_ids)) or len(set(verdict_ids)) != len(verdict_ids):
+            raise LocalSearchContractError(
+                "LOCAL_SEARCH_RETRIEVAL_ORDER",
+                "retrieval.filter_verdicts",
+                "must carry unique facts identities in exact sorted order",
+            )
+        if not isinstance(self.ordered_facts_sha256, tuple):
+            raise LocalSearchContractError(
+                "LOCAL_SEARCH_TYPE",
+                "retrieval.ordered_facts_sha256",
+                "must be an immutable tuple",
+            )
+        if len(self.ordered_facts_sha256) > MAX_RETRIEVAL_LIMIT:
+            raise LocalSearchContractError(
+                "LOCAL_SEARCH_RETRIEVAL_LIMIT",
+                "retrieval.ordered_facts_sha256",
+                f"may contain at most {MAX_RETRIEVAL_LIMIT} identities",
+            )
+        for index, digest in enumerate(self.ordered_facts_sha256):
+            _digest(digest, f"retrieval.ordered_facts_sha256[{index}]")
+        if len(set(self.ordered_facts_sha256)) != len(self.ordered_facts_sha256):
+            raise LocalSearchContractError(
+                "LOCAL_SEARCH_DUPLICATE",
+                "retrieval.ordered_facts_sha256",
+                "facts identities must be unique",
+            )
+        eligible = {
+            item.facts_sha256 for item in self.filter_verdicts if item.disposition == "eligible"
+        }
+        if not set(self.ordered_facts_sha256) <= eligible:
+            raise LocalSearchContractError(
+                "LOCAL_SEARCH_RETRIEVAL_ELIGIBILITY",
+                "retrieval.ordered_facts_sha256",
+                "may contain only facts-eligible identities",
+            )
+
+    def to_dict(self) -> dict[str, Any]:
+        return {
+            "question_sha256": self.question_sha256,
+            "filters_sha256": self.filters_sha256,
+            "backend_coordinate": self.backend_coordinate,
+            "filter_verdicts": [item.to_dict() for item in self.filter_verdicts],
+            "ordered_facts_sha256": list(self.ordered_facts_sha256),
+        }
+
+
+def parse_build_filters(raw: Any) -> BuildFilters:
+    """Parse exactly the versioned closed grammar; all filters combine with AND."""
+
+    payload = _mapping(raw, "filters")
+    unknown = sorted(set(payload) - _FILTER_KEYS)
+    if unknown:
+        raise LocalSearchContractError(
+            "LOCAL_SEARCH_FILTER_FIELDS",
+            "filters",
+            f"contains unknown fields: {unknown}",
+        )
+    if "schema_version" not in payload:
+        raise LocalSearchContractError(
+            "LOCAL_SEARCH_FILTER_FIELDS", "filters", "must name schema_version"
+        )
+    grain = None
+    if "grain" in payload:
+        grain = tuple(_array(payload["grain"], "filters.grain"))
+    time_overlap = None
+    if "time_overlap" in payload:
+        value = _mapping(payload["time_overlap"], "filters.time_overlap")
+        _exact(value, {"start_inclusive", "end_exclusive"}, "filters.time_overlap")
+        time_overlap = BuildTimeCoverage(value["start_inclusive"], value["end_exclusive"])
+    fields = tuple(
+        _field_filter(item, f"filters.required_fields[{index}]")
+        for index, item in enumerate(
+            _array(payload.get("required_fields", []), "filters.required_fields")
+        )
+    )
+    sources = tuple(
+        _source_filter(item, f"filters.sources[{index}]")
+        for index, item in enumerate(_array(payload.get("sources", []), "filters.sources"))
+    )
+    rights_statuses = tuple(_array(payload.get("rights_statuses", []), "filters.rights_statuses"))
+    recipe = None
+    if "recipe" in payload:
+        value = _mapping(payload["recipe"], "filters.recipe")
+        _exact(value, {"recipe_id", "recipe_version", "recipe_sha256"}, "filters.recipe")
+        recipe = RecipeIdentityFilter(
+            value["recipe_id"], value["recipe_version"], value["recipe_sha256"]
+        )
+    exact_digest = None
+    if "exact_digest" in payload:
+        value = _mapping(payload["exact_digest"], "filters.exact_digest")
+        _exact(value, {"kind", "sha256"}, "filters.exact_digest")
+        exact_digest = ExactDigestFilter(value["kind"], value["sha256"])
+    return BuildFilters(
+        schema_version=payload["schema_version"],
+        grain=grain,
+        time_overlap=time_overlap,
+        required_fields=fields,
+        sources=sources,
+        rights_statuses=rights_statuses,
+        recipe=recipe,
+        exact_digest=exact_digest,
+    )
+
+
+def filter_build_entries(
+    entries: tuple[BuildIndexEntry, ...], *, filters: BuildFilters
+) -> tuple[BuildFilterVerdict, ...]:
+    """Evaluate every candidate from sealed facts and return identity-sorted verdicts."""
+
+    _typed_tuple(entries, BuildIndexEntry, "entries", maximum=100_000)
+    if not isinstance(filters, BuildFilters):
+        raise LocalSearchContractError(
+            "LOCAL_SEARCH_TYPE", "filters", "must be a BuildFilters contract"
+        )
+    if len({item.facts_sha256 for item in entries}) != len(entries):
+        raise LocalSearchContractError(
+            "LOCAL_SEARCH_DUPLICATE", "entries", "facts identities must be unique"
+        )
+    return tuple(_filter_one(entry, filters) for entry in sorted(entries, key=_entry_identity))
+
+
+def retrieve_build_candidates(
+    entries: tuple[BuildIndexEntry, ...],
+    *,
+    filters: BuildFilters,
+    question: str,
+    backend: Any,
+    limit: int,
+) -> BuildRetrieval:
+    """Gate on sealed facts, then order only the eligible immutable facts identities.
+
+    The arithmetic remains in this function and dies before return.  There is no threshold:
+    ``limit`` truncates the already eligible total order and cannot change a filter disposition.
+    Candidate text is encoded only after the fact gate passes, which also bounds neural work by
+    the number of eligible entries.
+    """
+
+    if not isinstance(question, str) or not 1 <= len(question) <= MAX_QUERY_CHARS:
+        raise LocalSearchContractError(
+            "LOCAL_SEARCH_QUERY_BOUNDS",
+            "question",
+            f"must contain 1 to {MAX_QUERY_CHARS} characters",
+        )
+    if type(limit) is not int or not 1 <= limit <= MAX_RETRIEVAL_LIMIT:
+        raise LocalSearchContractError(
+            "LOCAL_SEARCH_RETRIEVAL_LIMIT",
+            "limit",
+            f"must be an integer in [1, {MAX_RETRIEVAL_LIMIT}]",
+        )
+    descriptor = getattr(backend, "descriptor", None)
+    coordinate = getattr(descriptor, "coordinate", None)
+    dimensions = getattr(descriptor, "dimensions", None)
+    encode = getattr(backend, "encode", None)
+    _backend_coordinate(coordinate)
+    if type(dimensions) is not int or not 1 <= dimensions <= 4_096:
+        raise LocalSearchContractError(
+            "LOCAL_SEARCH_BACKEND",
+            "backend.descriptor.dimensions",
+            "must be an integer in [1, 4096]",
+        )
+    if not callable(encode):
+        raise LocalSearchContractError("LOCAL_SEARCH_BACKEND", "backend.encode", "must be callable")
+
+    verdicts = filter_build_entries(entries, filters=filters)
+    eligible_ids = {item.facts_sha256 for item in verdicts if item.disposition == "eligible"}
+    eligible_entries = tuple(
+        entry
+        for entry in sorted(entries, key=_entry_identity)
+        if entry.facts_sha256 in eligible_ids
+    )
+    ordered: list[tuple[int, str]] = []
+    if eligible_entries:
+        asked = _vector(encode(question), dimensions, "backend.query_vector")
+        for entry in eligible_entries:
+            candidate = _vector(
+                encode(entry.question),
+                dimensions,
+                f"backend.candidate_vector[{entry.facts_sha256}]",
+            )
+            private_similarity = sum(
+                left * right for left, right in zip(asked, candidate, strict=True)
+            )
+            ordered.append((-private_similarity, entry.facts_sha256))
+    ordered.sort()
+    return BuildRetrieval(
+        question_sha256=sha256_bytes(question.encode("utf-8")),
+        filters_sha256=filters.digest,
+        backend_coordinate=coordinate,
+        filter_verdicts=verdicts,
+        ordered_facts_sha256=tuple(identity for _private, identity in ordered[:limit]),
+    )
+
+
+def _filter_one(entry: BuildIndexEntry, filters: BuildFilters) -> BuildFilterVerdict:
+    checks: list[BuildFilterCheck] = []
+    if filters.grain is not None:
+        checks.append(BuildFilterCheck("grain", _outcome(entry.grain == filters.grain)))
+    if filters.time_overlap is not None:
+        coverage = entry.time_coverage
+        matches = coverage is not None and (
+            coverage.start_inclusive < filters.time_overlap.end_exclusive
+            and filters.time_overlap.start_inclusive < coverage.end_exclusive
+        )
+        checks.append(BuildFilterCheck("time_overlap", _outcome(matches)))
+    if filters.required_fields:
+        present = {(field.name, field.logical_type) for field in entry.fields}
+        required = {(field.name, field.logical_type) for field in filters.required_fields}
+        checks.append(BuildFilterCheck("required_fields", _outcome(required <= present)))
+    if filters.sources:
+        present = {(source.source_id, source.content_sha256) for source in entry.sources}
+        required = {(source.source_id, source.content_sha256) for source in filters.sources}
+        checks.append(BuildFilterCheck("sources", _outcome(required <= present)))
+    if filters.rights_statuses:
+        allowed = set(filters.rights_statuses)
+        checks.append(
+            BuildFilterCheck(
+                "rights_statuses",
+                _outcome(
+                    bool(entry.sources) and all(s.rights_status in allowed for s in entry.sources)
+                ),
+            )
+        )
+    if filters.recipe is not None:
+        lineage = entry.recipe_lineage
+        matches = lineage is not None and (
+            lineage.recipe_id == filters.recipe.recipe_id
+            and lineage.recipe_version == filters.recipe.recipe_version
+            and lineage.recipe_sha256 == filters.recipe.recipe_sha256
+        )
+        checks.append(BuildFilterCheck("recipe", _outcome(matches)))
+    if filters.exact_digest is not None:
+        observed = _entry_digest(entry, filters.exact_digest.kind)
+        checks.append(
+            BuildFilterCheck("exact_digest", _outcome(observed == filters.exact_digest.sha256))
+        )
+    disposition = "ineligible" if any(item.outcome == "fail" for item in checks) else "eligible"
+    return BuildFilterVerdict(
+        entry.facts_sha256, entry.candidate_sha256, disposition, tuple(checks)
+    )
+
+
+def _entry_digest(entry: BuildIndexEntry, kind: str) -> str:
+    return {
+        "facts": entry.facts_sha256,
+        "candidate": entry.candidate_sha256,
+        "dataset": entry.table_sha256,
+        "requirements": entry.requirements_sha256,
+        "validation_policy": entry.validation_policy_sha256,
+        "lineage": entry.lineage_sha256,
+    }[kind]
+
+
+def _entry_identity(entry: BuildIndexEntry) -> tuple[str, str]:
+    return entry.facts_sha256, entry.candidate_sha256
+
+
+def _field_filter(value: Any, path: str) -> BuildField:
+    payload = _mapping(value, path)
+    _exact(payload, {"name", "logical_type"}, path)
+    return BuildField(payload["name"], payload["logical_type"])
+
+
+def _source_filter(value: Any, path: str) -> SourceIdentityFilter:
+    payload = _mapping(value, path)
+    _exact(payload, {"source_id", "content_sha256"}, path)
+    return SourceIdentityFilter(payload["source_id"], payload["content_sha256"])
+
+
+def _mapping(value: Any, path: str) -> Mapping[str, Any]:
+    if not isinstance(value, Mapping) or any(not isinstance(key, str) for key in value):
+        raise LocalSearchContractError(
+            "LOCAL_SEARCH_FILTER_SHAPE", path, "must be an object with string keys"
+        )
+    return value
+
+
+def _array(value: Any, path: str) -> list[Any]:
+    if isinstance(value, (str, bytes)) or not isinstance(value, Sequence):
+        raise LocalSearchContractError("LOCAL_SEARCH_FILTER_SHAPE", path, "must be an array")
+    if len(value) > MAX_FILTER_ITEMS:
+        raise LocalSearchContractError(
+            "LOCAL_SEARCH_FILTER_BOUNDS",
+            path,
+            f"may contain at most {MAX_FILTER_ITEMS} items",
+        )
+    return list(value)
+
+
+def _exact(value: Mapping[str, Any], expected: set[str], path: str) -> None:
+    if set(value) != expected:
+        raise LocalSearchContractError(
+            "LOCAL_SEARCH_FILTER_FIELDS",
+            path,
+            f"must contain exactly {sorted(expected)}",
+        )
+
+
+def _identifier(value: Any, path: str) -> None:
+    if (
+        not isinstance(value, str)
+        or len(value) > MAX_FILTER_TEXT
+        or _IDENTIFIER.fullmatch(value) is None
+    ):
+        raise LocalSearchContractError(
+            "LOCAL_SEARCH_FILTER_TEXT", path, "must be a bounded identifier"
+        )
+
+
+def _digest(value: Any, path: str) -> None:
+    if not isinstance(value, str) or _DIGEST.fullmatch(value) is None:
+        raise LocalSearchContractError(
+            "LOCAL_SEARCH_FILTER_DIGEST", path, "must be a lowercase SHA-256"
+        )
+
+
+def _integer(value: Any, path: str, *, minimum: int) -> None:
+    if type(value) is not int or not minimum <= value <= (1 << 53) - 1:
+        raise LocalSearchContractError(
+            "LOCAL_SEARCH_FILTER_INTEGER", path, f"must be an integer of at least {minimum}"
+        )
+
+
+def _choice(value: Any, choices: frozenset[str], path: str) -> None:
+    if not isinstance(value, str) or value not in choices:
+        raise LocalSearchContractError(
+            "LOCAL_SEARCH_FILTER_CHOICE", path, f"must be one of {sorted(choices)}"
+        )
+
+
+def _optional_type(value: Any, expected: type[Any], path: str) -> None:
+    if value is not None and not isinstance(value, expected):
+        raise LocalSearchContractError(
+            "LOCAL_SEARCH_TYPE", path, f"must be {expected.__name__} or null"
+        )
+
+
+def _typed_tuple(
+    value: Any,
+    expected: type[Any],
+    path: str,
+    maximum: int = MAX_FILTER_ITEMS,
+) -> None:
+    if not isinstance(value, tuple):
+        raise LocalSearchContractError("LOCAL_SEARCH_TYPE", path, "must be an immutable tuple")
+    if len(value) > maximum:
+        raise LocalSearchContractError(
+            "LOCAL_SEARCH_FILTER_BOUNDS", path, f"may contain at most {maximum} items"
+        )
+    if any(not isinstance(item, expected) for item in value):
+        raise LocalSearchContractError(
+            "LOCAL_SEARCH_TYPE", path, f"items must be {expected.__name__}"
+        )
+
+
+def _text_tuple(value: Any, path: str, *, nonempty: bool, ordered: bool) -> None:
+    if not isinstance(value, tuple):
+        raise LocalSearchContractError("LOCAL_SEARCH_TYPE", path, "must be an immutable tuple")
+    if (nonempty and not value) or len(value) > MAX_FILTER_ITEMS:
+        raise LocalSearchContractError(
+            "LOCAL_SEARCH_FILTER_BOUNDS", path, f"must contain 1 to {MAX_FILTER_ITEMS} items"
+        )
+    for index, item in enumerate(value):
+        if not isinstance(item, str) or not item or len(item) > MAX_FILTER_TEXT:
+            raise LocalSearchContractError(
+                "LOCAL_SEARCH_FILTER_TEXT",
+                f"{path}[{index}]",
+                f"must be non-empty text of at most {MAX_FILTER_TEXT} characters",
+            )
+    _unique(value, path)
+    if ordered and tuple(sorted(value)) != value:
+        raise LocalSearchContractError(
+            "LOCAL_SEARCH_FILTER_ORDER", path, "must be sorted in exact text order"
+        )
+
+
+def _unique(value: tuple[Any, ...], path: str) -> None:
+    if len(set(value)) != len(value):
+        raise LocalSearchContractError(
+            "LOCAL_SEARCH_FILTER_DUPLICATE", path, "items must be unique"
+        )
+
+
+def _sorted_unique(value: tuple[Any, ...], path: str) -> None:
+    _unique(value, path)
+    if tuple(sorted(value)) != value:
+        raise LocalSearchContractError(
+            "LOCAL_SEARCH_FILTER_ORDER", path, "must be sorted in exact identity order"
+        )
+
+
+def _outcome(value: bool) -> str:
+    return "pass" if value else "fail"
+
+
+def _backend_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_BACKEND",
+            "backend.descriptor.coordinate",
+            "must be the bounded exact one-line backend coordinate",
+        )
+
+
+def _vector(value: Any, dimensions: int, path: str) -> tuple[int, ...]:
+    if (
+        not isinstance(value, tuple)
+        or len(value) != dimensions
+        or any(type(item) is not int or not -(1 << 31) <= item <= (1 << 31) - 1 for item in value)
+    ):
+        raise LocalSearchContractError(
+            "LOCAL_SEARCH_VECTOR",
+            path,
+            "must be an immutable signed-int32 vector matching the backend dimensions",
+        )
+    return value
+
+
+__all__ = [
+    "BUILD_FILTER_VERSION",
+    "MAX_FILTER_ITEMS",
+    "MAX_QUERY_CHARS",
+    "MAX_RETRIEVAL_LIMIT",
+    "BuildFilterCheck",
+    "BuildFilterVerdict",
+    "BuildFilters",
+    "BuildRetrieval",
+    "ExactDigestFilter",
+    "RecipeIdentityFilter",
+    "SourceIdentityFilter",
+    "filter_build_entries",
+    "parse_build_filters",
+    "retrieve_build_candidates",
+]