mostlyright-data 0.9.0__py3-none-any.whl

mostlyright/data_harness/sources/catalog/packed_retrieval.py

@@ -0,0 +1,1517 @@
+"""Bounded exact retrieval over a range-local packed generation.
+
+:mod:`packed_catalog` defines what a packed generation *is* and :mod:`packed_writer` publishes one.
+This module is the only thing that reads one to answer a question, and it is deliberately the
+smallest surface that can do so: identities out, numbers never.
+
+Four properties are load-bearing.
+
+*Nothing is searched that the caller did not name.*  A search takes the caller's exact outer head
+digest **and** the publication receipt whose coordinate re-derives from its own body, and it refuses
+unless that receipt describes the head installed at this root -- the same range descriptors, the
+same range chain, the same counters, the same backends.  Every range manifest, bound segment,
+posting segment, vector pack and facts member is then read back and compared against the digest the
+authenticated chain binds it to.  An ambient head, an unbound summary, a substituted pack and a
+re-minted receipt that quietly drops an accelerator out of its own binding all refuse rather than
+answer.
+
+*The answer is exact whenever it is complete.*  An entry's score is the maximum
+over the four layers of the exact integer dot product of the query with that layer's vector.  When
+the selected backend is the generation's posting backend the four layer dot products are accumulated
+from the exact posting segments; otherwise the four layer packs are opened and scored directly.  The
+two agree term for term, because the postings *are* the nonzero terms of those packs.
+
+*Pruning is strict, and the bound is the publisher's.*  A range is skipped only when the sign-aware
+conservative bound of :func:`packed_catalog.range_upper_bound`, computed against the independently
+readback-validated bound segment published with the generation, is **strictly** below the current
+kth score.  An
+equal bound still exact-scans: a tie is broken by entry id ascending, and a pruned range cannot
+present an id.  Nothing recomputes a bound from the packs at query time; that is the publisher's job
+and it was already done by an independent reader before the head was installed.
+
+*Work is bounded before it is spent.*  :class:`CatalogSearchWorkLimits` is closed and has no
+defaults, so no caller can accidentally ask for unbounded work.  Ranges, packs, member bytes,
+posting terms, candidates, open descriptors, query encodes and elapsed time are each checked before
+the work that would consume them.  A cap that closes before every unpruned range has closed returns
+a typed *incomplete* carrying the work actuals and **no candidate at all** -- a partial ranking that
+reads like a complete one is the one answer this module may never give.
+
+There is no threshold, no approximate neighbour search, no persisted score and no query cache. A
+threshold would be an admission decision taken by similarity; the other three would each make the
+answer a function of something other than the exact bytes the caller authenticated.
+"""
+
+from __future__ import annotations
+
+import contextlib
+import os
+import time
+from collections.abc import Iterator, Mapping, Sequence
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Any
+
+from mostlyright.data_harness.canonical import (
+    CanonicalJSONError,
+    canonical_sha256,
+    parse_canonical_json,
+    sha256_bytes,
+)
+from mostlyright.data_harness.sources.catalog.bounded_io import (
+    BoundedReadFailure,
+    read_bounded_descriptor,
+)
+from mostlyright.data_harness.sources.catalog.contracts import EMBEDDING_LAYERS
+from mostlyright.data_harness.sources.catalog.coverage import coverage_is_valid
+from mostlyright.data_harness.sources.catalog.embedding import (
+    BOUNDED_SCALAR_ADAPTER,
+    EmbeddingBackend,
+)
+from mostlyright.data_harness.sources.catalog.entry_v2 import (
+    CatalogEntryV2,
+    catalog_entry_v2_from_dict,
+)
+from mostlyright.data_harness.sources.catalog.packed_catalog import (
+    MAX_FACTS_MEMBER_BYTES,
+    MAX_PACKED_HEAD_BYTES,
+    MAX_POSTING_SEGMENT_BYTES,
+    MAX_POSTING_SEGMENTS,
+    MAX_RANGE_DESCRIPTORS,
+    MAX_RANGE_MANIFEST_BYTES,
+    MAX_RANGE_MEMBER_DESCRIPTORS,
+    MAX_VECTOR_MEMBER_BYTES,
+    MEMBER_HEADER_BYTES,
+    MIN_POSTING_SEGMENTS,
+    PACKED_FACTS_SCHEMA,
+    PACKED_HEAD_FILENAME,
+    PACKED_HEAD_SCHEMA,
+    PACKED_MEMBERS_DIRNAME,
+    PACKED_RANGE_MANIFEST_SCHEMA,
+    RANGE_ENTRIES,
+    CatalogPackedRefused,
+    PackedMemberDescriptor,
+    PackedRangeDescriptor,
+    bound_segment_bytes,
+    member_descriptor_from_dict,
+    member_filename,
+    parse_bound_segment,
+    parse_posting_segment,
+    parse_vector_member,
+    range_binding_sha256,
+    range_descriptor_from_dict,
+    range_upper_bound,
+    ranges_chain_sha256,
+)
+from mostlyright.data_harness.sources.catalog.retrieval import (
+    MAX_QUERY_CHARS,
+    MAX_RETRIEVAL_LIMIT,
+)
+
+#: The publication receipt schema this reader admits. It is stated here rather than imported from
+#: :mod:`packed_writer`, because a read path that imports the publisher would put a writer on the
+#: query call graph; ``test_catalog_packed_retrieval`` asserts the two constants are one string.
+PACKED_RECEIPT_SCHEMA = "mr-data-catalog-packed.v1"
+PACKED_SEARCH_RESULT_SCHEMA = "harness-catalog-packed-search.v1"
+PACKED_WORK_LIMITS_SCHEMA = "harness-catalog-packed-work-limits.v1"
+
+RETRIEVAL_V2_FILENAME = "retrieval.json"
+SEALED_V1_FILENAME = "catalog.json"
+
+#: The three public-source stores this repository can answer from, newest first. Dispatch is by
+#: exact filename, and the packed head is additionally admitted only under its exact schema.
+PUBLIC_STORE_KINDS = ("packed", "retrieval_v2", "sealed_v1")
+
+MAX_WORK_RANGES = MAX_RANGE_DESCRIPTORS
+MAX_WORK_PACKS = MAX_RANGE_DESCRIPTORS * MAX_RANGE_MEMBER_DESCRIPTORS
+MAX_WORK_MEMBER_BYTES = 64 * 1024 * 1024 * 1024
+MAX_WORK_POSTING_TERMS = 1 << 33
+MAX_WORK_CANDIDATES = MAX_RANGE_DESCRIPTORS * RANGE_ENTRIES
+
+#: Three descriptors is the whole peak: the root, its members directory, and one member.
+MIN_WORK_OPEN_FILES = 3
+MAX_WORK_OPEN_FILES = 16
+MAX_WORK_QUERY_ENCODES = 8
+MAX_WORK_ELAPSED_SECONDS = 24 * 60 * 60
+
+_NANOSECONDS = 1_000_000_000
+
+PACKED_INCOMPLETE_CODES = (
+    "PACKED_SEARCH_RANGE_BUDGET",
+    "PACKED_SEARCH_PACK_BUDGET",
+    "PACKED_SEARCH_MEMBER_BYTE_BUDGET",
+    "PACKED_SEARCH_POSTING_TERM_BUDGET",
+    "PACKED_SEARCH_CANDIDATE_BUDGET",
+    "PACKED_SEARCH_OPEN_FILE_BUDGET",
+    "PACKED_SEARCH_QUERY_ENCODE_BUDGET",
+    "PACKED_SEARCH_TIME_BUDGET",
+)
+
+_OPEN_DIRECTORY = (
+    os.O_RDONLY
+    | getattr(os, "O_DIRECTORY", 0)
+    | getattr(os, "O_NOFOLLOW", 0)
+    | getattr(os, "O_CLOEXEC", 0)
+)
+_OPEN_MEMBER = (
+    os.O_RDONLY
+    | getattr(os, "O_NOFOLLOW", 0)
+    | getattr(os, "O_CLOEXEC", 0)
+    | getattr(os, "O_NONBLOCK", 0)
+)
+
+_READ_CHUNK = 1 << 20
+
+_RECEIPT_OUTPUT_MEMBERS = frozenset(
+    {
+        "head_sha256",
+        "range_count",
+        "entry_count",
+        "ranges",
+        "ranges_chain_sha256",
+        "vector_member_sha256s",
+        "posting_member_sha256s",
+        "bound_member_sha256s",
+    }
+)
+
+_FACTS_ENTRY_MEMBERS = frozenset(
+    {
+        "key",
+        "entry_id",
+        "classification",
+        "semantic_facts_digest",
+        "entry_sha256",
+        "entry_json",
+    }
+)
+
+_RANGE_MANIFEST_MEMBERS = frozenset(
+    {
+        "schema_version",
+        "range_index",
+        "first_key",
+        "last_key",
+        "entry_count",
+        "facts_sha256",
+        "history_sha256",
+        "range_binding_sha256",
+        "backends",
+        "posting_backend_coordinate",
+        "members",
+        "root_sha256",
+    }
+)
+
+
+def _refuse(code: str, path: str, detail: str) -> CatalogPackedRefused:
+    return CatalogPackedRefused(code, path, detail)
+
+
+def _is_digest(value: Any) -> bool:
+    return (
+        isinstance(value, str)
+        and len(value) == 64
+        and all(character in "0123456789abcdef" for character in value)
+    )
+
+
+def _now_ns() -> int:
+    """One monotonic clock reading. Named so a test can hold it still."""
+
+    return time.monotonic_ns()
+
+
+# ------------------------------------------------------------------------------------------
+# The closed work contract
+# ------------------------------------------------------------------------------------------
+
+
+_WORK_LIMIT_CEILINGS = {
+    "max_ranges": MAX_WORK_RANGES,
+    "max_packs": MAX_WORK_PACKS,
+    "max_member_bytes": MAX_WORK_MEMBER_BYTES,
+    "max_posting_terms": MAX_WORK_POSTING_TERMS,
+    "max_candidates": MAX_WORK_CANDIDATES,
+    "max_open_files": MAX_WORK_OPEN_FILES,
+    "max_query_encodes": MAX_WORK_QUERY_ENCODES,
+    "max_elapsed_seconds": MAX_WORK_ELAPSED_SECONDS,
+}
+
+
+@dataclass(frozen=True)
+class CatalogSearchWorkLimits:
+    """Every bound one packed search may consume, stated before it consumes any of them.
+
+    There is no default anywhere on this contract. A default would be a hidden answer to "how much
+    work may this question cost", supplied by whoever forgot to ask rather than by the caller who
+    has to live with it.
+    """
+
+    max_ranges: int
+    max_packs: int
+    max_member_bytes: int
+    max_posting_terms: int
+    max_candidates: int
+    max_open_files: int
+    max_query_encodes: int
+    max_elapsed_seconds: int
+
+    def __post_init__(self) -> None:
+        for name, ceiling in _WORK_LIMIT_CEILINGS.items():
+            value = getattr(self, name)
+            if type(value) is not int or not 1 <= value <= ceiling:
+                raise _refuse(
+                    "PACKED_SEARCH_LIMIT",
+                    f"work_limits.{name}",
+                    f"must be an integer in [1, {ceiling}]",
+                )
+
+    def to_dict(self) -> dict[str, Any]:
+        return {
+            "schema_version": PACKED_WORK_LIMITS_SCHEMA,
+            **{name: getattr(self, name) for name in _WORK_LIMIT_CEILINGS},
+        }
+
+    @property
+    def digest(self) -> str:
+        return canonical_sha256(self.to_dict())
+
+
+@dataclass(frozen=True)
+class PackedSearchWork:
+    """What one search actually did. Every number here is deterministic; elapsed time is not one."""
+
+    ranges_bounded: int
+    ranges_scanned: int
+    ranges_pruned: int
+    packs_opened: int
+    member_bytes_read: int
+    posting_terms_read: int
+    candidates_examined: int
+    open_files_peak: int
+    query_encodes: int
+
+    def to_dict(self) -> dict[str, int]:
+        return {name: getattr(self, name) for name in self.__dataclass_fields__}
+
+
+class _Exhausted(Exception):
+    """One work cap closed.
+
+    It is private control flow, not a typed refusal: it never leaves this module as an exception,
+    and the budget it names becomes ``PackedRetrievalResult.incomplete_code`` instead. So it
+    deliberately carries a ``budget`` rather than a ``code`` -- a workbench reader never sees this
+    class, and a class that looks like a typed error while never reaching a person is exactly the
+    thing the plain-words gates exist to notice.
+    """
+
+    def __init__(self, budget: str) -> None:
+        super().__init__(budget)
+        self.budget = budget
+
+
+class _Budget:
+    """Every cap, spent before the work it pays for rather than measured after it."""
+
+    def __init__(self, limits: CatalogSearchWorkLimits) -> None:
+        self._limits = limits
+        self._deadline_ns = _now_ns() + limits.max_elapsed_seconds * _NANOSECONDS
+        self._open_files = 0
+        self.ranges_bounded = 0
+        self.ranges_scanned = 0
+        self.ranges_pruned = 0
+        self.packs_opened = 0
+        self.member_bytes_read = 0
+        self.posting_terms_read = 0
+        self.candidates_examined = 0
+        self.open_files_peak = 0
+        self.query_encodes = 0
+
+    def work(self) -> PackedSearchWork:
+        return PackedSearchWork(
+            ranges_bounded=self.ranges_bounded,
+            ranges_scanned=self.ranges_scanned,
+            ranges_pruned=self.ranges_pruned,
+            packs_opened=self.packs_opened,
+            member_bytes_read=self.member_bytes_read,
+            posting_terms_read=self.posting_terms_read,
+            candidates_examined=self.candidates_examined,
+            open_files_peak=self.open_files_peak,
+            query_encodes=self.query_encodes,
+        )
+
+    def check_time(self) -> None:
+        if _now_ns() > self._deadline_ns:
+            raise _Exhausted("PACKED_SEARCH_TIME_BUDGET")
+
+    def spend_range_bounded(self) -> None:
+        if self.ranges_bounded + 1 > self._limits.max_ranges:
+            raise _Exhausted("PACKED_SEARCH_RANGE_BUDGET")
+        self.ranges_bounded += 1
+
+    def spend_range_scanned(self) -> None:
+        if self.ranges_scanned + 1 > self._limits.max_ranges:
+            raise _Exhausted("PACKED_SEARCH_RANGE_BUDGET")
+        self.ranges_scanned += 1
+
+    def note_pruned(self) -> None:
+        self.ranges_pruned += 1
+
+    def spend_member_bytes(self, count: int) -> None:
+        if self.member_bytes_read + count > self._limits.max_member_bytes:
+            raise _Exhausted("PACKED_SEARCH_MEMBER_BYTE_BUDGET")
+        self.member_bytes_read += count
+
+    def spend_pack(self) -> None:
+        if self.packs_opened + 1 > self._limits.max_packs:
+            raise _Exhausted("PACKED_SEARCH_PACK_BUDGET")
+        self.packs_opened += 1
+
+    def spend_posting_terms(self, count: int) -> None:
+        if self.posting_terms_read + count > self._limits.max_posting_terms:
+            raise _Exhausted("PACKED_SEARCH_POSTING_TERM_BUDGET")
+        self.posting_terms_read += count
+
+    def spend_candidates(self, count: int) -> None:
+        if self.candidates_examined + count > self._limits.max_candidates:
+            raise _Exhausted("PACKED_SEARCH_CANDIDATE_BUDGET")
+        self.candidates_examined += count
+
+    def spend_query_encode(self) -> None:
+        if self.query_encodes + 1 > self._limits.max_query_encodes:
+            raise _Exhausted("PACKED_SEARCH_QUERY_ENCODE_BUDGET")
+        self.query_encodes += 1
+
+    def open_file(self) -> None:
+        if self._open_files + 1 > self._limits.max_open_files:
+            raise _Exhausted("PACKED_SEARCH_OPEN_FILE_BUDGET")
+        self._open_files += 1
+        if self._open_files > self.open_files_peak:
+            self.open_files_peak = self._open_files
+
+    def close_file(self) -> None:
+        self._open_files -= 1
+
+
+# ------------------------------------------------------------------------------------------
+# The read-only packed root
+# ------------------------------------------------------------------------------------------
+
+
+def _read_regular(parent_fd: int, name: str, *, maximum: int, budget: _Budget | None) -> bytes:
+    """Read one bounded single-link regular file relative to a retained directory."""
+
+    if budget is not None:
+        budget.open_file()
+    try:
+        descriptor = os.open(name, _OPEN_MEMBER, dir_fd=parent_fd)
+    except FileNotFoundError:
+        if budget is not None:
+            budget.close_file()
+        raise
+    except OSError as error:
+        if budget is not None:
+            budget.close_file()
+        raise _refuse("PACKED_SEARCH_MEMBER", name, "cannot open a plain packed member") from error
+    try:
+        info = os.fstat(descriptor)
+        if budget is not None:
+            budget.spend_member_bytes(info.st_size)
+        try:
+            return read_bounded_descriptor(descriptor, maximum=maximum)
+        except BoundedReadFailure as error:
+            raise _refuse(
+                "PACKED_SEARCH_MEMBER",
+                name,
+                "a packed member must be stable, bounded, and single-link regular",
+            ) from error
+    finally:
+        os.close(descriptor)
+        if budget is not None:
+            budget.close_file()
+
+
+class _PackedRoot:
+    """One locally confined packed root, opened read-only and never by pathname twice."""
+
+    def __init__(self, root: Path, budget: _Budget) -> None:
+        self.root = Path(root)
+        self._budget = budget
+        self._root_fd = -1
+        self._members_fd = -1
+        self._stack: contextlib.ExitStack | None = None
+
+    @contextlib.contextmanager
+    def opened(self) -> Iterator[_PackedRoot]:
+        """Retain the root for the whole search. The members directory opens on first use.
+
+        The head is a document of the root, so a root with no members directory still refuses on
+        its missing head rather than on a directory a caller never asked about.
+        """
+
+        with contextlib.ExitStack() as stack:
+            self._budget.open_file()
+            stack.callback(self._budget.close_file)
+            try:
+                root_fd = os.open(self.root, _OPEN_DIRECTORY)
+            except OSError as error:
+                raise _refuse(
+                    "PACKED_SEARCH_ROOT", str(self.root), "cannot open a plain packed root"
+                ) from error
+            stack.callback(os.close, root_fd)
+            self._root_fd = root_fd
+            self._stack = stack
+            try:
+                yield self
+            finally:
+                self._root_fd = -1
+                self._members_fd = -1
+                self._stack = None
+
+    def _members(self) -> int:
+        if self._members_fd != -1:
+            return self._members_fd
+        stack = self._stack
+        if stack is None:  # pragma: no cover - only reachable outside `opened`
+            raise _refuse("PACKED_SEARCH_ROOT", str(self.root), "the packed root is not open")
+        self._budget.open_file()
+        stack.callback(self._budget.close_file)
+        try:
+            members_fd = os.open(PACKED_MEMBERS_DIRNAME, _OPEN_DIRECTORY, dir_fd=self._root_fd)
+        except OSError as error:
+            raise _refuse(
+                "PACKED_SEARCH_ROOT",
+                PACKED_MEMBERS_DIRNAME,
+                "cannot open the packed members directory",
+            ) from error
+        stack.callback(os.close, members_fd)
+        self._members_fd = members_fd
+        return members_fd
+
+    def read_document(self, name: str, *, maximum: int) -> bytes | None:
+        try:
+            return _read_regular(self._root_fd, name, maximum=maximum, budget=self._budget)
+        except FileNotFoundError:
+            return None
+
+    def read_member(self, sha256: str, *, kind: str, maximum: int) -> bytes | None:
+        members_fd = self._members()
+        self._budget.spend_pack()
+        try:
+            return _read_regular(
+                members_fd,
+                member_filename(kind, sha256),
+                maximum=maximum,
+                budget=self._budget,
+            )
+        except FileNotFoundError:
+            return None
+
+
+def detect_public_store_kind(root: Path) -> str:
+    """Name the public store installed at ``root`` by exact filename, never by discovery.
+
+    A packed head is admitted only under its exact schema: a file with that name that is not a
+    packed head refuses rather than silently falling through to the legacy v2 reader.
+    """
+
+    if not isinstance(root, Path):
+        raise _refuse("PACKED_SEARCH_STORE", "root", "must be a pathlib.Path")
+    try:
+        root_fd = os.open(root, _OPEN_DIRECTORY)
+    except OSError as error:
+        raise _refuse(
+            "PACKED_SEARCH_STORE", str(root), "no readable public store at this root"
+        ) from error
+    try:
+        try:
+            raw = _read_regular(
+                root_fd, PACKED_HEAD_FILENAME, maximum=MAX_PACKED_HEAD_BYTES, budget=None
+            )
+        except FileNotFoundError:
+            raw = None
+        if raw is not None:
+            try:
+                head = parse_canonical_json(raw)
+            except CanonicalJSONError as error:
+                raise _refuse(
+                    "PACKED_SEARCH_STORE",
+                    PACKED_HEAD_FILENAME,
+                    "a packed head is canonical JSON or it is not a packed head",
+                ) from error
+            if not isinstance(head, dict) or head.get("schema_version") != PACKED_HEAD_SCHEMA:
+                raise _refuse(
+                    "PACKED_SEARCH_STORE",
+                    PACKED_HEAD_FILENAME,
+                    "this root installs a head that is not a packed head",
+                )
+            return "packed"
+        for name, kind in (
+            (RETRIEVAL_V2_FILENAME, "retrieval_v2"),
+            (SEALED_V1_FILENAME, "sealed_v1"),
+        ):
+            try:
+                os.stat(name, dir_fd=root_fd, follow_symlinks=False)
+            except FileNotFoundError:
+                continue
+            except OSError as error:
+                raise _refuse(
+                    "PACKED_SEARCH_STORE", name, "cannot inspect a public store member"
+                ) from error
+            return kind
+        raise _refuse(
+            "PACKED_SEARCH_STORE",
+            str(root),
+            "this root holds no packed head, v2 retrieval manifest or sealed catalog",
+        )
+    finally:
+        os.close(root_fd)
+
+
+# ------------------------------------------------------------------------------------------
+# What one search returns
+# ------------------------------------------------------------------------------------------
+
+
+@dataclass(frozen=True)
+class PackedRankedEntry:
+    """One ordered identity and the exact facts it was carried by. No ranking number, ever."""
+
+    rank: int
+    entry_id: str
+    entry_coordinate: str
+    entry_digest: str
+    semantic_facts_digest: str
+    range_index: int
+    entry: CatalogEntryV2
+
+    def to_dict(self) -> dict[str, Any]:
+        return {
+            "rank": self.rank,
+            "entry_id": self.entry_id,
+            "entry_coordinate": self.entry_coordinate,
+            "entry_digest": self.entry_digest,
+            "semantic_facts_digest": self.semantic_facts_digest,
+        }
+
+
+@dataclass(frozen=True)
+class PackedRetrievalResult:
+    """One search's complete outcome, or a typed incomplete carrying only what it did.
+
+    An incomplete result carries no entry. That is the whole point of the type: a caller that
+    cannot tell a budget-truncated ranking from a finished one would present the first as the
+    second, and the difference is exactly the entries the search never looked at.
+    """
+
+    status: str
+    incomplete_code: str | None
+    head_sha256: str
+    receipt_coordinate_sha256: str
+    backend_coordinate: str
+    question_digest: str
+    limit: int
+    range_manifest_sha256s: tuple[str, ...]
+    vector_member_sha256s: tuple[str, ...]
+    posting_member_sha256s: tuple[str, ...]
+    bound_member_sha256s: tuple[str, ...]
+    entries: tuple[PackedRankedEntry, ...]
+    limits: CatalogSearchWorkLimits
+    work: PackedSearchWork
+
+    def __post_init__(self) -> None:
+        if self.status not in {"complete", "incomplete"}:
+            raise _refuse(
+                "PACKED_SEARCH_STATUS", "result.status", "a search is complete or incomplete"
+            )
+        if self.status == "complete":
+            if self.incomplete_code is not None:
+                raise _refuse(
+                    "PACKED_SEARCH_STATUS",
+                    "result.incomplete_code",
+                    "a complete search names no exhausted budget",
+                )
+        elif self.incomplete_code not in PACKED_INCOMPLETE_CODES or self.entries:
+            raise _refuse(
+                "PACKED_SEARCH_STATUS",
+                "result.entries",
+                "an incomplete search names the budget that closed and offers no ranked identity",
+            )
+        if tuple(item.rank for item in self.entries) != tuple(range(1, len(self.entries) + 1)):
+            raise _refuse(
+                "PACKED_SEARCH_ORDER",
+                "result.entries",
+                "ranks must be contiguous and ordered from one",
+            )
+
+    def to_dict(self) -> dict[str, Any]:
+        return {
+            "schema_version": PACKED_SEARCH_RESULT_SCHEMA,
+            "status": self.status,
+            "incomplete_code": self.incomplete_code,
+            "head_sha256": self.head_sha256,
+            "receipt_coordinate_sha256": self.receipt_coordinate_sha256,
+            "backend_coordinate": self.backend_coordinate,
+            "layers": list(EMBEDDING_LAYERS),
+            "question_digest": self.question_digest,
+            "limit": self.limit,
+            "range_manifest_sha256s": list(self.range_manifest_sha256s),
+            "vector_member_sha256s": list(self.vector_member_sha256s),
+            "posting_member_sha256s": list(self.posting_member_sha256s),
+            "bound_member_sha256s": list(self.bound_member_sha256s),
+            "entries": [item.to_dict() for item in self.entries],
+            "work_limits": self.limits.to_dict(),
+            "work_actuals": self.work.to_dict(),
+        }
+
+    @property
+    def identity_sha256(self) -> str:
+        return canonical_sha256(self.to_dict())
+
+
+# ------------------------------------------------------------------------------------------
+# Authentication
+# ------------------------------------------------------------------------------------------
+
+
+@dataclass(frozen=True)
+class _Authenticated:
+    """The head and the receipt, agreed with each other before a single range is opened."""
+
+    head: dict[str, Any]
+    head_sha256: str
+    receipt_coordinate_sha256: str
+    descriptors: tuple[PackedRangeDescriptor, ...]
+    backends: tuple[Mapping[str, Any], ...]
+    posting_backend_coordinate: str
+    vector_payload_sha256s: frozenset[str]
+    posting_member_sha256s: frozenset[str]
+    bound_member_sha256s: frozenset[str]
+
+
+def _receipt_coordinate(receipt: Any) -> str:
+    """Check the receipt against itself, before a byte of the generation has been read.
+
+    This half needs no head: a receipt that is not a complete bounded-scalar publication, or that
+    does not reproduce its own coordinate, is refused whatever is installed at the root.
+    """
+
+    if not isinstance(receipt, Mapping) or receipt.get("schema_version") != PACKED_RECEIPT_SCHEMA:
+        raise _refuse("PACKED_RECEIPT_SCHEMA", "packed.receipt", "receipt contract differs")
+    if receipt.get("adapter_mode") != BOUNDED_SCALAR_ADAPTER:
+        raise _refuse(
+            "PACKED_RECEIPT_ADAPTER",
+            "packed.receipt.adapter_mode",
+            f"a packed generation may claim only the {BOUNDED_SCALAR_ADAPTER!r} adapter",
+        )
+    if receipt.get("status") != "complete":
+        raise _refuse(
+            "PACKED_RECEIPT_STATUS",
+            "packed.receipt.status",
+            "only a complete publication may be searched",
+        )
+    body = {key: value for key, value in receipt.items() if key != "coordinate_sha256"}
+    try:
+        coordinate = canonical_sha256(body)
+    except CanonicalJSONError as error:
+        raise _refuse(
+            "PACKED_RECEIPT_COORDINATE", "packed.receipt", "receipt is not canonical"
+        ) from error
+    if coordinate != receipt.get("coordinate_sha256"):
+        raise _refuse(
+            "PACKED_RECEIPT_COORDINATE",
+            "packed.receipt.coordinate_sha256",
+            "the receipt does not reproduce its own coordinate",
+        )
+    return coordinate
+
+
+def _authenticate(
+    root: _PackedRoot, *, expected_head_sha256: str, receipt: Mapping[str, Any], coordinate: str
+) -> _Authenticated:
+    raw = root.read_document(PACKED_HEAD_FILENAME, maximum=MAX_PACKED_HEAD_BYTES)
+    if raw is None:
+        raise _refuse("PACKED_HEAD_MISSING", "packed.head", "no readable packed head at this root")
+    observed = sha256_bytes(raw)
+    if observed != expected_head_sha256:
+        raise _refuse(
+            "PACKED_HEAD_MISMATCH",
+            "packed.head",
+            "the installed head is not the caller's exact generation",
+        )
+    head = _parse_head(raw)
+    descriptors = tuple(
+        range_descriptor_from_dict(value, path=f"packed.head.ranges[{index}]")
+        for index, value in enumerate(head["ranges"])
+    )
+    if ranges_chain_sha256(descriptors) != head["ranges_chain_sha256"]:
+        raise _refuse(
+            "PACKED_HEAD_EXPECTED",
+            "packed.head.ranges_chain_sha256",
+            "the head's stated range chain is not the chain of its own descriptors",
+        )
+    for position, descriptor in enumerate(descriptors):
+        if descriptor.range_index != position:
+            raise _refuse(
+                "PACKED_RANGE_ORDER",
+                f"packed.head.ranges[{position}]",
+                "ranges are consecutive from zero",
+            )
+    return _bound_receipt(
+        receipt,
+        head=head,
+        head_sha256=observed,
+        descriptors=descriptors,
+        coordinate=coordinate,
+    )
+
+
+def _parse_head(raw: bytes) -> dict[str, Any]:
+    """Read the outer head exactly. The publisher's own laws, enforced by this reader."""
+
+    if len(raw) > MAX_PACKED_HEAD_BYTES:
+        raise _refuse("PACKED_HEAD_LIMIT", "packed.head", "head exceeds its byte bound")
+    try:
+        head = parse_canonical_json(raw)
+    except CanonicalJSONError as error:
+        raise _refuse("PACKED_HEAD_SCHEMA", "packed.head", "head is not canonical") from error
+    if (
+        not isinstance(head, dict)
+        or head.get("schema_version") != PACKED_HEAD_SCHEMA
+        or not isinstance(head.get("ranges"), list)
+        or not isinstance(head.get("backends"), list)
+        or not isinstance(head.get("counters"), dict)
+        or not isinstance(head.get("posting_backend_coordinate"), str)
+    ):
+        raise _refuse("PACKED_HEAD_SCHEMA", "packed.head", "head contract differs")
+    body = {key: value for key, value in head.items() if key != "root_sha256"}
+    if canonical_sha256(body) != head.get("root_sha256"):
+        raise _refuse(
+            "PACKED_HEAD_DIGEST",
+            "packed.head.root_sha256",
+            "the head's own digest does not reproduce from the head it signs",
+        )
+    if not 1 <= len(head["ranges"]) <= MAX_RANGE_DESCRIPTORS:
+        raise _refuse(
+            "PACKED_HEAD_DESCRIPTORS",
+            "packed.head.ranges",
+            f"an outer head holds 1 to {MAX_RANGE_DESCRIPTORS} range descriptors",
+        )
+    # This is the reader an *installed* catalogue is read back through, which makes it the one
+    # place the coverage statement has to be required rather than merely carried. A head that
+    # omitted it, or stated one that is not a coverage, would otherwise be readable here while
+    # the publisher's own reader refused it -- and a catalogue that cannot say whether it holds
+    # the whole sweep is exactly the thing the member exists to prevent.
+    if not coverage_is_valid(head.get("coverage")):
+        raise _refuse(
+            "PACKED_HEAD_COVERAGE",
+            "packed.head.coverage",
+            "an installed generation states what it covers and what it drew from",
+        )
+    return head
+
+
+def _bound_receipt(
+    receipt: Mapping[str, Any],
+    *,
+    head: dict[str, Any],
+    head_sha256: str,
+    descriptors: tuple[PackedRangeDescriptor, ...],
+    coordinate: str,
+) -> _Authenticated:
+    outputs = receipt.get("outputs")
+    if not isinstance(outputs, Mapping) or not _RECEIPT_OUTPUT_MEMBERS <= set(outputs):
+        raise _refuse("PACKED_RECEIPT_SCHEMA", "packed.receipt.outputs", "outputs contract differs")
+    if (
+        outputs["head_sha256"] != head_sha256
+        or outputs["range_count"] != head["range_count"]
+        or outputs["entry_count"] != head["entry_count"]
+        or outputs["ranges"] != head["ranges"]
+        or outputs["ranges_chain_sha256"] != head["ranges_chain_sha256"]
+        or receipt.get("counters") != head["counters"]
+        or receipt.get("backends") != head["backends"]
+        or receipt.get("posting_backend_coordinate") != head["posting_backend_coordinate"]
+        or receipt.get("coverage") != head["coverage"]
+    ):
+        raise _refuse(
+            "PACKED_RECEIPT_MISMATCH",
+            "packed.receipt.outputs",
+            "the receipt does not describe the generation installed at this root",
+        )
+    summaries: dict[str, frozenset[str]] = {}
+    backend_count = len(head["backends"])
+    range_count = len(descriptors)
+    expected = {
+        "vector_member_sha256s": (
+            range_count * len(EMBEDDING_LAYERS) * backend_count,
+            range_count * len(EMBEDDING_LAYERS) * backend_count,
+        ),
+        "bound_member_sha256s": (range_count * backend_count, range_count * backend_count),
+        "posting_member_sha256s": (
+            range_count * MIN_POSTING_SEGMENTS,
+            range_count * MAX_POSTING_SEGMENTS,
+        ),
+    }
+    for name, (low, high) in expected.items():
+        values = outputs[name]
+        if not isinstance(values, list) or any(not _is_digest(value) for value in values):
+            raise _refuse(
+                "PACKED_RECEIPT_SCHEMA",
+                f"packed.receipt.outputs.{name}",
+                "a receipt binds each summary by a lowercase SHA-256",
+            )
+        if not low <= len(values) <= high:
+            raise _refuse(
+                "PACKED_SEARCH_UNBOUND_MEMBER",
+                f"packed.receipt.outputs.{name}",
+                "the receipt does not bind one summary per published range, backend and layer",
+            )
+        summaries[name] = frozenset(values)
+    return _Authenticated(
+        head=head,
+        head_sha256=head_sha256,
+        receipt_coordinate_sha256=coordinate,
+        descriptors=descriptors,
+        backends=tuple(head["backends"]),
+        posting_backend_coordinate=str(head["posting_backend_coordinate"]),
+        vector_payload_sha256s=summaries["vector_member_sha256s"],
+        posting_member_sha256s=summaries["posting_member_sha256s"],
+        bound_member_sha256s=summaries["bound_member_sha256s"],
+    )
+
+
+# ------------------------------------------------------------------------------------------
+# One range, read back against the chain that binds it
+# ------------------------------------------------------------------------------------------
+
+
+@dataclass(frozen=True)
+class _VerifiedRange:
+    descriptor: PackedRangeDescriptor
+    members: tuple[PackedMemberDescriptor, ...]
+
+
+def _verified_range(
+    root: _PackedRoot, authenticated: _Authenticated, descriptor: PackedRangeDescriptor
+) -> _VerifiedRange:
+    raw = root.read_member(
+        descriptor.manifest_sha256, kind="range", maximum=MAX_RANGE_MANIFEST_BYTES
+    )
+    if (
+        raw is None
+        or len(raw) != descriptor.manifest_bytes
+        or sha256_bytes(raw) != descriptor.manifest_sha256
+    ):
+        raise _refuse(
+            "PACKED_RANGE_DIGEST",
+            "packed.range.manifest",
+            "the installed range manifest is not the manifest the head binds",
+        )
+    try:
+        manifest = parse_canonical_json(raw)
+    except CanonicalJSONError as error:
+        raise _refuse(
+            "PACKED_RANGE_MANIFEST", "packed.range.manifest", "manifest is not canonical"
+        ) from error
+    if (
+        not isinstance(manifest, dict)
+        or set(manifest) != _RANGE_MANIFEST_MEMBERS
+        or manifest["schema_version"] != PACKED_RANGE_MANIFEST_SCHEMA
+        or not isinstance(manifest["members"], list)
+    ):
+        raise _refuse(
+            "PACKED_RANGE_MANIFEST", "packed.range.manifest", "range manifest contract differs"
+        )
+    body = {key: value for key, value in manifest.items() if key != "root_sha256"}
+    if canonical_sha256(body) != manifest["root_sha256"]:
+        raise _refuse(
+            "PACKED_RANGE_MANIFEST", "packed.range.manifest", "manifest root digest differs"
+        )
+    if not 1 <= len(manifest["members"]) <= MAX_RANGE_MEMBER_DESCRIPTORS:
+        raise _refuse(
+            "PACKED_RANGE_MEMBERS",
+            "packed.range.members",
+            f"a range manifest holds 1 to {MAX_RANGE_MEMBER_DESCRIPTORS} member descriptors",
+        )
+    if (
+        manifest["backends"] != [backend["coordinate"] for backend in authenticated.backends]
+        or manifest["posting_backend_coordinate"] != authenticated.posting_backend_coordinate
+    ):
+        raise _refuse(
+            "PACKED_RANGE_MANIFEST",
+            "packed.range.backends",
+            "a range names exactly the generation's backends and posting backend",
+        )
+    binding = range_binding_sha256(
+        range_index=manifest["range_index"],
+        first_key=manifest["first_key"],
+        last_key=manifest["last_key"],
+        entry_count=manifest["entry_count"],
+        facts_sha256=manifest["facts_sha256"],
+    )
+    if (
+        binding != manifest["range_binding_sha256"]
+        or manifest["range_index"] != descriptor.range_index
+        or manifest["first_key"] != descriptor.first_key
+        or manifest["last_key"] != descriptor.last_key
+        or manifest["entry_count"] != descriptor.entry_count
+        or manifest["facts_sha256"] != descriptor.facts_sha256
+        or binding != descriptor.range_binding_sha256
+        or len(manifest["members"]) != descriptor.member_count
+    ):
+        raise _refuse(
+            "PACKED_RANGE_MANIFEST",
+            "packed.range.range_binding_sha256",
+            "the range manifest does not describe the range its head descriptor names",
+        )
+    members = tuple(
+        member_descriptor_from_dict(value, path=f"packed.range.members[{index}]")
+        for index, value in enumerate(manifest["members"])
+    )
+    for member in members:
+        if (
+            member.range_index != descriptor.range_index
+            or member.first_key != descriptor.first_key
+            or member.last_key != descriptor.last_key
+            or member.entry_count != descriptor.entry_count
+            or member.facts_sha256 != descriptor.facts_sha256
+            or member.range_binding_sha256 != binding
+        ):
+            raise _refuse(
+                "PACKED_MEMBER_BINDING",
+                "packed.range.members[]",
+                "a member descriptor is bound to another range",
+            )
+    return _VerifiedRange(descriptor=descriptor, members=members)
+
+
+def _one_member(members: Sequence[PackedMemberDescriptor], kind: str) -> PackedMemberDescriptor:
+    found = [member for member in members if member.kind == kind]
+    if len(found) != 1:
+        raise _refuse(
+            "PACKED_RANGE_MEMBERS",
+            "packed.range.members[]",
+            f"a range carries exactly one {kind} member",
+        )
+    return found[0]
+
+
+def _member_bytes(root: _PackedRoot, member: PackedMemberDescriptor, *, maximum: int) -> bytes:
+    raw = root.read_member(member.sha256, kind=member.kind, maximum=maximum)
+    if raw is None or len(raw) != member.bytes or sha256_bytes(raw) != member.sha256:
+        raise _refuse(
+            "PACKED_MEMBER_DIGEST",
+            "packed.range.members[]",
+            "an installed member is not the member its descriptor binds",
+        )
+    return raw
+
+
+def _require_bound_summary(digest: str, bound: frozenset[str], *, path: str) -> None:
+    if digest not in bound:
+        raise _refuse(
+            "PACKED_SEARCH_UNBOUND_MEMBER",
+            path,
+            "this summary is not one the authenticated receipt binds",
+        )
+
+
+# ------------------------------------------------------------------------------------------
+# The facts member
+# ------------------------------------------------------------------------------------------
+
+
+@dataclass(frozen=True)
+class _FactsItem:
+    entry_id: str
+    semantic_facts_digest: str
+    entry_sha256: str
+    entry_json: str
+
+
+def _verified_facts(raw: bytes, descriptor: PackedRangeDescriptor) -> tuple[_FactsItem, ...]:
+    """Read one facts member under exactly the law ``packed_catalog`` publishes it by.
+
+    ``packed_catalog._verify_facts_member`` enforces the same law and returns only the entry ids;
+    this reader needs each entry's exact canonical text as well, and parsing an eight-mebibyte
+    member twice per scanned range is a cost a provider-scale search cannot pay. The two are
+    proved to agree, and to refuse the same corruptions, in ``test_catalog_packed_retrieval``.
+    """
+
+    try:
+        payload = parse_canonical_json(raw)
+    except CanonicalJSONError as error:
+        raise _refuse(
+            "PACKED_FACTS_MEMBER", "packed.range.facts", "facts member is not canonical"
+        ) from error
+    if (
+        not isinstance(payload, dict)
+        or payload.get("schema_version") != PACKED_FACTS_SCHEMA
+        or payload.get("range_index") != descriptor.range_index
+        or payload.get("entry_count") != descriptor.entry_count
+        or not isinstance(payload.get("entries"), list)
+        or len(payload["entries"]) != descriptor.entry_count
+    ):
+        raise _refuse("PACKED_FACTS_MEMBER", "packed.range.facts", "facts member contract differs")
+    items: list[_FactsItem] = []
+    keys: list[str] = []
+    previous: bytes | None = None
+    for position, item in enumerate(payload["entries"]):
+        path = f"packed.range.facts.entries[{position}]"
+        if not isinstance(item, dict) or set(item) != _FACTS_ENTRY_MEMBERS:
+            raise _refuse("PACKED_FACTS_MEMBER", path, "a facts entry contract differs")
+        if sha256_bytes(item["entry_json"].encode("utf-8")) != item["entry_sha256"]:
+            raise _refuse("PACKED_FACTS_MEMBER", path, "an entry is not the entry it digests to")
+        key = item["key"].encode("utf-8")
+        if previous is not None and key <= previous:
+            raise _refuse("PACKED_RANGE_ORDER", path, "a facts member ascends by key")
+        previous = key
+        keys.append(item["key"])
+        items.append(
+            _FactsItem(
+                entry_id=item["entry_id"],
+                semantic_facts_digest=item["semantic_facts_digest"],
+                entry_sha256=item["entry_sha256"],
+                entry_json=item["entry_json"],
+            )
+        )
+    if keys[0] != descriptor.first_key or keys[-1] != descriptor.last_key:
+        raise _refuse(
+            "PACKED_RANGE_ORDER",
+            "packed.range.facts",
+            "the facts member does not span the interval its range claims",
+        )
+    return tuple(items)
+
+
+def _rebuilt_entry(item: _FactsItem) -> CatalogEntryV2:
+    """Rebuild one carried entry under the exact v2 contract, and check it is the one named.
+
+    The digest beside it in the facts member is the delta's *classification* digest -- the one
+    ``streaming_delta`` computes over identity, facts and provenance while deliberately excluding
+    the version link, the observations and the vector instances. It is therefore not
+    ``CatalogEntryV2.semantic_facts_digest`` and is carried onward as the publisher stated it,
+    rather than recomputed here under a definition this module does not own.
+    """
+
+    try:
+        document = parse_canonical_json(item.entry_json.encode("utf-8"))
+    except CanonicalJSONError as error:
+        raise _refuse(
+            "PACKED_SEARCH_FACTS_ENTRY",
+            "packed.range.facts.entries[].entry_json",
+            "a carried entry is not canonical",
+        ) from error
+    if not isinstance(document, dict):
+        raise _refuse(
+            "PACKED_SEARCH_FACTS_ENTRY",
+            "packed.range.facts.entries[].entry_json",
+            "a carried entry is an object",
+        )
+    entry = catalog_entry_v2_from_dict(document)
+    if entry.entry_id != item.entry_id:
+        raise _refuse(
+            "PACKED_SEARCH_FACTS_ENTRY",
+            "packed.range.facts.entries[]",
+            "a carried entry is not the entry its facts member names",
+        )
+    return entry
+
+
+# ------------------------------------------------------------------------------------------
+# Exact scoring: postings when they are this backend's, packs otherwise
+# ------------------------------------------------------------------------------------------
+
+
+def _scores_from_postings(
+    root: _PackedRoot,
+    verified: _VerifiedRange,
+    authenticated: _Authenticated,
+    *,
+    query: Sequence[int],
+    budget: _Budget,
+    opened: list[str],
+) -> list[int]:
+    postings = [member for member in verified.members if member.kind == "posting"]
+    if not MIN_POSTING_SEGMENTS <= len(postings) <= MAX_POSTING_SEGMENTS:
+        raise _refuse(
+            "PACKED_POSTING_SEGMENTS",
+            "packed.range.members[]",
+            f"a range carries {MIN_POSTING_SEGMENTS} to {MAX_POSTING_SEGMENTS} posting segments",
+        )
+    entry_count = verified.descriptor.entry_count
+    layers = len(EMBEDDING_LAYERS)
+    accumulated = [[0] * layers for _ in range(entry_count)]
+    previous: tuple[int, int, int, int] | None = None
+    for expected_index, member in enumerate(postings):
+        if member.segment_index != expected_index:
+            raise _refuse(
+                "PACKED_POSTING_SEGMENTS",
+                "packed.range.members[]",
+                "posting segments are published in ascending segment order",
+            )
+        _require_bound_summary(
+            member.sha256,
+            authenticated.posting_member_sha256s,
+            path="packed.range.postings",
+        )
+        budget.spend_posting_terms(int(member.term_count or 0))
+        raw = _member_bytes(root, member, maximum=MAX_POSTING_SEGMENT_BYTES)
+        segment = parse_posting_segment(raw, descriptor=member)
+        if member.term_count != len(segment.terms):
+            raise _refuse(
+                "PACKED_POSTING_TERM",
+                "packed.range.members[]",
+                "a posting descriptor's term count differs from its segment",
+            )
+        if previous is not None and segment.terms and segment.terms[0] <= previous:
+            raise _refuse(
+                "PACKED_POSTING_ORDER",
+                "packed.range.members[]",
+                "posting terms ascend across segment boundaries too",
+            )
+        for dimension, ordinal, layer_ordinal, value in segment.terms:
+            weight = query[dimension]
+            if weight:
+                accumulated[ordinal][layer_ordinal] += weight * value
+        if segment.terms:
+            previous = segment.terms[-1]
+        opened.append(member.sha256)
+    return [max(row) for row in accumulated]
+
+
+def _scores_from_packs(
+    root: _PackedRoot,
+    verified: _VerifiedRange,
+    authenticated: _Authenticated,
+    *,
+    query: Sequence[int],
+    backend_coordinate: str,
+    opened: list[str],
+) -> list[int]:
+    entry_count = verified.descriptor.entry_count
+    best: list[int | None] = [None] * entry_count
+    seen: set[str] = set()
+    for layer in EMBEDDING_LAYERS:
+        member = _one_layer_member(verified.members, layer=layer, coordinate=backend_coordinate)
+        raw = _member_bytes(root, member, maximum=MAX_VECTOR_MEMBER_BYTES)
+        payload_sha256 = sha256_bytes(raw[MEMBER_HEADER_BYTES:])
+        _require_bound_summary(
+            payload_sha256,
+            authenticated.vector_payload_sha256s,
+            path="packed.range.vectors",
+        )
+        parsed = parse_vector_member(raw, descriptor=member)
+        if parsed.entry_count != entry_count or layer in seen:
+            raise _refuse(
+                "PACKED_MEMBER_LAYER",
+                "packed.range.members[]",
+                "a backend carries each layer exactly once, over this range's own entries",
+            )
+        seen.add(layer)
+        for ordinal, vector in enumerate(parsed.vectors):
+            total = 0
+            for weight, value in zip(query, vector, strict=True):
+                total += weight * value
+            current = best[ordinal]
+            if current is None or total > current:
+                best[ordinal] = total
+        opened.append(payload_sha256)
+    return [0 if value is None else value for value in best]
+
+
+def _one_layer_member(
+    members: Sequence[PackedMemberDescriptor], *, layer: str, coordinate: str
+) -> PackedMemberDescriptor:
+    found = [
+        member
+        for member in members
+        if member.kind == "vector"
+        and member.layer == layer
+        and member.backend_coordinate == coordinate
+    ]
+    if len(found) != 1:
+        raise _refuse(
+            "PACKED_MEMBER_LAYER",
+            "packed.range.members[]",
+            f"this range carries no single {layer!r} pack for the selected backend",
+        )
+    return found[0]
+
+
+# ------------------------------------------------------------------------------------------
+# The search
+# ------------------------------------------------------------------------------------------
+
+
+@dataclass(frozen=True)
+class _Candidate:
+    """One entry that scored above zero, ordered by score descending then entry id ascending."""
+
+    negated: int
+    entry_id: str
+    range_index: int
+    item: _FactsItem
+
+
+def rank_packed_entries(
+    *,
+    root: Path,
+    expected_head_sha256: str,
+    receipt: Mapping[str, Any],
+    question: str,
+    backend: EmbeddingBackend,
+    limit: int,
+    work_limits: CatalogSearchWorkLimits,
+) -> PackedRetrievalResult:
+    """Answer one question from one authenticated packed generation, or say what it could not do."""
+
+    if not isinstance(root, Path):
+        raise _refuse("PACKED_SEARCH_ROOT", "root", "must be a pathlib.Path")
+    if not isinstance(work_limits, CatalogSearchWorkLimits):
+        raise _refuse("PACKED_SEARCH_LIMIT", "work_limits", "must be a CatalogSearchWorkLimits")
+    if type(limit) is not int or not 1 <= limit <= MAX_RETRIEVAL_LIMIT:
+        raise _refuse(
+            "RETRIEVAL_LIMIT", "limit", f"must be an integer in [1, {MAX_RETRIEVAL_LIMIT}]"
+        )
+    if not isinstance(question, str) or len(question) > MAX_QUERY_CHARS:
+        raise _refuse(
+            "RETRIEVAL_QUERY_LIMIT",
+            "question",
+            f"a question is a string of at most {MAX_QUERY_CHARS} characters",
+        )
+
+    if not _is_digest(expected_head_sha256):
+        raise _refuse("PACKED_HEAD_EXPECTED", "expected_head_sha256", "must be a lowercase SHA-256")
+    receipt_coordinate = _receipt_coordinate(receipt)
+    coordinate = backend.descriptor.coordinate
+
+    budget = _Budget(work_limits)
+    question_digest = canonical_sha256({"question": question})
+    reader = _PackedRoot(root, budget)
+    manifests: list[str] = []
+    vectors: list[str] = []
+    postings: list[str] = []
+    bounds: list[str] = []
+    entries: tuple[PackedRankedEntry, ...] = ()
+    incomplete: str | None = None
+    try:
+        with reader.opened() as opened_root:
+            authenticated = _authenticate(
+                opened_root,
+                expected_head_sha256=expected_head_sha256,
+                receipt=receipt,
+                coordinate=receipt_coordinate,
+            )
+            coordinate = _selected_backend_coordinate(authenticated, backend)
+            query = _encoded_query(backend, question, budget=budget)
+            if any(query):
+                entries = _search(
+                    opened_root,
+                    authenticated,
+                    query=query,
+                    coordinate=coordinate,
+                    limit=limit,
+                    budget=budget,
+                    manifests=manifests,
+                    vectors=vectors,
+                    postings=postings,
+                    bounds=bounds,
+                )
+    except _Exhausted as exhausted:
+        incomplete = exhausted.budget
+        entries = ()
+    return PackedRetrievalResult(
+        status="incomplete" if incomplete is not None else "complete",
+        incomplete_code=incomplete,
+        head_sha256=expected_head_sha256,
+        receipt_coordinate_sha256=receipt_coordinate,
+        backend_coordinate=coordinate,
+        question_digest=question_digest,
+        limit=limit,
+        range_manifest_sha256s=tuple(manifests),
+        vector_member_sha256s=tuple(vectors),
+        posting_member_sha256s=tuple(postings),
+        bound_member_sha256s=tuple(bounds),
+        entries=entries,
+        limits=work_limits,
+        work=budget.work(),
+    )
+
+
+def _selected_backend_coordinate(authenticated: _Authenticated, backend: EmbeddingBackend) -> str:
+    descriptor = backend.descriptor
+    coordinate = descriptor.coordinate
+    for published in authenticated.backends:
+        if published["coordinate"] != coordinate:
+            continue
+        if (
+            published["dimensions"] != descriptor.dimensions
+            or published["quantization"] != descriptor.quantization
+        ):
+            raise _refuse(
+                "PACKED_SEARCH_BACKEND",
+                "backend",
+                "the selected encoder is not the published backend of that coordinate",
+            )
+        return coordinate
+    raise _refuse(
+        "PACKED_SEARCH_BACKEND",
+        "backend",
+        "this generation publishes no packs for the selected backend coordinate",
+    )
+
+
+def _encoded_query(backend: EmbeddingBackend, question: str, *, budget: _Budget) -> tuple[int, ...]:
+    budget.spend_query_encode()
+    asked = backend.encode(question)
+    dimensions = backend.descriptor.dimensions
+    if (
+        not isinstance(asked, tuple)
+        or len(asked) != dimensions
+        or any(type(value) is not int for value in asked)
+    ):
+        raise _refuse(
+            "RETRIEVAL_QUERY_VECTOR",
+            "question",
+            "the selected backend returned a vector outside its exact integer coordinate",
+        )
+    return asked
+
+
+def _search(
+    root: _PackedRoot,
+    authenticated: _Authenticated,
+    *,
+    query: tuple[int, ...],
+    coordinate: str,
+    limit: int,
+    budget: _Budget,
+    manifests: list[str],
+    vectors: list[str],
+    postings: list[str],
+    bounds: list[str],
+) -> tuple[PackedRankedEntry, ...]:
+    """One bound pass to order the work, one exact pass over whatever survives pruning."""
+
+    range_bounds: list[int] = []
+    for descriptor in authenticated.descriptors:
+        budget.check_time()
+        budget.spend_range_bounded()
+        verified = _verified_range(root, authenticated, descriptor)
+        manifests.append(descriptor.manifest_sha256)
+        member = _one_backend_member(verified.members, kind="bound", coordinate=coordinate)
+        _require_bound_summary(
+            member.sha256, authenticated.bound_member_sha256s, path="packed.range.bounds"
+        )
+        raw = _member_bytes(root, member, maximum=bound_segment_bytes(dimensions=len(query)))
+        segment = parse_bound_segment(raw, descriptor=member)
+        range_bounds.append(range_upper_bound(query, segment.bounds))
+        bounds.append(member.sha256)
+
+    order = sorted(
+        range(len(authenticated.descriptors)),
+        key=lambda index: (-range_bounds[index], index),
+    )
+    selected: list[_Candidate] = []
+    for index in order:
+        if len(selected) == limit and range_bounds[index] < -selected[limit - 1].negated:
+            budget.note_pruned()
+            continue
+        descriptor = authenticated.descriptors[index]
+        budget.check_time()
+        budget.spend_range_scanned()
+        budget.spend_candidates(descriptor.entry_count)
+        verified = _verified_range(root, authenticated, descriptor)
+        facts = _one_member(verified.members, "facts")
+        items = _verified_facts(
+            _member_bytes(root, facts, maximum=MAX_FACTS_MEMBER_BYTES), descriptor
+        )
+        if coordinate == authenticated.posting_backend_coordinate:
+            scores = _scores_from_postings(
+                root, verified, authenticated, query=query, budget=budget, opened=postings
+            )
+        else:
+            scores = _scores_from_packs(
+                root,
+                verified,
+                authenticated,
+                query=query,
+                backend_coordinate=coordinate,
+                opened=vectors,
+            )
+        if len(scores) != len(items):
+            raise _refuse(
+                "PACKED_SEARCH_FACTS_ENTRY",
+                "packed.range.facts",
+                "this range's packs and its facts member describe different entry counts",
+            )
+        found = [
+            _Candidate(
+                negated=-score,
+                entry_id=item.entry_id,
+                range_index=descriptor.range_index,
+                item=item,
+            )
+            for score, item in zip(scores, items, strict=True)
+            if score > 0
+        ]
+        found.sort(key=lambda candidate: (candidate.negated, candidate.entry_id))
+        selected = sorted(
+            [*selected, *found[:limit]],
+            key=lambda candidate: (candidate.negated, candidate.entry_id),
+        )[:limit]
+    return tuple(
+        PackedRankedEntry(
+            rank=rank,
+            entry_id=candidate.entry_id,
+            entry_coordinate=entry.coordinate,
+            entry_digest=entry.digest,
+            semantic_facts_digest=candidate.item.semantic_facts_digest,
+            range_index=candidate.range_index,
+            entry=entry,
+        )
+        for rank, (candidate, entry) in enumerate(
+            ((candidate, _rebuilt_entry(candidate.item)) for candidate in selected), start=1
+        )
+    )
+
+
+def _one_backend_member(
+    members: Sequence[PackedMemberDescriptor], *, kind: str, coordinate: str
+) -> PackedMemberDescriptor:
+    found = [
+        member
+        for member in members
+        if member.kind == kind and member.backend_coordinate == coordinate
+    ]
+    if len(found) != 1:
+        raise _refuse(
+            "PACKED_RANGE_MEMBERS",
+            "packed.range.members[]",
+            f"a range carries exactly one {kind} member per backend",
+        )
+    return found[0]
+
+
+__all__ = [
+    "MAX_WORK_CANDIDATES",
+    "MAX_WORK_ELAPSED_SECONDS",
+    "MAX_WORK_MEMBER_BYTES",
+    "MAX_WORK_OPEN_FILES",
+    "MAX_WORK_PACKS",
+    "MAX_WORK_POSTING_TERMS",
+    "MAX_WORK_QUERY_ENCODES",
+    "MAX_WORK_RANGES",
+    "MIN_WORK_OPEN_FILES",
+    "PACKED_INCOMPLETE_CODES",
+    "PACKED_RECEIPT_SCHEMA",
+    "PACKED_SEARCH_RESULT_SCHEMA",
+    "PUBLIC_STORE_KINDS",
+    "CatalogSearchWorkLimits",
+    "PackedRankedEntry",
+    "PackedRetrievalResult",
+    "PackedSearchWork",
+    "detect_public_store_kind",
+    "rank_packed_entries",
+]