mostlyright-data 0.9.0__py3-none-any.whl

mostlyright/data_harness/local_search/contracts.py

@@ -0,0 +1,920 @@
+"""Strict contracts for the private local Build index.
+
+Immutable Build facts, mutable filesystem locators, and sanitized discovery diagnostics are
+different documents by construction.  Nothing in this module imports the public Source Catalog:
+the two indexes share canonical JSON mechanics, not contracts or admission authority.
+"""
+
+from __future__ import annotations
+
+import re
+from collections.abc import Mapping, Sequence
+from dataclasses import dataclass
+from datetime import date
+from pathlib import PurePosixPath
+from typing import Any, ClassVar
+
+from mostlyright.data_harness.canonical import canonical_json_bytes, canonical_sha256, sha256_bytes
+
+BUILD_INDEX_ENTRY_VERSION = "harness-private-build-index-entry.v1"
+BUILD_LOCATOR_VERSION = "harness-private-build-locators.v1"
+BUILD_DIAGNOSTIC_VERSION = "harness-private-build-diagnostics.v1"
+BUILD_INDEX_MANIFEST_VERSION = "harness-private-build-index-manifest.v1"
+DATASET_PROFILE_VERSION = "dataset-profile.v1"
+
+MAX_TEXT = 16_384
+MAX_SHORT_TEXT = 512
+MAX_PATH = 1_024
+MAX_GRAIN = 64
+MAX_FIELDS = 1_024
+MAX_SOURCES = 256
+MAX_ENTRIES = 100_000
+MAX_LOCATORS = 200_000
+MAX_DIAGNOSTICS = 100_000
+MAX_SAFE_INTEGER = (1 << 53) - 1
+
+_SHA256 = re.compile(r"^[0-9a-f]{64}$")
+_IDENTIFIER = re.compile(r"^[A-Za-z0-9][A-Za-z0-9._-]{0,255}$")
+_LOGICAL_TYPES = frozenset({"string", "int64", "float64", "date"})
+_RIGHTS_STATUSES = frozenset(
+    {
+        "project_owned",
+        "public_domain",
+        "permissive_license",
+        "authorized_internal",
+        "user_authorized",
+        "unknown",
+        "prohibited",
+    }
+)
+_DIAGNOSTIC_CODES = frozenset(
+    {
+        "BUILD_HARDLINK",
+        "BUILD_INVALID",
+        "BUILD_LIMIT",
+        "BUILD_RACE",
+        "BUILD_SPECIAL",
+        "BUILD_SYMLINK",
+        "BUILD_UNREADABLE",
+    }
+)
+
+
+class LocalSearchContractError(ValueError):
+    """Typed refusal for private index contracts and sealed snapshots."""
+
+    def __init__(self, code: str, path: str, detail: str) -> None:
+        self.code = code
+        self.path = path
+        self.detail = detail
+        super().__init__(f"{path}: {detail} [{code}]")
+
+
+class _CanonicalContract:
+    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 BuildField(_CanonicalContract):
+    """One output field in the sealed profile's exact column order."""
+
+    name: str
+    logical_type: str
+
+    def __post_init__(self) -> None:
+        _text(self.name, "field.name", maximum=MAX_SHORT_TEXT)
+        _choice(self.logical_type, _LOGICAL_TYPES, "field.logical_type")
+
+    def to_dict(self) -> dict[str, str]:
+        return {"name": self.name, "logical_type": self.logical_type}
+
+
+@dataclass(frozen=True)
+class BuildTimeCoverage(_CanonicalContract):
+    """Sealed requirement coverage; absent when the Build carries no such evidence."""
+
+    start_inclusive: str
+    end_exclusive: str
+
+    def __post_init__(self) -> None:
+        start = _iso_date(self.start_inclusive, "time_coverage.start_inclusive")
+        end = _iso_date(self.end_exclusive, "time_coverage.end_exclusive")
+        if start >= end:
+            raise LocalSearchContractError(
+                "LOCAL_SEARCH_TIME",
+                "time_coverage",
+                "start_inclusive must precede end_exclusive",
+            )
+
+    def to_dict(self) -> dict[str, str]:
+        return {
+            "start_inclusive": self.start_inclusive,
+            "end_exclusive": self.end_exclusive,
+        }
+
+
+@dataclass(frozen=True)
+class BuildSourceFacts(_CanonicalContract):
+    """Identity, exact content, and rights evidence for one sealed Build source."""
+
+    source_id: str
+    content_sha256: str
+    rights_status: str
+    rights_evidence_sha256: str
+
+    def __post_init__(self) -> None:
+        _identifier(self.source_id, "source.source_id")
+        _digest(self.content_sha256, "source.content_sha256")
+        _choice(self.rights_status, _RIGHTS_STATUSES, "source.rights_status")
+        _digest(self.rights_evidence_sha256, "source.rights_evidence_sha256")
+
+    def to_dict(self) -> dict[str, str]:
+        return {
+            "source_id": self.source_id,
+            "content_sha256": self.content_sha256,
+            "rights_status": self.rights_status,
+            "rights_evidence_sha256": self.rights_evidence_sha256,
+        }
+
+
+@dataclass(frozen=True)
+class BuildRecipeLineage(_CanonicalContract):
+    """Recipe lineage only when the sealed Build carries recipe evidence."""
+
+    recipe_id: str
+    recipe_version: int
+    recipe_sha256: str
+    predecessor_candidate_sha256: str | None
+
+    def __post_init__(self) -> None:
+        _identifier(self.recipe_id, "recipe_lineage.recipe_id")
+        _integer(
+            self.recipe_version,
+            "recipe_lineage.recipe_version",
+            minimum=1,
+            maximum=MAX_SAFE_INTEGER,
+        )
+        _digest(self.recipe_sha256, "recipe_lineage.recipe_sha256")
+        if self.predecessor_candidate_sha256 is not None:
+            _digest(
+                self.predecessor_candidate_sha256,
+                "recipe_lineage.predecessor_candidate_sha256",
+            )
+
+    def to_dict(self) -> dict[str, Any]:
+        return {
+            "recipe_id": self.recipe_id,
+            "recipe_version": self.recipe_version,
+            "recipe_sha256": self.recipe_sha256,
+            "predecessor_candidate_sha256": self.predecessor_candidate_sha256,
+        }
+
+
+@dataclass(frozen=True)
+class SealedProfileFactsV1(_CanonicalContract):
+    """The exact useful subset presently sealed by ``dataset-profile.v1``.
+
+    The profile member's digest is mandatory.  A later rich profile therefore adds a new
+    profile-facts contract instead of reinterpreting these v1 fields or rewriting the Build.
+    """
+
+    evidence_sha256: str
+    row_count: int
+    columns: tuple[str, ...]
+    logical_types: tuple[str, ...]
+    null_counts: tuple[int, ...]
+    profile_schema_version: str = DATASET_PROFILE_VERSION
+
+    def __post_init__(self) -> None:
+        if self.profile_schema_version != DATASET_PROFILE_VERSION:
+            raise LocalSearchContractError(
+                "LOCAL_SEARCH_PROFILE",
+                "profile.profile_schema_version",
+                f"must equal {DATASET_PROFILE_VERSION!r}",
+            )
+        _digest(self.evidence_sha256, "profile.evidence_sha256")
+        _integer(self.row_count, "profile.row_count", minimum=0, maximum=MAX_SAFE_INTEGER)
+        _texts(
+            self.columns,
+            "profile.columns",
+            maximum=MAX_FIELDS,
+            item_maximum=MAX_SHORT_TEXT,
+            nonempty=False,
+        )
+        _typed_choices(self.logical_types, _LOGICAL_TYPES, "profile.logical_types", MAX_FIELDS)
+        _integers(self.null_counts, "profile.null_counts", maximum=MAX_FIELDS)
+        if not (len(self.columns) == len(self.logical_types) == len(self.null_counts)):
+            raise LocalSearchContractError(
+                "LOCAL_SEARCH_PROFILE",
+                "profile",
+                "columns, logical_types, and null_counts must have equal lengths",
+            )
+        for index, count in enumerate(self.null_counts):
+            if count > self.row_count:
+                raise LocalSearchContractError(
+                    "LOCAL_SEARCH_PROFILE",
+                    f"profile.null_counts[{index}]",
+                    "cannot exceed row_count",
+                )
+
+    def to_dict(self) -> dict[str, Any]:
+        return {
+            "profile_schema_version": self.profile_schema_version,
+            "evidence_sha256": self.evidence_sha256,
+            "row_count": self.row_count,
+            "columns": list(self.columns),
+            "logical_types": list(self.logical_types),
+            "null_counts": list(self.null_counts),
+        }
+
+
+@dataclass(frozen=True)
+class BuildIndexEntry(_CanonicalContract):
+    """Immutable sealed facts about one locally retained Build.
+
+    There is intentionally no path, indexing timestamp, username, machine, attempt, row sample,
+    or Parquet payload field.  ``facts_sha256`` is solely the digest of this document.
+    """
+
+    question: str
+    question_sha256: str
+    requirements_sha256: str
+    grain: tuple[str, ...]
+    time_coverage: BuildTimeCoverage | None
+    fields: tuple[BuildField, ...]
+    sources: tuple[BuildSourceFacts, ...]
+    profile: SealedProfileFactsV1 | None
+    recipe_lineage: BuildRecipeLineage | None
+    candidate_sha256: str
+    table_sha256: str
+    validation_policy_sha256: str
+    lineage_sha256: str
+    schema_version: str = BUILD_INDEX_ENTRY_VERSION
+
+    def __post_init__(self) -> None:
+        if self.schema_version != BUILD_INDEX_ENTRY_VERSION:
+            raise LocalSearchContractError(
+                "LOCAL_SEARCH_VERSION",
+                "entry.schema_version",
+                f"must equal {BUILD_INDEX_ENTRY_VERSION!r}",
+            )
+        _text(self.question, "entry.question", maximum=MAX_TEXT)
+        _digest(self.question_sha256, "entry.question_sha256")
+        if self.question_sha256 != sha256_bytes(self.question.encode("utf-8")):
+            raise LocalSearchContractError(
+                "LOCAL_SEARCH_QUESTION_BINDING",
+                "entry.question_sha256",
+                "does not match the exact UTF-8 question",
+            )
+        _digest(self.requirements_sha256, "entry.requirements_sha256")
+        _texts(
+            self.grain,
+            "entry.grain",
+            maximum=MAX_GRAIN,
+            item_maximum=MAX_SHORT_TEXT,
+            nonempty=True,
+        )
+        _optional_type(self.time_coverage, BuildTimeCoverage, "entry.time_coverage")
+        _typed_tuple(self.fields, BuildField, "entry.fields", MAX_FIELDS, nonempty=True)
+        if len({item.name for item in self.fields}) != len(self.fields):
+            raise LocalSearchContractError(
+                "LOCAL_SEARCH_DUPLICATE", "entry.fields", "field names must be unique"
+            )
+        _typed_tuple(self.sources, BuildSourceFacts, "entry.sources", MAX_SOURCES, nonempty=True)
+        if len({item.source_id for item in self.sources}) != len(self.sources):
+            raise LocalSearchContractError(
+                "LOCAL_SEARCH_DUPLICATE", "entry.sources", "source ids must be unique"
+            )
+        _optional_type(self.profile, SealedProfileFactsV1, "entry.profile")
+        if self.profile is not None:
+            if self.profile.columns != tuple(field.name for field in self.fields):
+                raise LocalSearchContractError(
+                    "LOCAL_SEARCH_PROFILE",
+                    "entry.profile.columns",
+                    "must match fields in sealed order",
+                )
+            if self.profile.logical_types != tuple(field.logical_type for field in self.fields):
+                raise LocalSearchContractError(
+                    "LOCAL_SEARCH_PROFILE",
+                    "entry.profile.logical_types",
+                    "must match field logical types in sealed order",
+                )
+        _optional_type(self.recipe_lineage, BuildRecipeLineage, "entry.recipe_lineage")
+        for name in (
+            "candidate_sha256",
+            "table_sha256",
+            "validation_policy_sha256",
+            "lineage_sha256",
+        ):
+            _digest(getattr(self, name), f"entry.{name}")
+
+    @property
+    def facts_sha256(self) -> str:
+        return self.digest
+
+    def to_dict(self) -> dict[str, Any]:
+        return {
+            "schema_version": self.schema_version,
+            "question": self.question,
+            "question_sha256": self.question_sha256,
+            "requirements_sha256": self.requirements_sha256,
+            "grain": list(self.grain),
+            "time_coverage": None if self.time_coverage is None else self.time_coverage.to_dict(),
+            "fields": [item.to_dict() for item in self.fields],
+            "sources": [item.to_dict() for item in self.sources],
+            "profile": None if self.profile is None else self.profile.to_dict(),
+            "recipe_lineage": (
+                None if self.recipe_lineage is None else self.recipe_lineage.to_dict()
+            ),
+            "candidate_sha256": self.candidate_sha256,
+            "table_sha256": self.table_sha256,
+            "validation_policy_sha256": self.validation_policy_sha256,
+            "lineage_sha256": self.lineage_sha256,
+        }
+
+
+@dataclass(frozen=True)
+class BuildLocator(_CanonicalContract):
+    """One mutable root-relative location for immutable Build facts."""
+
+    facts_sha256: str
+    relative_path: str
+
+    def __post_init__(self) -> None:
+        _digest(self.facts_sha256, "locator.facts_sha256")
+        _relative_path(self.relative_path, "locator.relative_path")
+
+    def to_dict(self) -> dict[str, str]:
+        return {"facts_sha256": self.facts_sha256, "relative_path": self.relative_path}
+
+
+@dataclass(frozen=True)
+class BuildIndexDiagnostic(_CanonicalContract):
+    """A path-safe discovery result with no free-form filesystem error text."""
+
+    code: str
+    relative_path: str
+
+    def __post_init__(self) -> None:
+        _choice(self.code, _DIAGNOSTIC_CODES, "diagnostic.code")
+        _relative_path(self.relative_path, "diagnostic.relative_path")
+
+    def to_dict(self) -> dict[str, str]:
+        return {"code": self.code, "relative_path": self.relative_path}
+
+
+@dataclass(frozen=True)
+class BuildLocatorDocument(_CanonicalContract):
+    locators: tuple[BuildLocator, ...]
+    schema_version: str = BUILD_LOCATOR_VERSION
+
+    def __post_init__(self) -> None:
+        _version(self.schema_version, BUILD_LOCATOR_VERSION, "locators.schema_version")
+        _typed_tuple(self.locators, BuildLocator, "locators.locators", MAX_LOCATORS)
+        coordinates = tuple((item.facts_sha256, item.relative_path) for item in self.locators)
+        _sorted_unique(coordinates, "locators.locators")
+
+    def to_dict(self) -> dict[str, Any]:
+        return {
+            "schema_version": self.schema_version,
+            "locators": [item.to_dict() for item in self.locators],
+        }
+
+
+@dataclass(frozen=True)
+class BuildDiagnosticDocument(_CanonicalContract):
+    diagnostics: tuple[BuildIndexDiagnostic, ...]
+    schema_version: str = BUILD_DIAGNOSTIC_VERSION
+
+    def __post_init__(self) -> None:
+        _version(self.schema_version, BUILD_DIAGNOSTIC_VERSION, "diagnostics.schema_version")
+        _typed_tuple(
+            self.diagnostics,
+            BuildIndexDiagnostic,
+            "diagnostics.diagnostics",
+            MAX_DIAGNOSTICS,
+        )
+        coordinates = tuple((item.relative_path, item.code) for item in self.diagnostics)
+        _sorted_unique(coordinates, "diagnostics.diagnostics")
+
+    def to_dict(self) -> dict[str, Any]:
+        return {
+            "schema_version": self.schema_version,
+            "diagnostics": [item.to_dict() for item in self.diagnostics],
+        }
+
+
+@dataclass(frozen=True)
+class SnapshotMember(_CanonicalContract):
+    """Exact size and content identity of one manifest-bound snapshot member."""
+
+    path: str
+    bytes: int
+    sha256: str
+
+    def __post_init__(self) -> None:
+        _snapshot_member_path(self.path)
+        _integer(self.bytes, f"member[{self.path}].bytes", minimum=0, maximum=MAX_SAFE_INTEGER)
+        _digest(self.sha256, f"member[{self.path}].sha256")
+
+    def to_dict(self) -> dict[str, Any]:
+        return {"path": self.path, "bytes": self.bytes, "sha256": self.sha256}
+
+
+def manifest_aggregate_sha256(members: Sequence[SnapshotMember]) -> str:
+    """Digest the explicit ordered member table, not a live filesystem listing."""
+
+    if not isinstance(members, (tuple, list)):
+        raise LocalSearchContractError(
+            "LOCAL_SEARCH_TYPE", "members", "must be an ordered sequence"
+        )
+    return canonical_sha256({"members": [item.to_dict() for item in members]})
+
+
+@dataclass(frozen=True)
+class BuildIndexManifest(_CanonicalContract):
+    """The complete explicit layout and counts for one private index snapshot."""
+
+    entries: tuple[SnapshotMember, ...]
+    locators: SnapshotMember
+    diagnostics: SnapshotMember
+    entry_count: int
+    locator_count: int
+    diagnostic_count: int
+    total_bytes: int
+    aggregate_sha256: str
+    schema_version: str = BUILD_INDEX_MANIFEST_VERSION
+
+    def __post_init__(self) -> None:
+        _version(self.schema_version, BUILD_INDEX_MANIFEST_VERSION, "manifest.schema_version")
+        _typed_tuple(self.entries, SnapshotMember, "manifest.entries", MAX_ENTRIES)
+        paths = tuple(member.path for member in self.entries)
+        if paths != tuple(sorted(paths)):
+            raise LocalSearchContractError(
+                "LOCAL_SEARCH_MANIFEST", "manifest.entries", "must be sorted by exact path"
+            )
+        if len(set(paths)) != len(paths):
+            raise LocalSearchContractError(
+                "LOCAL_SEARCH_DUPLICATE", "manifest.entries", "member paths must be unique"
+            )
+        for member in self.entries:
+            match = re.fullmatch(r"entries/([0-9a-f]{64})\.json", member.path)
+            if match is None or match.group(1) != member.sha256:
+                raise LocalSearchContractError(
+                    "LOCAL_SEARCH_MANIFEST",
+                    f"manifest.entries[{member.path}]",
+                    "entry filename must equal its canonical member digest",
+                )
+        if not isinstance(self.locators, SnapshotMember) or self.locators.path != "locators.json":
+            raise LocalSearchContractError(
+                "LOCAL_SEARCH_MANIFEST", "manifest.locators", "must bind locators.json"
+            )
+        if (
+            not isinstance(self.diagnostics, SnapshotMember)
+            or self.diagnostics.path != "diagnostics.json"
+        ):
+            raise LocalSearchContractError(
+                "LOCAL_SEARCH_MANIFEST", "manifest.diagnostics", "must bind diagnostics.json"
+            )
+        _integer(self.entry_count, "manifest.entry_count", minimum=0, maximum=MAX_ENTRIES)
+        _integer(self.locator_count, "manifest.locator_count", minimum=0, maximum=MAX_LOCATORS)
+        _integer(
+            self.diagnostic_count,
+            "manifest.diagnostic_count",
+            minimum=0,
+            maximum=MAX_DIAGNOSTICS,
+        )
+        _integer(self.total_bytes, "manifest.total_bytes", minimum=0, maximum=MAX_SAFE_INTEGER)
+        _digest(self.aggregate_sha256, "manifest.aggregate_sha256")
+        if self.entry_count != len(self.entries):
+            raise LocalSearchContractError(
+                "LOCAL_SEARCH_MANIFEST",
+                "manifest.entry_count",
+                "must equal the number of bound entry members",
+            )
+        members = (*self.entries, self.locators, self.diagnostics)
+        if self.total_bytes != sum(item.bytes for item in members):
+            raise LocalSearchContractError(
+                "LOCAL_SEARCH_MANIFEST",
+                "manifest.total_bytes",
+                "must equal the sum of exact member sizes",
+            )
+        if self.aggregate_sha256 != manifest_aggregate_sha256(members):
+            raise LocalSearchContractError(
+                "LOCAL_SEARCH_MANIFEST",
+                "manifest.aggregate_sha256",
+                "does not match the ordered member table",
+            )
+
+    @property
+    def members(self) -> tuple[SnapshotMember, ...]:
+        return (*self.entries, self.locators, self.diagnostics)
+
+    def to_dict(self) -> dict[str, Any]:
+        return {
+            "schema_version": self.schema_version,
+            "entries": [item.to_dict() for item in self.entries],
+            "locators": self.locators.to_dict(),
+            "diagnostics": self.diagnostics.to_dict(),
+            "entry_count": self.entry_count,
+            "locator_count": self.locator_count,
+            "diagnostic_count": self.diagnostic_count,
+            "total_bytes": self.total_bytes,
+            "aggregate_sha256": self.aggregate_sha256,
+        }
+
+
+def build_index_entry_from_dict(data: Mapping[str, Any]) -> BuildIndexEntry:
+    payload = _mapping(data, "entry")
+    _exact(
+        payload,
+        {
+            "schema_version",
+            "question",
+            "question_sha256",
+            "requirements_sha256",
+            "grain",
+            "time_coverage",
+            "fields",
+            "sources",
+            "profile",
+            "recipe_lineage",
+            "candidate_sha256",
+            "table_sha256",
+            "validation_policy_sha256",
+            "lineage_sha256",
+        },
+        "entry",
+    )
+    return BuildIndexEntry(
+        schema_version=payload["schema_version"],
+        question=payload["question"],
+        question_sha256=payload["question_sha256"],
+        requirements_sha256=payload["requirements_sha256"],
+        grain=tuple(_sequence(payload["grain"], "entry.grain")),
+        time_coverage=_time_coverage_from_value(payload["time_coverage"]),
+        fields=tuple(
+            _field_from_dict(item, f"entry.fields[{index}]")
+            for index, item in enumerate(_sequence(payload["fields"], "entry.fields"))
+        ),
+        sources=tuple(
+            _source_from_dict(item, f"entry.sources[{index}]")
+            for index, item in enumerate(_sequence(payload["sources"], "entry.sources"))
+        ),
+        profile=_profile_from_value(payload["profile"]),
+        recipe_lineage=_recipe_from_value(payload["recipe_lineage"]),
+        candidate_sha256=payload["candidate_sha256"],
+        table_sha256=payload["table_sha256"],
+        validation_policy_sha256=payload["validation_policy_sha256"],
+        lineage_sha256=payload["lineage_sha256"],
+    )
+
+
+def build_locator_document_from_dict(data: Mapping[str, Any]) -> BuildLocatorDocument:
+    payload = _mapping(data, "locators")
+    _exact(payload, {"schema_version", "locators"}, "locators")
+    return BuildLocatorDocument(
+        schema_version=payload["schema_version"],
+        locators=tuple(
+            _locator_from_dict(item, f"locators.locators[{index}]")
+            for index, item in enumerate(_sequence(payload["locators"], "locators.locators"))
+        ),
+    )
+
+
+def build_diagnostic_document_from_dict(data: Mapping[str, Any]) -> BuildDiagnosticDocument:
+    payload = _mapping(data, "diagnostics")
+    _exact(payload, {"schema_version", "diagnostics"}, "diagnostics")
+    return BuildDiagnosticDocument(
+        schema_version=payload["schema_version"],
+        diagnostics=tuple(
+            _diagnostic_from_dict(item, f"diagnostics.diagnostics[{index}]")
+            for index, item in enumerate(
+                _sequence(payload["diagnostics"], "diagnostics.diagnostics")
+            )
+        ),
+    )
+
+
+def build_index_manifest_from_dict(data: Mapping[str, Any]) -> BuildIndexManifest:
+    payload = _mapping(data, "manifest")
+    _exact(
+        payload,
+        {
+            "schema_version",
+            "entries",
+            "locators",
+            "diagnostics",
+            "entry_count",
+            "locator_count",
+            "diagnostic_count",
+            "total_bytes",
+            "aggregate_sha256",
+        },
+        "manifest",
+    )
+    return BuildIndexManifest(
+        schema_version=payload["schema_version"],
+        entries=tuple(
+            _member_from_dict(item, f"manifest.entries[{index}]")
+            for index, item in enumerate(_sequence(payload["entries"], "manifest.entries"))
+        ),
+        locators=_member_from_dict(payload["locators"], "manifest.locators"),
+        diagnostics=_member_from_dict(payload["diagnostics"], "manifest.diagnostics"),
+        entry_count=payload["entry_count"],
+        locator_count=payload["locator_count"],
+        diagnostic_count=payload["diagnostic_count"],
+        total_bytes=payload["total_bytes"],
+        aggregate_sha256=payload["aggregate_sha256"],
+    )
+
+
+def _field_from_dict(value: Any, path: str) -> BuildField:
+    payload = _mapping(value, path)
+    _exact(payload, {"name", "logical_type"}, path)
+    return BuildField(payload["name"], payload["logical_type"])
+
+
+def _source_from_dict(value: Any, path: str) -> BuildSourceFacts:
+    payload = _mapping(value, path)
+    _exact(
+        payload,
+        {"source_id", "content_sha256", "rights_status", "rights_evidence_sha256"},
+        path,
+    )
+    return BuildSourceFacts(
+        payload["source_id"],
+        payload["content_sha256"],
+        payload["rights_status"],
+        payload["rights_evidence_sha256"],
+    )
+
+
+def _time_coverage_from_value(value: Any) -> BuildTimeCoverage | None:
+    if value is None:
+        return None
+    payload = _mapping(value, "entry.time_coverage")
+    _exact(payload, {"start_inclusive", "end_exclusive"}, "entry.time_coverage")
+    return BuildTimeCoverage(payload["start_inclusive"], payload["end_exclusive"])
+
+
+def _profile_from_value(value: Any) -> SealedProfileFactsV1 | None:
+    if value is None:
+        return None
+    payload = _mapping(value, "entry.profile")
+    _exact(
+        payload,
+        {
+            "profile_schema_version",
+            "evidence_sha256",
+            "row_count",
+            "columns",
+            "logical_types",
+            "null_counts",
+        },
+        "entry.profile",
+    )
+    return SealedProfileFactsV1(
+        profile_schema_version=payload["profile_schema_version"],
+        evidence_sha256=payload["evidence_sha256"],
+        row_count=payload["row_count"],
+        columns=tuple(_sequence(payload["columns"], "entry.profile.columns")),
+        logical_types=tuple(_sequence(payload["logical_types"], "entry.profile.logical_types")),
+        null_counts=tuple(_sequence(payload["null_counts"], "entry.profile.null_counts")),
+    )
+
+
+def _recipe_from_value(value: Any) -> BuildRecipeLineage | None:
+    if value is None:
+        return None
+    payload = _mapping(value, "entry.recipe_lineage")
+    _exact(
+        payload,
+        {"recipe_id", "recipe_version", "recipe_sha256", "predecessor_candidate_sha256"},
+        "entry.recipe_lineage",
+    )
+    return BuildRecipeLineage(
+        payload["recipe_id"],
+        payload["recipe_version"],
+        payload["recipe_sha256"],
+        payload["predecessor_candidate_sha256"],
+    )
+
+
+def _locator_from_dict(value: Any, path: str) -> BuildLocator:
+    payload = _mapping(value, path)
+    _exact(payload, {"facts_sha256", "relative_path"}, path)
+    return BuildLocator(payload["facts_sha256"], payload["relative_path"])
+
+
+def _diagnostic_from_dict(value: Any, path: str) -> BuildIndexDiagnostic:
+    payload = _mapping(value, path)
+    _exact(payload, {"code", "relative_path"}, path)
+    return BuildIndexDiagnostic(payload["code"], payload["relative_path"])
+
+
+def _member_from_dict(value: Any, path: str) -> SnapshotMember:
+    payload = _mapping(value, path)
+    _exact(payload, {"path", "bytes", "sha256"}, path)
+    return SnapshotMember(payload["path"], payload["bytes"], payload["sha256"])
+
+
+def _mapping(value: Any, path: str) -> Mapping[str, Any]:
+    if not isinstance(value, Mapping):
+        raise LocalSearchContractError("LOCAL_SEARCH_TYPE", path, "must be an object")
+    if any(not isinstance(key, str) for key in value):
+        raise LocalSearchContractError("LOCAL_SEARCH_TYPE", path, "keys must be strings")
+    return value
+
+
+def _sequence(value: Any, path: str) -> list[Any]:
+    if not isinstance(value, list):
+        raise LocalSearchContractError("LOCAL_SEARCH_TYPE", path, "must be an array")
+    return value
+
+
+def _exact(value: Mapping[str, Any], expected: set[str], path: str) -> None:
+    actual = set(value)
+    if actual != expected:
+        raise LocalSearchContractError(
+            "LOCAL_SEARCH_FIELDS",
+            path,
+            f"must contain exactly {sorted(expected)}; missing={sorted(expected - actual)}, "
+            f"extra={sorted(actual - expected)}",
+        )
+
+
+def _version(value: Any, expected: str, path: str) -> None:
+    if value != expected:
+        raise LocalSearchContractError("LOCAL_SEARCH_VERSION", path, f"must equal {expected!r}")
+
+
+def _text(value: Any, path: str, *, maximum: int) -> str:
+    if not isinstance(value, str) or not value or len(value) > maximum:
+        raise LocalSearchContractError(
+            "LOCAL_SEARCH_TEXT", path, f"must be non-empty text no longer than {maximum}"
+        )
+    if any(ord(char) < 0x20 or 0x7F <= ord(char) <= 0x9F for char in value):
+        raise LocalSearchContractError(
+            "LOCAL_SEARCH_TEXT", path, "must not contain control characters"
+        )
+    return value
+
+
+def _identifier(value: Any, path: str) -> str:
+    text = _text(value, path, maximum=256)
+    if _IDENTIFIER.fullmatch(text) is None:
+        raise LocalSearchContractError(
+            "LOCAL_SEARCH_IDENTIFIER", path, "must be a bounded identifier"
+        )
+    return text
+
+
+def _digest(value: Any, path: str) -> str:
+    if not isinstance(value, str) or _SHA256.fullmatch(value) is None:
+        raise LocalSearchContractError(
+            "LOCAL_SEARCH_SHA256", path, "must be a lowercase 64-character SHA-256"
+        )
+    return value
+
+
+def _integer(value: Any, path: str, *, minimum: int, maximum: int) -> int:
+    if type(value) is not int or not minimum <= value <= maximum:
+        raise LocalSearchContractError(
+            "LOCAL_SEARCH_INTEGER", path, f"must be an integer in [{minimum}, {maximum}]"
+        )
+    return value
+
+
+def _integers(values: Any, path: str, *, maximum: int) -> None:
+    if not isinstance(values, tuple) or len(values) > maximum:
+        raise LocalSearchContractError(
+            "LOCAL_SEARCH_TYPE", path, f"must be an immutable tuple of at most {maximum} values"
+        )
+    for index, value in enumerate(values):
+        _integer(value, f"{path}[{index}]", minimum=0, maximum=MAX_SAFE_INTEGER)
+
+
+def _choice(value: Any, allowed: frozenset[str], path: str) -> str:
+    text = _text(value, path, maximum=MAX_SHORT_TEXT)
+    if text not in allowed:
+        raise LocalSearchContractError(
+            "LOCAL_SEARCH_ENUM", path, f"must be one of {sorted(allowed)}"
+        )
+    return text
+
+
+def _texts(
+    values: Any,
+    path: str,
+    *,
+    maximum: int,
+    item_maximum: int,
+    nonempty: bool,
+) -> None:
+    if not isinstance(values, tuple) or len(values) > maximum or (nonempty and not values):
+        raise LocalSearchContractError(
+            "LOCAL_SEARCH_TYPE", path, f"must be an immutable tuple of at most {maximum} values"
+        )
+    for index, value in enumerate(values):
+        _text(value, f"{path}[{index}]", maximum=item_maximum)
+    if len(set(values)) != len(values):
+        raise LocalSearchContractError("LOCAL_SEARCH_DUPLICATE", path, "values must be unique")
+
+
+def _typed_choices(values: Any, allowed: frozenset[str], path: str, maximum: int) -> None:
+    if not isinstance(values, tuple) or len(values) > maximum:
+        raise LocalSearchContractError(
+            "LOCAL_SEARCH_TYPE", path, f"must be an immutable tuple of at most {maximum} values"
+        )
+    for index, value in enumerate(values):
+        _choice(value, allowed, f"{path}[{index}]")
+
+
+def _typed_tuple(
+    values: Any,
+    expected: type[Any],
+    path: str,
+    maximum: int,
+    *,
+    nonempty: bool = False,
+) -> None:
+    if not isinstance(values, tuple) or len(values) > maximum or (nonempty and not values):
+        raise LocalSearchContractError(
+            "LOCAL_SEARCH_TYPE", path, f"must be an immutable tuple of at most {maximum} values"
+        )
+    for index, value in enumerate(values):
+        if not isinstance(value, expected):
+            raise LocalSearchContractError(
+                "LOCAL_SEARCH_TYPE", f"{path}[{index}]", f"must be a {expected.__name__}"
+            )
+
+
+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 null or a {expected.__name__}"
+        )
+
+
+def _sorted_unique(values: tuple[Any, ...], path: str) -> None:
+    if len(set(values)) != len(values):
+        raise LocalSearchContractError("LOCAL_SEARCH_DUPLICATE", path, "coordinates must be unique")
+    if values != tuple(sorted(values)):
+        raise LocalSearchContractError("LOCAL_SEARCH_ORDER", path, "coordinates must be sorted")
+
+
+def _iso_date(value: Any, path: str) -> date:
+    text = _text(value, path, maximum=10)
+    try:
+        parsed = date.fromisoformat(text)
+    except ValueError:
+        raise LocalSearchContractError(
+            "LOCAL_SEARCH_TIME", path, "must be an exact ISO calendar date"
+        ) from None
+    if parsed.isoformat() != text:
+        raise LocalSearchContractError(
+            "LOCAL_SEARCH_TIME", path, "must be an exact ISO calendar date"
+        )
+    return parsed
+
+
+def _relative_path(value: Any, path: str) -> str:
+    text = _text(value, path, maximum=MAX_PATH)
+    if "\\" in text or text.startswith("/"):
+        raise LocalSearchContractError(
+            "LOCAL_SEARCH_PATH", path, "must be a root-relative POSIX path"
+        )
+    parsed = PurePosixPath(text)
+    if text in {".", ".."} or any(part in {"", ".", ".."} for part in parsed.parts):
+        raise LocalSearchContractError(
+            "LOCAL_SEARCH_PATH", path, "must be a normalized root-relative POSIX path"
+        )
+    if parsed.as_posix() != text:
+        raise LocalSearchContractError(
+            "LOCAL_SEARCH_PATH", path, "must be a normalized root-relative POSIX path"
+        )
+    return text
+
+
+def _snapshot_member_path(value: Any) -> str:
+    text = _text(value, "member.path", maximum=MAX_PATH)
+    allowed = text in {"locators.json", "diagnostics.json"} or re.fullmatch(
+        r"entries/[0-9a-f]{64}\.json", text
+    )
+    if not allowed:
+        raise LocalSearchContractError(
+            "LOCAL_SEARCH_PATH", "member.path", "is not an allowed private-index member path"
+        )
+    return text