mostlyright-data 0.9.0__py3-none-any.whl

mostlyright/data_harness/sources/catalog/packed_catalog.py

@@ -0,0 +1,2345 @@
+"""Range-local packed catalogs: fixed-width vector packs, exact postings, conservative bounds.
+
+The v2 retrieval manifest in :mod:`retrieval_manifest` describes one representation as a flat member
+list.  At provider scale that shape stops working: four corpus-wide packs would each be gigabytes,
+no reader could bound its own allocation from a descriptor, and a single mutated byte anywhere would
+be indistinguishable from a legitimate republication. This module owns packed generations; the
+flat v1/v2 contract and its constants remain scoped to :mod:`retrieval_manifest`.
+
+*A range is the unit.*  Sorted entries are grouped into consecutive ranges of exactly
+``RANGE_ENTRIES`` -- only the final range is short -- and each range owns one facts member, one
+history member, four layer-specific vector members per available backend, one to eight lexical
+posting segments, and one bound segment per backend.  There are never four corpus-wide packs.
+
+*Every member has an exact byte law.*  A vector member is exactly
+``64 + entry_count * dimension * 4`` bytes; a bound segment is exactly
+``64 + 4 * dimension * 2 * 4`` bytes; a posting term is exactly ten bytes.  That is what lets a
+reader refuse a member from its 64-byte header before it allocates anything the member claims to
+contain, and it is why the ceilings in this module are laws rather than guidance: a 1000-entry
+range at the 384-dimension ceiling is 1,536,064 bytes per layer member and cannot be anything
+else.
+
+*Nothing derived is trusted.*  Posting segments and bound segments are accelerators, and an
+accelerator that lies changes which entries a bounded search ever looks at.  So
+:func:`verify_packed_generation` recomputes both from the exact vector member bytes and refuses a
+summary that is not the publisher's exact one.  It refuses a *non-conservative* bound with its own
+code, because a bound that is too narrow hides a true hit while a merely wrong one only wastes a
+scan.
+
+*The bound is the one number this module computes.*  Exact entry scores belong to the ranker and die
+there.  What a published range can carry is the summary side of that score:
+:func:`conservative_upper_bound` is ``sum_i(q_i * max_i)`` where ``q_i >= 0`` and
+``sum_i(q_i * min_i)`` otherwise, and :func:`range_upper_bound` maximizes it across the four
+layers.  Pruning on it must be strict -- an equal bound still exact-scans, because a tie is broken
+by entry id and a pruned range cannot present its ids.
+
+Fixed-endian tables and canonical JSON only.  No pickle, no memory mapping, no length a reader
+learns after it has already allocated.
+"""
+
+from __future__ import annotations
+
+import contextlib
+import os
+import re
+import secrets
+import stat
+import struct
+from collections.abc import Iterator, Mapping, Sequence
+from dataclasses import dataclass, replace
+from pathlib import Path
+from typing import Any
+
+from mostlyright.data_harness.canonical import (
+    CanonicalJSONError,
+    canonical_json_bytes,
+    canonical_sha256,
+    parse_canonical_json,
+    sha256_bytes,
+)
+from mostlyright.data_harness.sources.catalog.bounded_io import (
+    BoundedReadFailure,
+    read_bounded_at,
+)
+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 BatchEncodeResult, EmbeddingBackend
+from mostlyright.data_harness.sources.contracts import SourceContractError
+
+PACKED_HEAD_SCHEMA = "harness-catalog-packed-head.v1"
+PACKED_RANGE_MANIFEST_SCHEMA = "harness-catalog-packed-range.v1"
+PACKED_FACTS_SCHEMA = "harness-catalog-packed-facts.v1"
+PACKED_HISTORY_SCHEMA = "harness-catalog-packed-history.v1"
+
+PACKED_HEAD_FILENAME = "packed-head.json"
+PACKED_MEMBERS_DIRNAME = "members"
+
+#: One range is exactly this many entries. Only the final range of a generation is shorter, and a
+#: publisher that would rather split a range than refuse an oversized member changes the call bound
+#: the whole design rests on -- so it refuses instead.
+RANGE_ENTRIES = 1_000
+
+MAX_RANGE_DESCRIPTORS = 1_024
+MAX_RANGE_DESCRIPTOR_BYTES = 2_048
+MAX_PACKED_HEAD_BYTES = 4 * 1024 * 1024
+
+MAX_FACTS_MEMBER_BYTES = 8 * 1024 * 1024
+MAX_HISTORY_MEMBER_BYTES = 8 * 1024 * 1024
+
+MAX_RANGE_MANIFEST_BYTES = 64 * 1024
+MAX_RANGE_MEMBER_DESCRIPTORS = 24
+MAX_MEMBER_DESCRIPTOR_BYTES = 1_024
+
+#: The widest backend this format admits. 384 is the MiniLM coordinate's dimension, and the number
+#: is a law rather than a default: it is what makes the vector-member ceiling a constant.
+MAX_BACKEND_DIMENSION = 384
+MEMBER_HEADER_BYTES = 64
+MAX_VECTOR_MEMBER_BYTES = MEMBER_HEADER_BYTES + RANGE_ENTRIES * MAX_BACKEND_DIMENSION * 4
+
+BOUND_SEGMENT_LAYERS = len(EMBEDDING_LAYERS)
+MIN_POSTING_SEGMENTS = 1
+MAX_POSTING_SEGMENTS = 8
+MAX_POSTING_SEGMENT_BYTES = 4 * 1024 * 1024
+POSTING_TERM_FORMAT = ">HHBxi"
+POSTING_TERM_BYTES = struct.calcsize(POSTING_TERM_FORMAT)
+MAX_POSTING_SEGMENT_TERMS = (MAX_POSTING_SEGMENT_BYTES - MEMBER_HEADER_BYTES) // POSTING_TERM_BYTES
+
+#: Two backends (one query-safe lexical, one governed neural) is what the 24-descriptor range
+#: manifest admits alongside eight posting segments. A third would not fit, and widening the
+#: manifest to make it fit would widen every reader's allocation ceiling.
+MAX_PACKED_BACKENDS = 2
+
+PACKED_CLASSIFICATIONS = ("new", "changed", "unchanged")
+MEMBER_KINDS = ("facts", "history", "vector", "posting", "bound", "range")
+_BINARY_KINDS = ("vector", "posting", "bound")
+
+MIN_INT32 = -(1 << 31)
+MAX_INT32 = (1 << 31) - 1
+
+PACKED_FORMAT_VERSION = 1
+MEMBER_MAGIC = b"MRPACKD1"
+_HEADER_FORMAT = ">8sHHHHIIII16s16s"
+_KIND_CODES = {"vector": 1, "posting": 2, "bound": 3}
+_KIND_NAMES = {code: name for name, code in _KIND_CODES.items()}
+SUBINDEX_NONE = 0xFFFF
+
+_OPEN_DIRECTORY = os.O_RDONLY | getattr(os, "O_DIRECTORY", 0) | getattr(os, "O_NOFOLLOW", 0)
+_OPEN_MEMBER = os.O_RDONLY | getattr(os, "O_NOFOLLOW", 0) | getattr(os, "O_CLOEXEC", 0)
+
+_SHA256 = re.compile(r"^[0-9a-f]{64}$")
+
+
+class CatalogPackedRefused(SourceContractError):
+    """A stable refusal of a packed member, descriptor, manifest, head, or durable output."""
+
+
+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 _SHA256.fullmatch(value) is not None
+
+
+# ------------------------------------------------------------------------------------------
+# Exact byte laws
+# ------------------------------------------------------------------------------------------
+
+
+def vector_member_bytes(*, entry_count: int, dimensions: int) -> int:
+    """The exact size of one layer-specific vector member. There is no other admissible size."""
+
+    return MEMBER_HEADER_BYTES + entry_count * dimensions * 4
+
+
+def bound_segment_bytes(*, dimensions: int) -> int:
+    """The exact size of one backend's bound segment: four layers of per-dimension min and max."""
+
+    return MEMBER_HEADER_BYTES + BOUND_SEGMENT_LAYERS * dimensions * 2 * 4
+
+
+def member_filename(kind: str, sha256: str) -> str:
+    """Content-addressed member name. Binary tables and canonical JSON never share an extension."""
+
+    if kind not in MEMBER_KINDS:
+        raise _refuse("PACKED_MEMBER_KIND", "packed.member.kind", f"unknown member kind {kind!r}")
+    if not _is_digest(sha256):
+        raise _refuse("PACKED_MEMBER_DIGEST", "packed.member.sha256", "must be a lowercase SHA-256")
+    return f"{sha256}.bin" if kind in _BINARY_KINDS else f"{sha256}.json"
+
+
+def _check_dimensions(dimensions: Any, path: str) -> int:
+    if type(dimensions) is not int or not 1 <= dimensions <= MAX_BACKEND_DIMENSION:
+        raise _refuse(
+            "PACKED_MEMBER_DIMENSION",
+            path,
+            f"a packed backend dimension must be an integer in [1, {MAX_BACKEND_DIMENSION}]",
+        )
+    return dimensions
+
+
+def _check_entry_count(entry_count: Any, path: str) -> int:
+    if type(entry_count) is not int or not 1 <= entry_count <= RANGE_ENTRIES:
+        raise _refuse(
+            "PACKED_MEMBER_ENTRY_COUNT",
+            path,
+            f"a range carries 1 to {RANGE_ENTRIES} entries",
+        )
+    return entry_count
+
+
+# ------------------------------------------------------------------------------------------
+# The 64-byte fixed-endian member header
+# ------------------------------------------------------------------------------------------
+
+
+@dataclass(frozen=True)
+class PackedMemberHeader:
+    """Everything a reader must know before it allocates one byte of a member's payload."""
+
+    kind: str
+    subindex: int
+    dimensions: int
+    entry_count: int
+    term_count: int
+    range_index: int
+    payload_bytes: int
+    binding_prefix: bytes
+    backend_prefix: bytes
+
+
+def _binding_prefix(binding_sha256: str) -> bytes:
+    if not _is_digest(binding_sha256):
+        raise _refuse(
+            "PACKED_MEMBER_BINDING",
+            "packed.member.range_binding_sha256",
+            "a member binds its range by that range's exact binding digest",
+        )
+    return bytes.fromhex(binding_sha256)[:16]
+
+
+def _backend_prefix(backend_coordinate: str) -> bytes:
+    if not isinstance(backend_coordinate, str) or not backend_coordinate:
+        raise _refuse(
+            "PACKED_MEMBER_BINDING",
+            "packed.member.backend_coordinate",
+            "a member binds the exact backend coordinate that produced it",
+        )
+    return bytes.fromhex(sha256_bytes(backend_coordinate.encode("utf-8")))[:16]
+
+
+def pack_member_header(
+    *,
+    kind: str,
+    subindex: int,
+    dimensions: int,
+    entry_count: int,
+    term_count: int,
+    range_index: int,
+    payload_bytes: int,
+    binding_sha256: str,
+    backend_coordinate: str,
+) -> bytes:
+    """Build one exact 64-byte member header. Fixed big-endian, no padding a reader must guess."""
+
+    if kind not in _KIND_CODES:
+        raise _refuse("PACKED_MEMBER_KIND", "packed.member.kind", f"unknown member kind {kind!r}")
+    if type(range_index) is not int or not 0 <= range_index < MAX_RANGE_DESCRIPTORS:
+        raise _refuse(
+            "PACKED_MEMBER_HEADER",
+            "packed.member.range_index",
+            f"a range index must be an integer in [0, {MAX_RANGE_DESCRIPTORS - 1}]",
+        )
+    if type(subindex) is not int or not 0 <= subindex <= SUBINDEX_NONE:
+        raise _refuse(
+            "PACKED_MEMBER_HEADER", "packed.member.subindex", "a member subindex is a uint16"
+        )
+    raw = struct.pack(
+        _HEADER_FORMAT,
+        MEMBER_MAGIC,
+        PACKED_FORMAT_VERSION,
+        _KIND_CODES[kind],
+        subindex,
+        dimensions,
+        entry_count,
+        term_count,
+        range_index,
+        payload_bytes,
+        _binding_prefix(binding_sha256),
+        _backend_prefix(backend_coordinate),
+    )
+    if len(raw) != MEMBER_HEADER_BYTES:  # pragma: no cover - the format is fixed
+        raise _refuse("PACKED_MEMBER_HEADER", "packed.member", "header is not exactly 64 bytes")
+    return raw
+
+
+def parse_member_header(raw: bytes) -> PackedMemberHeader:
+    """Read the fixed header, or refuse. Nothing is allocated from a value read after this."""
+
+    if not isinstance(raw, bytes | bytearray | memoryview):
+        raise _refuse("PACKED_MEMBER_HEADER", "packed.member", "a member is raw bytes")
+    raw = bytes(raw)
+    if len(raw) < MEMBER_HEADER_BYTES:
+        raise _refuse(
+            "PACKED_MEMBER_TRUNCATED",
+            "packed.member",
+            f"a member is at least its {MEMBER_HEADER_BYTES}-byte header",
+        )
+    (
+        magic,
+        version,
+        kind_code,
+        subindex,
+        dimensions,
+        entry_count,
+        term_count,
+        range_index,
+        payload_bytes,
+        binding_prefix,
+        backend_prefix,
+    ) = struct.unpack(_HEADER_FORMAT, raw[:MEMBER_HEADER_BYTES])
+    if magic != MEMBER_MAGIC:
+        raise _refuse("PACKED_MEMBER_MAGIC", "packed.member.magic", "not a packed catalog member")
+    if version != PACKED_FORMAT_VERSION:
+        raise _refuse(
+            "PACKED_MEMBER_VERSION",
+            "packed.member.format_version",
+            f"this reader reads format version {PACKED_FORMAT_VERSION} only",
+        )
+    if kind_code not in _KIND_NAMES:
+        raise _refuse("PACKED_MEMBER_KIND", "packed.member.kind", "unknown member kind code")
+    _check_dimensions(dimensions, "packed.member.dimensions")
+    _check_entry_count(entry_count, "packed.member.entry_count")
+    if range_index >= MAX_RANGE_DESCRIPTORS:
+        raise _refuse(
+            "PACKED_MEMBER_HEADER", "packed.member.range_index", "range index exceeds its bound"
+        )
+    return PackedMemberHeader(
+        kind=_KIND_NAMES[kind_code],
+        subindex=subindex,
+        dimensions=dimensions,
+        entry_count=entry_count,
+        term_count=term_count,
+        range_index=range_index,
+        payload_bytes=payload_bytes,
+        binding_prefix=binding_prefix,
+        backend_prefix=backend_prefix,
+    )
+
+
+def _payload(raw: bytes, header: PackedMemberHeader, *, expected_payload: int) -> bytes:
+    if header.payload_bytes != expected_payload:
+        raise _refuse(
+            "PACKED_MEMBER_HEADER",
+            "packed.member.payload_bytes",
+            "the declared payload length disagrees with this member's exact byte law",
+        )
+    total = MEMBER_HEADER_BYTES + expected_payload
+    if len(raw) < total:
+        raise _refuse(
+            "PACKED_MEMBER_TRUNCATED",
+            "packed.member",
+            "the member ends before its declared payload",
+        )
+    if len(raw) > total:
+        raise _refuse(
+            "PACKED_MEMBER_EXCESS",
+            "packed.member",
+            "a member is exactly its header plus its payload; trailing bytes are refused",
+        )
+    return raw[MEMBER_HEADER_BYTES:]
+
+
+def _check_binding(
+    header: PackedMemberHeader,
+    descriptor: PackedMemberDescriptor | None,
+    *,
+    kind: str,
+) -> None:
+    if header.kind != kind:
+        raise _refuse(
+            "PACKED_MEMBER_KIND",
+            "packed.member.kind",
+            f"this member is a {header.kind} member, not a {kind} member",
+        )
+    if descriptor is None:
+        return
+    if descriptor.kind != kind:
+        raise _refuse(
+            "PACKED_MEMBER_KIND", "packed.member.kind", "the descriptor names another member kind"
+        )
+    if kind == "vector" and descriptor.layer != EMBEDDING_LAYERS[header.subindex]:
+        raise _refuse(
+            "PACKED_MEMBER_LAYER",
+            "packed.member.layer",
+            "this member carries another layer than the descriptor binds",
+        )
+    if kind == "posting" and descriptor.segment_index != header.subindex:
+        raise _refuse(
+            "PACKED_MEMBER_BINDING",
+            "packed.member.segment_index",
+            "this posting segment is not the segment the descriptor binds",
+        )
+    if (
+        descriptor.range_index != header.range_index
+        or descriptor.entry_count != header.entry_count
+        or descriptor.dimensions != header.dimensions
+        or _binding_prefix(descriptor.range_binding_sha256) != header.binding_prefix
+        or _backend_prefix(descriptor.backend_coordinate or "") != header.backend_prefix
+    ):
+        raise _refuse(
+            "PACKED_MEMBER_BINDING",
+            "packed.member",
+            "this member is bound to another range, entry order, or backend",
+        )
+
+
+# ------------------------------------------------------------------------------------------
+# Vector members
+# ------------------------------------------------------------------------------------------
+
+
+@dataclass(frozen=True)
+class PackedVectorMember:
+    """One layer's exact integer vectors for one range and one backend, in range entry order."""
+
+    layer: str
+    dimensions: int
+    entry_count: int
+    range_index: int
+    vectors: tuple[tuple[int, ...], ...]
+
+
+def pack_vector_member(
+    vectors: Sequence[Sequence[int]],
+    *,
+    layer: str,
+    dimensions: int,
+    range_index: int,
+    binding_sha256: str,
+    backend_coordinate: str,
+) -> bytes:
+    """Serialize one layer's vectors as a fixed-width big-endian int32 table."""
+
+    _check_dimensions(dimensions, "packed.vector.dimensions")
+    if layer not in EMBEDDING_LAYERS:
+        raise _refuse(
+            "PACKED_MEMBER_LAYER",
+            "packed.vector.layer",
+            f"a layer member names one of {list(EMBEDDING_LAYERS)}",
+        )
+    entry_count = _check_entry_count(len(vectors), "packed.vector.entry_count")
+    payload = bytearray()
+    for ordinal, vector in enumerate(vectors):
+        if len(vector) != dimensions:
+            raise _refuse(
+                "PACKED_MEMBER_DIMENSION",
+                f"packed.vector[{ordinal}]",
+                "every vector in a member has exactly the backend's dimension",
+            )
+        for value in vector:
+            if type(value) is not int or not MIN_INT32 <= value <= MAX_INT32:
+                raise _refuse(
+                    "PACKED_VECTOR_VALUE",
+                    f"packed.vector[{ordinal}]",
+                    "a packed vector holds exact int32 values only",
+                )
+        payload += struct.pack(f">{dimensions}i", *vector)
+    header = pack_member_header(
+        kind="vector",
+        subindex=EMBEDDING_LAYERS.index(layer),
+        dimensions=dimensions,
+        entry_count=entry_count,
+        term_count=0,
+        range_index=range_index,
+        payload_bytes=len(payload),
+        binding_sha256=binding_sha256,
+        backend_coordinate=backend_coordinate,
+    )
+    raw = header + bytes(payload)
+    if len(raw) != vector_member_bytes(entry_count=entry_count, dimensions=dimensions):
+        raise _refuse(  # pragma: no cover - the arithmetic above is the law
+            "PACKED_MEMBER_HEADER", "packed.vector", "vector member violated its exact byte law"
+        )
+    if len(raw) > MAX_VECTOR_MEMBER_BYTES:  # pragma: no cover - implied by the two ceilings
+        raise _refuse("PACKED_MEMBER_LIMIT", "packed.vector", "vector member exceeds its ceiling")
+    return raw
+
+
+def parse_vector_member(
+    raw: bytes, *, descriptor: PackedMemberDescriptor | None = None
+) -> PackedVectorMember:
+    """Read one vector member exactly, or refuse it. Never partially."""
+
+    header = parse_member_header(raw)
+    _check_binding(header, descriptor, kind="vector")
+    if header.subindex >= len(EMBEDDING_LAYERS):
+        raise _refuse(
+            "PACKED_MEMBER_LAYER", "packed.vector.layer", "layer ordinal is outside layer closure"
+        )
+    if header.term_count != 0:
+        raise _refuse(
+            "PACKED_MEMBER_HEADER", "packed.vector.term_count", "a vector member carries no terms"
+        )
+    expected = header.entry_count * header.dimensions * 4
+    payload = _payload(bytes(raw), header, expected_payload=expected)
+    vectors: list[tuple[int, ...]] = []
+    stride = header.dimensions * 4
+    for ordinal in range(header.entry_count):
+        chunk = payload[ordinal * stride : (ordinal + 1) * stride]
+        vectors.append(struct.unpack(f">{header.dimensions}i", chunk))
+    return PackedVectorMember(
+        layer=EMBEDDING_LAYERS[header.subindex],
+        dimensions=header.dimensions,
+        entry_count=header.entry_count,
+        range_index=header.range_index,
+        vectors=tuple(vectors),
+    )
+
+
+# ------------------------------------------------------------------------------------------
+# Lexical posting segments
+# ------------------------------------------------------------------------------------------
+
+
+PostingTerm = tuple[int, int, int, int]
+
+
+@dataclass(frozen=True)
+class PackedPostingSegment:
+    """One bounded run of canonical ``(dimension, entry ordinal, layer ordinal, value)`` terms."""
+
+    segment_index: int
+    dimensions: int
+    entry_count: int
+    range_index: int
+    terms: tuple[PostingTerm, ...]
+
+
+def compute_layer_postings(
+    vectors_by_layer: Mapping[str, Sequence[Sequence[int]]], *, dimensions: int
+) -> tuple[PostingTerm, ...]:
+    """Derive this range's canonical posting terms from its exact layer vectors.
+
+    A zero contributes nothing to any dot product, so it is not a term. Everything else is, and the
+    order is total: dimension, then entry ordinal, then layer ordinal.
+    """
+
+    _check_dimensions(dimensions, "packed.postings.dimensions")
+    terms: list[PostingTerm] = []
+    for layer_ordinal, layer in enumerate(EMBEDDING_LAYERS):
+        vectors = vectors_by_layer.get(layer)
+        if vectors is None:
+            raise _refuse(
+                "PACKED_MEMBER_LAYER",
+                "packed.postings.layers",
+                f"postings require exactly the four layers {list(EMBEDDING_LAYERS)}",
+            )
+        for ordinal, vector in enumerate(vectors):
+            for dimension, value in enumerate(vector):
+                if value:
+                    terms.append((dimension, ordinal, layer_ordinal, value))
+    terms.sort()
+    return tuple(terms)
+
+
+def segment_posting_terms(
+    terms: Sequence[PostingTerm], *, max_terms_per_segment: int | None = None
+) -> tuple[tuple[PostingTerm, ...], ...]:
+    """Split canonical terms into 1-8 bounded segments, or refuse rather than widen the cap."""
+
+    limit = MAX_POSTING_SEGMENT_TERMS if max_terms_per_segment is None else max_terms_per_segment
+    if type(limit) is not int or not 1 <= limit <= MAX_POSTING_SEGMENT_TERMS:
+        raise _refuse(
+            "PACKED_POSTING_SEGMENTS",
+            "packed.postings.max_terms_per_segment",
+            f"a segment carries 1 to {MAX_POSTING_SEGMENT_TERMS} terms",
+        )
+    segments = tuple(
+        tuple(terms[start : start + limit]) for start in range(0, max(len(terms), 1), limit)
+    )
+    if not MIN_POSTING_SEGMENTS <= len(segments) <= MAX_POSTING_SEGMENTS:
+        raise _refuse(
+            "PACKED_POSTING_SEGMENTS",
+            "packed.postings.segments",
+            f"a range carries {MIN_POSTING_SEGMENTS} to {MAX_POSTING_SEGMENTS} posting segments; "
+            f"{len(segments)} would be needed",
+        )
+    return segments
+
+
+def pack_posting_segment(
+    terms: Sequence[PostingTerm],
+    *,
+    segment_index: int,
+    dimensions: int,
+    entry_count: int,
+    range_index: int,
+    binding_sha256: str,
+    backend_coordinate: str,
+) -> bytes:
+    """Serialize one posting segment as a fixed-width big-endian term table."""
+
+    _check_dimensions(dimensions, "packed.postings.dimensions")
+    _check_entry_count(entry_count, "packed.postings.entry_count")
+    _validate_posting_terms(terms, dimensions=dimensions, entry_count=entry_count)
+    payload = bytearray()
+    for dimension, ordinal, layer_ordinal, value in terms:
+        payload += struct.pack(POSTING_TERM_FORMAT, dimension, ordinal, layer_ordinal, value)
+    if MEMBER_HEADER_BYTES + len(payload) > MAX_POSTING_SEGMENT_BYTES:
+        raise _refuse(
+            "PACKED_POSTING_LIMIT",
+            "packed.postings.segment",
+            f"one posting segment holds at most {MAX_POSTING_SEGMENT_BYTES} bytes",
+        )
+    header = pack_member_header(
+        kind="posting",
+        subindex=segment_index,
+        dimensions=dimensions,
+        entry_count=entry_count,
+        term_count=len(terms),
+        range_index=range_index,
+        payload_bytes=len(payload),
+        binding_sha256=binding_sha256,
+        backend_coordinate=backend_coordinate,
+    )
+    return header + bytes(payload)
+
+
+def _validate_posting_terms(
+    terms: Sequence[PostingTerm], *, dimensions: int, entry_count: int
+) -> None:
+    previous: PostingTerm | None = None
+    for position, term in enumerate(terms):
+        if len(term) != 4:
+            raise _refuse(
+                "PACKED_POSTING_TERM", f"packed.postings[{position}]", "a term is exactly four ints"
+            )
+        dimension, ordinal, layer_ordinal, value = term
+        if (
+            type(dimension) is not int
+            or not 0 <= dimension < dimensions
+            or type(ordinal) is not int
+            or not 0 <= ordinal < entry_count
+            or type(layer_ordinal) is not int
+            or not 0 <= layer_ordinal < len(EMBEDDING_LAYERS)
+            or type(value) is not int
+            or not MIN_INT32 <= value <= MAX_INT32
+            or value == 0
+        ):
+            raise _refuse(
+                "PACKED_POSTING_TERM",
+                f"packed.postings[{position}]",
+                "a term names an in-range dimension, entry ordinal, layer ordinal and int32",
+            )
+        if previous is not None and term <= previous:
+            raise _refuse(
+                "PACKED_POSTING_ORDER",
+                f"packed.postings[{position}]",
+                "posting terms ascend by dimension, entry ordinal, then layer ordinal",
+            )
+        previous = term
+
+
+def parse_posting_segment(
+    raw: bytes, *, descriptor: PackedMemberDescriptor | None = None
+) -> PackedPostingSegment:
+    """Read one posting segment exactly, refusing a term outside the range's own closure."""
+
+    header = parse_member_header(raw)
+    _check_binding(header, descriptor, kind="posting")
+    if len(raw) > MAX_POSTING_SEGMENT_BYTES:
+        raise _refuse(
+            "PACKED_POSTING_LIMIT", "packed.postings.segment", "segment exceeds its byte ceiling"
+        )
+    if header.term_count > MAX_POSTING_SEGMENT_TERMS:
+        raise _refuse(
+            "PACKED_POSTING_LIMIT", "packed.postings.term_count", "segment exceeds its term ceiling"
+        )
+    expected = header.term_count * POSTING_TERM_BYTES
+    payload = _payload(bytes(raw), header, expected_payload=expected)
+    terms = tuple(
+        struct.unpack_from(POSTING_TERM_FORMAT, payload, position * POSTING_TERM_BYTES)
+        for position in range(header.term_count)
+    )
+    _validate_posting_terms(terms, dimensions=header.dimensions, entry_count=header.entry_count)
+    return PackedPostingSegment(
+        segment_index=header.subindex,
+        dimensions=header.dimensions,
+        entry_count=header.entry_count,
+        range_index=header.range_index,
+        terms=terms,
+    )
+
+
+# ------------------------------------------------------------------------------------------
+# Bound segments and the conservative bound
+# ------------------------------------------------------------------------------------------
+
+
+LayerBounds = tuple[tuple[int, ...], tuple[int, ...]]
+
+
+@dataclass(frozen=True)
+class PackedBoundSegment:
+    """One backend's exact per-layer, per-dimension minima and maxima for one range."""
+
+    dimensions: int
+    entry_count: int
+    range_index: int
+    bounds: tuple[LayerBounds, ...]
+
+
+def compute_layer_bounds(
+    vectors_by_layer: Mapping[str, Sequence[Sequence[int]]], *, dimensions: int
+) -> tuple[LayerBounds, ...]:
+    """Derive the exact per-dimension minima and maxima of each layer in this range."""
+
+    _check_dimensions(dimensions, "packed.bounds.dimensions")
+    bounds: list[LayerBounds] = []
+    for layer in EMBEDDING_LAYERS:
+        vectors = vectors_by_layer.get(layer)
+        if not vectors:
+            raise _refuse(
+                "PACKED_MEMBER_LAYER",
+                "packed.bounds.layers",
+                f"bounds require exactly the four layers {list(EMBEDDING_LAYERS)}",
+            )
+        minima = [MAX_INT32] * dimensions
+        maxima = [MIN_INT32] * dimensions
+        for vector in vectors:
+            if len(vector) != dimensions:
+                raise _refuse(
+                    "PACKED_MEMBER_DIMENSION",
+                    "packed.bounds.vectors",
+                    "every vector summarized has exactly the backend's dimension",
+                )
+            for dimension, value in enumerate(vector):
+                if value < minima[dimension]:
+                    minima[dimension] = value
+                if value > maxima[dimension]:
+                    maxima[dimension] = value
+        bounds.append((tuple(minima), tuple(maxima)))
+    return tuple(bounds)
+
+
+def pack_bound_segment(
+    bounds: Sequence[LayerBounds],
+    *,
+    dimensions: int,
+    entry_count: int,
+    range_index: int,
+    binding_sha256: str,
+    backend_coordinate: str,
+) -> bytes:
+    """Serialize one backend's four-layer min/max summary as a fixed-width int32 table."""
+
+    _check_dimensions(dimensions, "packed.bounds.dimensions")
+    _check_entry_count(entry_count, "packed.bounds.entry_count")
+    if len(bounds) != BOUND_SEGMENT_LAYERS:
+        raise _refuse(
+            "PACKED_BOUND_SEGMENT",
+            "packed.bounds",
+            f"a bound segment summarizes exactly {BOUND_SEGMENT_LAYERS} layers",
+        )
+    payload = bytearray()
+    for layer_ordinal, layer_bounds in enumerate(bounds):
+        if len(layer_bounds) != 2:
+            raise _refuse(
+                "PACKED_BOUND_SEGMENT",
+                f"packed.bounds[{layer_ordinal}]",
+                "each layer summary is exactly one minima and one maxima table",
+            )
+        for values in layer_bounds:
+            if len(values) != dimensions:
+                raise _refuse(
+                    "PACKED_BOUND_SEGMENT",
+                    f"packed.bounds[{layer_ordinal}]",
+                    "each summary table has exactly the backend's dimension",
+                )
+            for value in values:
+                if type(value) is not int or not MIN_INT32 <= value <= MAX_INT32:
+                    raise _refuse(
+                        "PACKED_BOUND_SEGMENT",
+                        f"packed.bounds[{layer_ordinal}]",
+                        "a bound summary holds exact int32 values only",
+                    )
+            payload += struct.pack(f">{dimensions}i", *values)
+    header = pack_member_header(
+        kind="bound",
+        subindex=SUBINDEX_NONE,
+        dimensions=dimensions,
+        entry_count=entry_count,
+        term_count=0,
+        range_index=range_index,
+        payload_bytes=len(payload),
+        binding_sha256=binding_sha256,
+        backend_coordinate=backend_coordinate,
+    )
+    raw = header + bytes(payload)
+    if len(raw) != bound_segment_bytes(dimensions=dimensions):
+        raise _refuse(  # pragma: no cover - the arithmetic above is the law
+            "PACKED_BOUND_SEGMENT", "packed.bounds", "bound segment violated its exact byte law"
+        )
+    return raw
+
+
+def parse_bound_segment(
+    raw: bytes, *, descriptor: PackedMemberDescriptor | None = None
+) -> PackedBoundSegment:
+    """Read one bound segment exactly, refusing an inverted or mis-shaped summary."""
+
+    header = parse_member_header(raw)
+    _check_binding(header, descriptor, kind="bound")
+    if header.subindex != SUBINDEX_NONE:
+        raise _refuse(
+            "PACKED_BOUND_SEGMENT",
+            "packed.bounds.subindex",
+            "a bound segment summarizes every layer and carries no subindex",
+        )
+    expected = BOUND_SEGMENT_LAYERS * header.dimensions * 2 * 4
+    payload = _payload(bytes(raw), header, expected_payload=expected)
+    stride = header.dimensions * 4
+    bounds: list[LayerBounds] = []
+    for layer_ordinal in range(BOUND_SEGMENT_LAYERS):
+        base = layer_ordinal * stride * 2
+        minima = struct.unpack_from(f">{header.dimensions}i", payload, base)
+        maxima = struct.unpack_from(f">{header.dimensions}i", payload, base + stride)
+        for dimension, (low, high) in enumerate(zip(minima, maxima, strict=True)):
+            if low > high:
+                raise _refuse(
+                    "PACKED_BOUND_ORDER",
+                    f"packed.bounds[{layer_ordinal}][{dimension}]",
+                    "a summarized minimum may never exceed its maximum",
+                )
+        bounds.append((minima, maxima))
+    return PackedBoundSegment(
+        dimensions=header.dimensions,
+        entry_count=header.entry_count,
+        range_index=header.range_index,
+        bounds=tuple(bounds),
+    )
+
+
+def conservative_upper_bound(
+    query: Sequence[int], minima: Sequence[int], maxima: Sequence[int]
+) -> int:
+    """The largest dot product any vector inside this summary could have with ``query``.
+
+    Exact integers throughout: ``sum_i(q_i * max_i)`` where ``q_i >= 0`` and ``sum_i(q_i * min_i)``
+    otherwise. It is an upper bound on the *layer* score, never a score, and it is the only number
+    this module computes from a query.
+    """
+
+    total = 0
+    for value, low, high in zip(query, minima, maxima, strict=True):
+        total += value * (high if value >= 0 else low)
+    return total
+
+
+def range_upper_bound(query: Sequence[int], bounds: Sequence[LayerBounds]) -> int:
+    """The range's bound: the maximum of its four layer bounds.
+
+    Prune only when this is *strictly* below the current kth score. Equality must exact-scan: a
+    range that ties on score may still win on entry id, and a pruned range cannot present an id.
+    """
+
+    if len(bounds) != BOUND_SEGMENT_LAYERS:
+        raise _refuse(
+            "PACKED_BOUND_SEGMENT",
+            "packed.bounds",
+            f"a range bound maximizes exactly {BOUND_SEGMENT_LAYERS} layer bounds",
+        )
+    return max(conservative_upper_bound(query, minima, maxima) for minima, maxima in bounds)
+
+
+# ------------------------------------------------------------------------------------------
+# Descriptors, range manifests, and the outer head
+# ------------------------------------------------------------------------------------------
+
+
+@dataclass(frozen=True)
+class PackedBackend:
+    """One available backend's published coordinate, exactly as the vectors were produced under."""
+
+    coordinate: str
+    dimensions: int
+    quantization: str
+    query_safe: bool
+
+    def __post_init__(self) -> None:
+        if not isinstance(self.coordinate, str) or not 1 <= len(self.coordinate) <= 256:
+            raise _refuse(
+                "PACKED_BACKEND", "packed.backend.coordinate", "must be a bounded coordinate string"
+            )
+        _check_dimensions(self.dimensions, "packed.backend.dimensions")
+        if not isinstance(self.quantization, str) or not self.quantization:
+            raise _refuse(
+                "PACKED_BACKEND", "packed.backend.quantization", "must name its exact quantization"
+            )
+        if type(self.query_safe) is not bool:
+            raise _refuse("PACKED_BACKEND", "packed.backend.query_safe", "must be a boolean")
+
+    def to_dict(self) -> dict[str, Any]:
+        return {
+            "coordinate": self.coordinate,
+            "dimensions": self.dimensions,
+            "quantization": self.quantization,
+            "query_safe": self.query_safe,
+        }
+
+
+@dataclass(frozen=True)
+class PackedMemberDescriptor:
+    """One member's exact identity: what it is, where it belongs, and its byte-for-byte digest."""
+
+    kind: str
+    sha256: str
+    bytes: int
+    range_index: int
+    first_key: str
+    last_key: str
+    entry_count: int
+    facts_sha256: str
+    range_binding_sha256: str
+    backend_coordinate: str | None = None
+    dimensions: int | None = None
+    layer: str | None = None
+    segment_index: int | None = None
+    term_count: int | None = None
+
+    def __post_init__(self) -> None:
+        if self.kind not in MEMBER_KINDS:
+            raise _refuse("PACKED_MEMBER_KIND", "packed.descriptor.kind", "unknown member kind")
+        if not _is_digest(self.sha256) or not _is_digest(self.range_binding_sha256):
+            raise _refuse(
+                "PACKED_MEMBER_DIGEST", "packed.descriptor", "member digests are lowercase SHA-256"
+            )
+        if not _is_digest(self.facts_sha256):
+            raise _refuse(
+                "PACKED_MEMBER_DIGEST",
+                "packed.descriptor.facts_sha256",
+                "a descriptor binds its range's exact facts order digest",
+            )
+        if type(self.bytes) is not int or self.bytes < 0:
+            raise _refuse("PACKED_MEMBER_HEADER", "packed.descriptor.bytes", "must be a byte count")
+        if self.layer is not None and self.layer not in EMBEDDING_LAYERS:
+            raise _refuse("PACKED_MEMBER_LAYER", "packed.descriptor.layer", "unknown layer")
+
+    def to_dict(self) -> dict[str, Any]:
+        return {
+            "kind": self.kind,
+            "sha256": self.sha256,
+            "bytes": self.bytes,
+            "range_index": self.range_index,
+            "first_key": self.first_key,
+            "last_key": self.last_key,
+            "entry_count": self.entry_count,
+            "facts_sha256": self.facts_sha256,
+            "range_binding_sha256": self.range_binding_sha256,
+            "backend_coordinate": self.backend_coordinate,
+            "dimensions": self.dimensions,
+            "layer": self.layer,
+            "segment_index": self.segment_index,
+            "term_count": self.term_count,
+        }
+
+    def replace(self, **changes: Any) -> PackedMemberDescriptor:
+        return replace(self, **changes)
+
+
+_MEMBER_DESCRIPTOR_MEMBERS = frozenset(PackedMemberDescriptor.__dataclass_fields__)
+
+
+def member_descriptor_from_dict(value: Any, *, path: str) -> PackedMemberDescriptor:
+    if not isinstance(value, dict) or set(value) != _MEMBER_DESCRIPTOR_MEMBERS:
+        raise _refuse("PACKED_MEMBER_HEADER", path, "a member descriptor contract differs")
+    if len(canonical_json_bytes(value)) > MAX_MEMBER_DESCRIPTOR_BYTES:
+        raise _refuse(
+            "PACKED_DESCRIPTOR_LIMIT",
+            path,
+            f"a member descriptor holds at most {MAX_MEMBER_DESCRIPTOR_BYTES} bytes",
+        )
+    return PackedMemberDescriptor(**value)
+
+
+@dataclass(frozen=True)
+class PackedRangeDescriptor:
+    """One range's entry in the outer head: its key interval and its manifest's exact digest."""
+
+    range_index: int
+    first_key: str
+    last_key: str
+    entry_count: int
+    facts_sha256: str
+    range_binding_sha256: str
+    manifest_sha256: str
+    manifest_bytes: int
+    member_count: int
+
+    def to_dict(self) -> dict[str, Any]:
+        return {
+            "range_index": self.range_index,
+            "first_key": self.first_key,
+            "last_key": self.last_key,
+            "entry_count": self.entry_count,
+            "facts_sha256": self.facts_sha256,
+            "range_binding_sha256": self.range_binding_sha256,
+            "manifest_sha256": self.manifest_sha256,
+            "manifest_bytes": self.manifest_bytes,
+            "member_count": self.member_count,
+        }
+
+    def replace(self, **changes: Any) -> PackedRangeDescriptor:
+        return replace(self, **changes)
+
+
+_RANGE_DESCRIPTOR_MEMBERS = frozenset(PackedRangeDescriptor.__dataclass_fields__)
+
+
+def range_descriptor_from_dict(value: Any, *, path: str) -> PackedRangeDescriptor:
+    if not isinstance(value, dict) or set(value) != _RANGE_DESCRIPTOR_MEMBERS:
+        raise _refuse("PACKED_HEAD_DESCRIPTORS", path, "a range descriptor contract differs")
+    if len(canonical_json_bytes(value)) > MAX_RANGE_DESCRIPTOR_BYTES:
+        raise _refuse(
+            "PACKED_DESCRIPTOR_LIMIT",
+            path,
+            f"a range descriptor holds at most {MAX_RANGE_DESCRIPTOR_BYTES} bytes",
+        )
+    if not _is_digest(value["manifest_sha256"]) or not _is_digest(value["facts_sha256"]):
+        raise _refuse("PACKED_HEAD_DESCRIPTORS", path, "a range descriptor binds exact digests")
+    return PackedRangeDescriptor(**value)
+
+
+def range_binding_sha256(
+    *,
+    range_index: int,
+    first_key: str,
+    last_key: str,
+    entry_count: int,
+    facts_sha256: str,
+) -> str:
+    """The digest every member of one range carries: its interval, size, and exact facts order."""
+
+    return canonical_sha256(
+        {
+            "entry_count": entry_count,
+            "facts_sha256": facts_sha256,
+            "first_key": first_key,
+            "last_key": last_key,
+            "range_index": range_index,
+        }
+    )
+
+
+# ------------------------------------------------------------------------------------------
+# The one encoding seam a packed publisher may reach
+# ------------------------------------------------------------------------------------------
+
+
+def encode_layer_batch(
+    backend: EmbeddingBackend,
+    texts: Sequence[str],
+    *,
+    entry_count: int,
+    dimensions: int,
+) -> tuple[tuple[tuple[int, ...], ...], BatchEncodeResult]:
+    """Encode one range/layer/backend's fresh texts through the bounded seam, and verify the result.
+
+    This is the only place in the packed pair that reaches an encoder, and it reaches exactly one
+    entry point. The counter record comes back untouched: the publisher may sum ordered records but
+    may never author one, so nothing here rewrites a field of it.
+    """
+
+    result = backend.encode_many(tuple(texts))
+    if not isinstance(result, BatchEncodeResult):
+        raise _refuse(
+            "PACKED_ENCODE_RESULT",
+            "packed.encode.result",
+            "the bounded seam must return its own counter record",
+        )
+    if len(result.vectors) != entry_count or result.scalar_invocations != entry_count:
+        raise _refuse(
+            "PACKED_ENCODE_RESULT",
+            "packed.encode.result",
+            "the seam returned another count than the items this range/layer asked for",
+        )
+    for ordinal, vector in enumerate(result.vectors):
+        if len(vector) != dimensions or any(
+            type(value) is not int or not MIN_INT32 <= value <= MAX_INT32 for value in vector
+        ):
+            raise _refuse(
+                "PACKED_ENCODE_RESULT",
+                f"packed.encode.vectors[{ordinal}]",
+                "the seam returned a vector outside the backend's exact integer coordinate",
+            )
+    return result.vectors, result
+
+
+# ------------------------------------------------------------------------------------------
+# Building one range
+# ------------------------------------------------------------------------------------------
+
+
+@dataclass(frozen=True)
+class PackedRangeInput:
+    """One range's ordered publishable entries, exactly as classification produced them."""
+
+    range_index: int
+    entries: tuple[Mapping[str, Any], ...]
+
+    def __post_init__(self) -> None:
+        if type(self.range_index) is not int or not 0 <= self.range_index < MAX_RANGE_DESCRIPTORS:
+            raise _refuse(
+                "PACKED_RANGE_ORDER",
+                "packed.range.range_index",
+                f"a generation holds at most {MAX_RANGE_DESCRIPTORS} ranges",
+            )
+        _check_entry_count(len(self.entries), "packed.range.entries")
+        previous: bytes | None = None
+        for position, entry in enumerate(self.entries):
+            path = f"packed.range.entries[{position}]"
+            if not isinstance(entry, Mapping) or not {
+                "key",
+                "entry_id",
+                "classification",
+                "semantic_facts_digest",
+                "entry",
+                "history",
+            } <= set(entry):
+                raise _refuse("PACKED_RANGE_ENTRY", path, "a range entry contract differs")
+            if entry["classification"] not in PACKED_CLASSIFICATIONS:
+                raise _refuse(
+                    "PACKED_RANGE_ENTRY",
+                    path,
+                    f"a published entry is one of {list(PACKED_CLASSIFICATIONS)}",
+                )
+            if not isinstance(entry["key"], str) or not entry["key"]:
+                raise _refuse("PACKED_RANGE_ENTRY", path, "a range entry carries its exact key")
+            key = entry["key"].encode("utf-8")
+            if previous is not None and key <= previous:
+                raise _refuse(
+                    "PACKED_RANGE_ORDER", path, "a range ascends by key with no repeated key"
+                )
+            previous = key
+
+    @property
+    def keys(self) -> tuple[str, ...]:
+        return tuple(str(entry["key"]) for entry in self.entries)
+
+    @property
+    def first_key(self) -> str:
+        return str(self.entries[0]["key"])
+
+    @property
+    def last_key(self) -> str:
+        return str(self.entries[-1]["key"])
+
+
+@dataclass(frozen=True)
+class BuiltPackedMember:
+    """One member's exact bytes beside the descriptor that binds them."""
+
+    raw: bytes
+    descriptor: PackedMemberDescriptor
+
+
+@dataclass(frozen=True)
+class BuiltPackedRange:
+    """One complete range: every member's bytes, its manifest, and its head descriptor."""
+
+    range_index: int
+    first_key: str
+    last_key: str
+    entry_count: int
+    facts_sha256: str
+    history_sha256: str
+    range_binding_sha256: str
+    members: tuple[BuiltPackedMember, ...]
+    manifest: dict[str, Any]
+    manifest_raw: bytes
+    manifest_sha256: str
+    descriptor: PackedRangeDescriptor
+    bounds: dict[str, tuple[LayerBounds, ...]]
+    posting_term_count: int
+
+
+def _canonical_text(payload: Any, *, code: str, path: str, maximum: int) -> tuple[str, str]:
+    """Serialize one nested document to canonical text carried as one string.
+
+    A range holds up to a thousand v2 entries and each one is itself a deep document; nesting them
+    as JSON objects would exceed the canonical member ceiling long before it exceeded the byte
+    ceiling. Carrying each as its exact canonical text keeps the member's own shape flat and keeps
+    the entry byte-for-byte reproducible.
+    """
+
+    try:
+        raw = canonical_json_bytes(payload)
+    except CanonicalJSONError as error:
+        raise _refuse(code, path, "a range document is not canonically representable") from error
+    if len(raw) > maximum:
+        raise _refuse(code, path, "a range document exceeds its byte bound")
+    return raw.decode("utf-8"), sha256_bytes(raw)
+
+
+def build_packed_range(
+    range_input: PackedRangeInput,
+    vectors: Mapping[str, Mapping[str, Sequence[Sequence[int]]]],
+    *,
+    backends: Sequence[PackedBackend],
+    posting_backend_coordinate: str,
+    max_terms_per_segment: int | None = None,
+) -> BuiltPackedRange:
+    """Assemble every member of one range from its entries and its per-backend layer vectors."""
+
+    if not 1 <= len(backends) <= MAX_PACKED_BACKENDS:
+        raise _refuse(
+            "PACKED_BACKEND",
+            "packed.range.backends",
+            f"a packed generation carries 1 to {MAX_PACKED_BACKENDS} backends",
+        )
+    coordinates = [backend.coordinate for backend in backends]
+    if len(set(coordinates)) != len(coordinates) or coordinates != sorted(coordinates):
+        raise _refuse(
+            "PACKED_BACKEND",
+            "packed.range.backends",
+            "backends are distinct and published in ascending coordinate order",
+        )
+    if posting_backend_coordinate not in coordinates:
+        raise _refuse(
+            "PACKED_POSTING_BACKEND",
+            "packed.range.posting_backend_coordinate",
+            "postings are derived from one of this generation's own backends",
+        )
+
+    entry_count = len(range_input.entries)
+    first_key = range_input.first_key
+    last_key = range_input.last_key
+
+    facts_items = []
+    history_items = []
+    for entry in range_input.entries:
+        entry_text, entry_sha256 = _canonical_text(
+            entry["entry"],
+            code="PACKED_FACTS_LIMIT",
+            path="packed.range.entries[].entry",
+            maximum=MAX_FACTS_MEMBER_BYTES,
+        )
+        history_text, history_sha256 = _canonical_text(
+            entry["history"],
+            code="PACKED_HISTORY_LIMIT",
+            path="packed.range.entries[].history",
+            maximum=MAX_HISTORY_MEMBER_BYTES,
+        )
+        facts_items.append(
+            {
+                "key": entry["key"],
+                "entry_id": entry["entry_id"],
+                "classification": entry["classification"],
+                "semantic_facts_digest": entry["semantic_facts_digest"],
+                "entry_sha256": entry_sha256,
+                "entry_json": entry_text,
+            }
+        )
+        history_items.append(
+            {
+                "key": entry["key"],
+                "entry_id": entry["entry_id"],
+                "history_sha256": history_sha256,
+                "history_json": history_text,
+            }
+        )
+
+    facts_payload = {
+        "schema_version": PACKED_FACTS_SCHEMA,
+        "range_index": range_input.range_index,
+        "first_key": first_key,
+        "last_key": last_key,
+        "entry_count": entry_count,
+        "entries": facts_items,
+    }
+    facts_raw = _member_bytes(
+        facts_payload,
+        code="PACKED_FACTS_LIMIT",
+        path="packed.range.facts",
+        maximum=MAX_FACTS_MEMBER_BYTES,
+    )
+    facts_sha256 = sha256_bytes(facts_raw)
+
+    history_payload = {
+        "schema_version": PACKED_HISTORY_SCHEMA,
+        "range_index": range_input.range_index,
+        "first_key": first_key,
+        "last_key": last_key,
+        "entry_count": entry_count,
+        "entries": history_items,
+    }
+    history_raw = _member_bytes(
+        history_payload,
+        code="PACKED_HISTORY_LIMIT",
+        path="packed.range.history",
+        maximum=MAX_HISTORY_MEMBER_BYTES,
+    )
+    history_sha256 = sha256_bytes(history_raw)
+
+    binding = range_binding_sha256(
+        range_index=range_input.range_index,
+        first_key=first_key,
+        last_key=last_key,
+        entry_count=entry_count,
+        facts_sha256=facts_sha256,
+    )
+
+    def descriptor(**changes: Any) -> PackedMemberDescriptor:
+        return PackedMemberDescriptor(
+            range_index=range_input.range_index,
+            first_key=first_key,
+            last_key=last_key,
+            entry_count=entry_count,
+            facts_sha256=facts_sha256,
+            range_binding_sha256=binding,
+            **changes,
+        )
+
+    members: list[BuiltPackedMember] = [
+        BuiltPackedMember(
+            raw=facts_raw,
+            descriptor=descriptor(kind="facts", sha256=facts_sha256, bytes=len(facts_raw)),
+        ),
+        BuiltPackedMember(
+            raw=history_raw,
+            descriptor=descriptor(kind="history", sha256=history_sha256, bytes=len(history_raw)),
+        ),
+    ]
+
+    bounds_by_backend: dict[str, tuple[LayerBounds, ...]] = {}
+    posting_term_count = 0
+    for backend in backends:
+        layers = vectors.get(backend.coordinate)
+        if layers is None or set(layers) != set(EMBEDDING_LAYERS):
+            raise _refuse(
+                "PACKED_MEMBER_LAYER",
+                "packed.range.vectors",
+                f"every backend supplies exactly the four layers {list(EMBEDDING_LAYERS)}",
+            )
+        for layer in EMBEDDING_LAYERS:
+            layer_vectors = layers[layer]
+            if len(layer_vectors) != entry_count:
+                raise _refuse(
+                    "PACKED_MEMBER_ENTRY_COUNT",
+                    "packed.range.vectors",
+                    "every layer member covers exactly this range's entries",
+                )
+            raw = pack_vector_member(
+                layer_vectors,
+                layer=layer,
+                dimensions=backend.dimensions,
+                range_index=range_input.range_index,
+                binding_sha256=binding,
+                backend_coordinate=backend.coordinate,
+            )
+            members.append(
+                BuiltPackedMember(
+                    raw=raw,
+                    descriptor=descriptor(
+                        kind="vector",
+                        sha256=sha256_bytes(raw),
+                        bytes=len(raw),
+                        backend_coordinate=backend.coordinate,
+                        dimensions=backend.dimensions,
+                        layer=layer,
+                    ),
+                )
+            )
+
+        bounds = compute_layer_bounds(layers, dimensions=backend.dimensions)
+        bounds_by_backend[backend.coordinate] = bounds
+        raw = pack_bound_segment(
+            bounds,
+            dimensions=backend.dimensions,
+            entry_count=entry_count,
+            range_index=range_input.range_index,
+            binding_sha256=binding,
+            backend_coordinate=backend.coordinate,
+        )
+        members.append(
+            BuiltPackedMember(
+                raw=raw,
+                descriptor=descriptor(
+                    kind="bound",
+                    sha256=sha256_bytes(raw),
+                    bytes=len(raw),
+                    backend_coordinate=backend.coordinate,
+                    dimensions=backend.dimensions,
+                ),
+            )
+        )
+
+        if backend.coordinate == posting_backend_coordinate:
+            terms = compute_layer_postings(layers, dimensions=backend.dimensions)
+            posting_term_count = len(terms)
+            for segment_index, segment in enumerate(
+                segment_posting_terms(terms, max_terms_per_segment=max_terms_per_segment)
+            ):
+                raw = pack_posting_segment(
+                    segment,
+                    segment_index=segment_index,
+                    dimensions=backend.dimensions,
+                    entry_count=entry_count,
+                    range_index=range_input.range_index,
+                    binding_sha256=binding,
+                    backend_coordinate=backend.coordinate,
+                )
+                members.append(
+                    BuiltPackedMember(
+                        raw=raw,
+                        descriptor=descriptor(
+                            kind="posting",
+                            sha256=sha256_bytes(raw),
+                            bytes=len(raw),
+                            backend_coordinate=backend.coordinate,
+                            dimensions=backend.dimensions,
+                            segment_index=segment_index,
+                            term_count=len(segment),
+                        ),
+                    )
+                )
+
+    if len(members) > MAX_RANGE_MEMBER_DESCRIPTORS:
+        raise _refuse(
+            "PACKED_RANGE_MEMBERS",
+            "packed.range.members",
+            f"a range manifest holds at most {MAX_RANGE_MEMBER_DESCRIPTORS} member descriptors",
+        )
+    for member in members:
+        if len(canonical_json_bytes(member.descriptor.to_dict())) > MAX_MEMBER_DESCRIPTOR_BYTES:
+            raise _refuse(
+                "PACKED_DESCRIPTOR_LIMIT",
+                "packed.range.members[]",
+                f"a member descriptor holds at most {MAX_MEMBER_DESCRIPTOR_BYTES} bytes",
+            )
+
+    body = {
+        "schema_version": PACKED_RANGE_MANIFEST_SCHEMA,
+        "range_index": range_input.range_index,
+        "first_key": first_key,
+        "last_key": last_key,
+        "entry_count": entry_count,
+        "facts_sha256": facts_sha256,
+        "history_sha256": history_sha256,
+        "range_binding_sha256": binding,
+        "backends": list(coordinates),
+        "posting_backend_coordinate": posting_backend_coordinate,
+        "members": [member.descriptor.to_dict() for member in members],
+    }
+    manifest = {**body, "root_sha256": canonical_sha256(body)}
+    manifest_raw = _member_bytes(
+        manifest,
+        code="PACKED_RANGE_MANIFEST",
+        path="packed.range.manifest",
+        maximum=MAX_RANGE_MANIFEST_BYTES,
+    )
+    return BuiltPackedRange(
+        range_index=range_input.range_index,
+        first_key=first_key,
+        last_key=last_key,
+        entry_count=entry_count,
+        facts_sha256=facts_sha256,
+        history_sha256=history_sha256,
+        range_binding_sha256=binding,
+        members=tuple(members),
+        manifest=manifest,
+        manifest_raw=manifest_raw,
+        manifest_sha256=sha256_bytes(manifest_raw),
+        descriptor=PackedRangeDescriptor(
+            range_index=range_input.range_index,
+            first_key=first_key,
+            last_key=last_key,
+            entry_count=entry_count,
+            facts_sha256=facts_sha256,
+            range_binding_sha256=binding,
+            manifest_sha256=sha256_bytes(manifest_raw),
+            manifest_bytes=len(manifest_raw),
+            member_count=len(members),
+        ),
+        bounds=bounds_by_backend,
+        posting_term_count=posting_term_count,
+    )
+
+
+def _member_bytes(payload: Any, *, code: str, path: str, maximum: int) -> bytes:
+    try:
+        raw = canonical_json_bytes(payload)
+    except CanonicalJSONError as error:
+        raise _refuse(code, path, "a packed document is not canonically representable") from error
+    if len(raw) > maximum:
+        raise _refuse(
+            code,
+            path,
+            f"the member holds at most {maximum} bytes; publication refuses rather than splitting",
+        )
+    return raw
+
+
+# ------------------------------------------------------------------------------------------
+# The outer head
+# ------------------------------------------------------------------------------------------
+
+
+COUNTER_MEMBERS = (
+    "batch_invocations",
+    "encoded_layer_items",
+    "backend_scalar_invocations",
+    "encoded_utf8_bytes",
+    "reused_layer_items",
+)
+
+
+def ranges_chain_sha256(descriptors: Sequence[PackedRangeDescriptor]) -> str:
+    """One chained digest over every range descriptor, in published order."""
+
+    chain: str | None = None
+    for descriptor in descriptors:
+        chain = canonical_sha256({"previous_sha256": chain, "range": descriptor.to_dict()})
+    return chain or canonical_sha256({"previous_sha256": None, "range": None})
+
+
+def build_packed_head(
+    *,
+    provider_id: str,
+    generation_sha256: str,
+    predecessor_head_sha256: str | None,
+    backends: Sequence[PackedBackend],
+    posting_backend_coordinate: str,
+    ranges: Sequence[PackedRangeDescriptor],
+    coverage: Mapping[str, Any],
+    counters: Mapping[str, int],
+    invocations: Sequence[Mapping[str, Any]],
+    terminal_sha256: str,
+) -> dict[str, Any]:
+    """Assemble the outer head. Every law it carries is enforced by the reader, not by this call."""
+
+    if len(ranges) > MAX_RANGE_DESCRIPTORS:
+        raise _refuse(
+            "PACKED_HEAD_DESCRIPTORS",
+            "packed.head.ranges",
+            f"an outer head holds at most {MAX_RANGE_DESCRIPTORS} range descriptors",
+        )
+    if not ranges:
+        raise _refuse(
+            "PACKED_HEAD_DESCRIPTORS", "packed.head.ranges", "a published generation has a range"
+        )
+    if set(counters) != set(COUNTER_MEMBERS):
+        raise _refuse(
+            "PACKED_COUNTER_CONTRACT",
+            "packed.head.counters",
+            f"the head carries exactly {list(COUNTER_MEMBERS)}",
+        )
+    for name in COUNTER_MEMBERS:
+        if type(counters[name]) is not int or counters[name] < 0:
+            raise _refuse(
+                "PACKED_COUNTER_CONTRACT",
+                f"packed.head.counters.{name}",
+                "a work counter is a non-negative integer",
+            )
+    for descriptor in ranges:
+        if len(canonical_json_bytes(descriptor.to_dict())) > MAX_RANGE_DESCRIPTOR_BYTES:
+            raise _refuse(
+                "PACKED_DESCRIPTOR_LIMIT",
+                "packed.head.ranges[]",
+                f"a range descriptor holds at most {MAX_RANGE_DESCRIPTOR_BYTES} bytes",
+            )
+    if not _is_digest(terminal_sha256):
+        raise _refuse(
+            "PACKED_HEAD_DIGEST",
+            "packed.head.terminal_sha256",
+            "the terminal publication record is named by one lowercase SHA-256",
+        )
+    if not coverage_is_valid(coverage):
+        raise _refuse(
+            "PACKED_HEAD_COVERAGE",
+            "packed.head.coverage",
+            "a published generation states what it covers and what it drew from",
+        )
+    body = {
+        "schema_version": PACKED_HEAD_SCHEMA,
+        "provider_id": provider_id,
+        "generation_sha256": generation_sha256,
+        "predecessor_head_sha256": predecessor_head_sha256,
+        "backends": [backend.to_dict() for backend in backends],
+        "posting_backend_coordinate": posting_backend_coordinate,
+        "range_count": len(ranges),
+        "entry_count": sum(descriptor.entry_count for descriptor in ranges),
+        # What this generation covers travels with the head rather than only with the receipts
+        # behind it, because the head is what a release archive is built from and what an
+        # installed catalogue reads back. A consumer that holds only the published bytes can
+        # still tell a bounded catalogue from an exhaustive one.
+        "coverage": dict(coverage),
+        "ranges": [descriptor.to_dict() for descriptor in ranges],
+        "ranges_chain_sha256": ranges_chain_sha256(ranges),
+        "counters": {name: counters[name] for name in COUNTER_MEMBERS},
+        "invocations": [dict(record) for record in invocations],
+        "terminal_sha256": terminal_sha256,
+    }
+    head = {**body, "root_sha256": canonical_sha256(body)}
+    if len(canonical_json_bytes(head)) > MAX_PACKED_HEAD_BYTES:
+        raise _refuse(
+            "PACKED_HEAD_LIMIT",
+            "packed.head",
+            f"an outer head holds at most {MAX_PACKED_HEAD_BYTES} bytes",
+        )
+    return head
+
+
+# ------------------------------------------------------------------------------------------
+# The durable output root
+# ------------------------------------------------------------------------------------------
+
+
+class PackedDirectory:
+    """One locally confined packed root whose members install atomically and read back exactly."""
+
+    def __init__(self, root: Path, *, root_descriptor: int | None = None) -> None:
+        self.root = Path(root)
+        self._retained_root_descriptor = root_descriptor
+        self.bytes_written = 0
+        self._root_fd = -1
+        self._members_fd = -1
+        self._owned: list[int] = []
+
+    @contextlib.contextmanager
+    def opened(self) -> Iterator[PackedDirectory]:
+        try:
+            if self._retained_root_descriptor is None:
+                self.root.mkdir(parents=True, exist_ok=True, mode=0o700)
+                self._root_fd = self._open_directory(self.root)
+            else:
+                self._root_fd = os.dup(self._retained_root_descriptor)
+                self._owned.append(self._root_fd)
+                self._require_private_directory(self._root_fd)
+            try:
+                os.mkdir(PACKED_MEMBERS_DIRNAME, mode=0o700, dir_fd=self._root_fd)
+            except FileExistsError:
+                pass
+            self._members_fd = self._open_directory_at(self._root_fd, PACKED_MEMBERS_DIRNAME)
+        except OSError as error:
+            self._release()
+            raise _refuse("PACKED_OUTPUT_IO", "packed.output", "output root is unusable") from error
+        except SourceContractError:
+            self._release()
+            raise
+        try:
+            yield self
+        finally:
+            self._release()
+
+    def _release(self) -> None:
+        for descriptor in reversed(self._owned):
+            os.close(descriptor)
+        self._owned = []
+        self._root_fd = -1
+        self._members_fd = -1
+
+    def _open_directory(self, path: Path) -> int:
+        descriptor = os.open(path, _OPEN_DIRECTORY)
+        self._owned.append(descriptor)
+        self._require_private_directory(descriptor)
+        return descriptor
+
+    def _open_directory_at(self, parent_descriptor: int, name: str) -> int:
+        descriptor = os.open(name, _OPEN_DIRECTORY, dir_fd=parent_descriptor)
+        self._owned.append(descriptor)
+        self._require_private_directory(descriptor)
+        return descriptor
+
+    def _require_private_directory(self, descriptor: int) -> None:
+        info = os.fstat(descriptor)
+        if not stat.S_ISDIR(info.st_mode) or stat.S_IMODE(info.st_mode) & 0o077:
+            raise _refuse(
+                "PACKED_OUTPUT_PATH",
+                "packed.output",
+                "output components must be private directories",
+            )
+
+    @property
+    def root_descriptor(self) -> int:
+        """The exact open root used by this directory context."""
+
+        if self._root_fd < 0:
+            raise RuntimeError("packed directory is not open")
+        return self._root_fd
+
+    def read(self, name: str, *, maximum: int) -> bytes | None:
+        try:
+            return _read_regular_at(self._root_fd, name, maximum=maximum)
+        except FileNotFoundError:
+            return None
+
+    def read_member(self, sha256: str, *, kind: str, maximum: int) -> bytes | None:
+        try:
+            return _read_regular_at(
+                self._members_fd, member_filename(kind, sha256), maximum=maximum
+            )
+        except FileNotFoundError:
+            return None
+
+    def has_member(self, sha256: str, *, kind: str) -> bool:
+        try:
+            os.stat(member_filename(kind, sha256), dir_fd=self._members_fd, follow_symlinks=False)
+        except FileNotFoundError:
+            return False
+        except OSError as error:
+            raise _refuse(
+                "PACKED_OUTPUT_IO", "packed.output.member", "member lookup failed"
+            ) from error
+        return True
+
+    def write_member_bytes(self, raw: bytes, *, kind: str) -> tuple[str, int]:
+        digest = sha256_bytes(raw)
+        name = member_filename(kind, digest)
+        try:
+            existing = _read_regular_at(self._members_fd, name, maximum=len(raw))
+        except FileNotFoundError:
+            existing = None
+        except OSError as error:
+            raise _refuse(
+                "PACKED_OUTPUT_IO", "packed.output.member", "member lookup failed"
+            ) from error
+        if existing is not None:
+            if existing != raw:
+                raise _refuse(
+                    "PACKED_OUTPUT_READBACK", "packed.output.member", "digest path bytes differ"
+                )
+            return digest, len(raw)
+        temporary = f".publish.{os.getpid()}.{secrets.token_hex(16)}.tmp"
+        try:
+            _write_regular_at(self._members_fd, temporary, raw)
+            with contextlib.suppress(FileExistsError):
+                os.link(
+                    temporary,
+                    name,
+                    src_dir_fd=self._members_fd,
+                    dst_dir_fd=self._members_fd,
+                    follow_symlinks=False,
+                )
+        except OSError as error:
+            raise _refuse(
+                "PACKED_OUTPUT_IO", "packed.output.member", "member publication failed"
+            ) from error
+        finally:
+            with contextlib.suppress(FileNotFoundError):
+                os.unlink(temporary, dir_fd=self._members_fd)
+            os.fsync(self._members_fd)
+        if _read_regular_at(self._members_fd, name, maximum=len(raw)) != raw:
+            raise _refuse(
+                "PACKED_OUTPUT_READBACK", "packed.output.member", "member readback differs"
+            )
+        self.bytes_written += len(raw)
+        return digest, len(raw)
+
+    def publish(self, name: str, payload: Mapping[str, Any], *, maximum: int) -> str:
+        raw = canonical_json_bytes(dict(payload))
+        if len(raw) > maximum:
+            raise _refuse(
+                "PACKED_OUTPUT_LIMIT", f"packed.output.{name}", "document exceeds its byte bound"
+            )
+        temporary = f".{name}.{os.getpid()}.{secrets.token_hex(8)}.tmp"
+        try:
+            _write_regular_at(self._root_fd, temporary, raw)
+            os.replace(temporary, name, src_dir_fd=self._root_fd, dst_dir_fd=self._root_fd)
+            os.fsync(self._root_fd)
+        except OSError as error:
+            raise _refuse(
+                "PACKED_OUTPUT_IO", f"packed.output.{name}", "document publication failed"
+            ) from error
+        finally:
+            with contextlib.suppress(FileNotFoundError):
+                os.unlink(temporary, dir_fd=self._root_fd)
+        if _read_regular_at(self._root_fd, name, maximum=maximum) != raw:
+            raise _refuse(
+                "PACKED_OUTPUT_READBACK", f"packed.output.{name}", "document readback differs"
+            )
+        self.bytes_written += len(raw)
+        return sha256_bytes(raw)
+
+
+def _read_regular_at(parent_fd: int, name: str, *, maximum: int) -> bytes:
+    try:
+        raw = read_bounded_at(parent_fd, name, maximum=maximum)
+    except BoundedReadFailure as error:
+        raise _refuse(
+            "PACKED_OUTPUT_PATH",
+            "packed.output",
+            "members must be stable bounded single-link regular files",
+        ) from error
+    assert raw is not None
+    return raw
+
+
+def _write_regular_at(parent_fd: int, name: str, raw: bytes) -> None:
+    flags = os.O_WRONLY | os.O_CREAT | os.O_EXCL | getattr(os, "O_NOFOLLOW", 0)
+    descriptor = os.open(name, flags, 0o600, dir_fd=parent_fd)
+    try:
+        written = 0
+        while written < len(raw):
+            count = os.write(descriptor, raw[written:])
+            if count < 1:
+                raise _refuse("PACKED_OUTPUT_IO", "packed.output", "write made no progress")
+            written += count
+        os.fsync(descriptor)
+    finally:
+        os.close(descriptor)
+
+
+# ------------------------------------------------------------------------------------------
+# The independent reader
+# ------------------------------------------------------------------------------------------
+
+
+@dataclass(frozen=True)
+class VerifiedPackedRange:
+    """What one range verified to, recomputed from its own bytes rather than from a summary."""
+
+    range_index: int
+    first_key: str
+    last_key: str
+    entry_count: int
+    facts_sha256: str
+    history_sha256: str
+    range_binding_sha256: str
+    manifest_bytes: int
+    member_count: int
+    member_sha256s: tuple[str, ...]
+    vector_payload_sha256s: tuple[str, ...]
+    posting_sha256s: tuple[str, ...]
+    bound_sha256s: tuple[str, ...]
+    posting_term_count: int
+    entry_ids: tuple[str, ...]
+    classification_counts: tuple[tuple[str, int], ...]
+
+
+@dataclass(frozen=True)
+class VerifiedPackedGeneration:
+    """One complete packed generation's verified shape."""
+
+    head_sha256: str
+    head: dict[str, Any]
+    range_count: int
+    entry_count: int
+    member_count: int
+    posting_term_count: int
+    backends: tuple[str, ...]
+    classification_counts: tuple[tuple[str, int], ...]
+    fresh_range_count: int
+    vector_payload_sha256s: tuple[str, ...]
+    posting_member_sha256s: tuple[str, ...]
+    bound_member_sha256s: tuple[str, ...]
+
+
+def verify_packed_range(
+    directory: PackedDirectory,
+    manifest_sha256: str,
+    *,
+    backends: Sequence[PackedBackend],
+    posting_backend_coordinate: str,
+) -> VerifiedPackedRange:
+    """Scan one emitted range once, recomputing every accelerator from the exact pack bytes."""
+
+    raw = directory.read_member(manifest_sha256, kind="range", maximum=MAX_RANGE_MANIFEST_BYTES)
+    if raw is None or sha256_bytes(raw) != 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
+    expected_members = {
+        "schema_version",
+        "range_index",
+        "first_key",
+        "last_key",
+        "entry_count",
+        "facts_sha256",
+        "history_sha256",
+        "range_binding_sha256",
+        "backends",
+        "posting_backend_coordinate",
+        "members",
+        "root_sha256",
+    }
+    if (
+        not isinstance(manifest, dict)
+        or set(manifest) != expected_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["posting_backend_coordinate"] != posting_backend_coordinate or manifest[
+        "backends"
+    ] != [backend.coordinate for backend in backends]:
+        raise _refuse(
+            "PACKED_RANGE_MANIFEST",
+            "packed.range.backends",
+            "a range names exactly the generation's backends and posting backend",
+        )
+
+    descriptors = [
+        member_descriptor_from_dict(value, path=f"packed.range.members[{index}]")
+        for index, value in enumerate(manifest["members"])
+    ]
+    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"]:
+        raise _refuse(
+            "PACKED_RANGE_MANIFEST",
+            "packed.range.range_binding_sha256",
+            "the range binding does not reproduce from this range's own interval and facts order",
+        )
+    for descriptor in descriptors:
+        if (
+            descriptor.range_index != manifest["range_index"]
+            or descriptor.first_key != manifest["first_key"]
+            or descriptor.last_key != manifest["last_key"]
+            or descriptor.entry_count != manifest["entry_count"]
+            or descriptor.facts_sha256 != manifest["facts_sha256"]
+            or descriptor.range_binding_sha256 != binding
+        ):
+            raise _refuse(
+                "PACKED_MEMBER_BINDING",
+                "packed.range.members[]",
+                "a member descriptor is bound to another range",
+            )
+
+    facts = _verified_member(directory, _one(descriptors, "facts"), maximum=MAX_FACTS_MEMBER_BYTES)
+    entry_ids, classification_counts = _verify_facts_member(facts, manifest)
+    _verified_member(directory, _one(descriptors, "history"), maximum=MAX_HISTORY_MEMBER_BYTES)
+
+    vectors_by_backend: dict[str, dict[str, tuple[tuple[int, ...], ...]]] = {}
+    vector_payload_sha256s: list[str] = []
+    for backend in backends:
+        layers: dict[str, tuple[tuple[int, ...], ...]] = {}
+        for descriptor in descriptors:
+            if descriptor.kind != "vector" or descriptor.backend_coordinate != backend.coordinate:
+                continue
+            raw_member = _verified_member(directory, descriptor, maximum=MAX_VECTOR_MEMBER_BYTES)
+            member = parse_vector_member(raw_member, descriptor=descriptor)
+            vector_payload_sha256s.append(sha256_bytes(raw_member[MEMBER_HEADER_BYTES:]))
+            if descriptor.dimensions != backend.dimensions:
+                raise _refuse(
+                    "PACKED_MEMBER_DIMENSION",
+                    "packed.range.members[]",
+                    "a vector member does not carry its backend's dimension",
+                )
+            if member.layer in layers:
+                raise _refuse(
+                    "PACKED_MEMBER_LAYER",
+                    "packed.range.members[]",
+                    "a backend carries each layer exactly once",
+                )
+            layers[member.layer] = member.vectors
+        if set(layers) != set(EMBEDDING_LAYERS):
+            raise _refuse(
+                "PACKED_MEMBER_LAYER",
+                "packed.range.members[]",
+                f"every backend closes over the four layers {list(EMBEDDING_LAYERS)}",
+            )
+        vectors_by_backend[backend.coordinate] = layers
+
+    bound_sha256s: list[str] = []
+    for backend in backends:
+        descriptor = _one(
+            [item for item in descriptors if item.backend_coordinate == backend.coordinate], "bound"
+        )
+        raw_member = _verified_member(
+            directory, descriptor, maximum=bound_segment_bytes(dimensions=backend.dimensions)
+        )
+        segment = parse_bound_segment(raw_member, descriptor=descriptor)
+        exact = compute_layer_bounds(
+            vectors_by_backend[backend.coordinate], dimensions=backend.dimensions
+        )
+        _verify_bounds(segment.bounds, exact)
+        bound_sha256s.append(descriptor.sha256)
+
+    posting_descriptors = [item for item in descriptors if item.kind == "posting"]
+    if not MIN_POSTING_SEGMENTS <= len(posting_descriptors) <= MAX_POSTING_SEGMENTS:
+        raise _refuse(
+            "PACKED_POSTING_SEGMENTS",
+            "packed.range.members[]",
+            f"a range carries {MIN_POSTING_SEGMENTS} to {MAX_POSTING_SEGMENTS} posting segments",
+        )
+    observed: list[PostingTerm] = []
+    for expected_index, descriptor in enumerate(posting_descriptors):
+        if descriptor.segment_index != expected_index:
+            raise _refuse(
+                "PACKED_POSTING_SEGMENTS",
+                "packed.range.members[]",
+                "posting segments are published in ascending segment order",
+            )
+        raw_member = _verified_member(directory, descriptor, maximum=MAX_POSTING_SEGMENT_BYTES)
+        segment = parse_posting_segment(raw_member, descriptor=descriptor)
+        if descriptor.term_count != len(segment.terms):
+            raise _refuse(
+                "PACKED_POSTING_TERM",
+                "packed.range.members[]",
+                "a posting descriptor's term count differs from its segment",
+            )
+        if observed and segment.terms and segment.terms[0] <= observed[-1]:
+            raise _refuse(
+                "PACKED_POSTING_ORDER",
+                "packed.range.members[]",
+                "posting terms ascend across segment boundaries too",
+            )
+        observed.extend(segment.terms)
+    posting_dimensions = next(
+        backend.dimensions
+        for backend in backends
+        if backend.coordinate == posting_backend_coordinate
+    )
+    recomputed = compute_layer_postings(
+        vectors_by_backend[posting_backend_coordinate], dimensions=posting_dimensions
+    )
+    if tuple(observed) != recomputed:
+        raise _refuse(
+            "PACKED_POSTING_MISMATCH",
+            "packed.range.postings",
+            "the published postings are not the postings these packs contain",
+        )
+
+    return VerifiedPackedRange(
+        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"],
+        history_sha256=manifest["history_sha256"],
+        range_binding_sha256=manifest["range_binding_sha256"],
+        manifest_bytes=len(raw),
+        member_count=len(descriptors),
+        member_sha256s=tuple(descriptor.sha256 for descriptor in descriptors),
+        vector_payload_sha256s=tuple(vector_payload_sha256s),
+        posting_sha256s=tuple(descriptor.sha256 for descriptor in posting_descriptors),
+        bound_sha256s=tuple(bound_sha256s),
+        posting_term_count=len(observed),
+        entry_ids=entry_ids,
+        classification_counts=classification_counts,
+    )
+
+
+def _one(descriptors: Sequence[PackedMemberDescriptor], kind: str) -> PackedMemberDescriptor:
+    found = [descriptor for descriptor in descriptors if descriptor.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 _verified_member(
+    directory: PackedDirectory, descriptor: PackedMemberDescriptor, *, maximum: int
+) -> bytes:
+    raw = directory.read_member(descriptor.sha256, kind=descriptor.kind, maximum=maximum)
+    if raw is None or len(raw) != descriptor.bytes or sha256_bytes(raw) != descriptor.sha256:
+        raise _refuse(
+            "PACKED_MEMBER_DIGEST",
+            "packed.range.members[]",
+            "an installed member is not the member its descriptor binds",
+        )
+    return raw
+
+
+def _verify_facts_member(
+    raw: bytes, manifest: Mapping[str, Any]
+) -> tuple[tuple[str, ...], tuple[tuple[str, int], ...]]:
+    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") != manifest["range_index"]
+        or payload.get("entry_count") != manifest["entry_count"]
+        or not isinstance(payload.get("entries"), list)
+        or len(payload["entries"]) != manifest["entry_count"]
+    ):
+        raise _refuse("PACKED_FACTS_MEMBER", "packed.range.facts", "facts member contract differs")
+    entry_ids: list[str] = []
+    classification_counts = dict.fromkeys(PACKED_CLASSIFICATIONS, 0)
+    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) != {
+            "key",
+            "entry_id",
+            "classification",
+            "semantic_facts_digest",
+            "entry_sha256",
+            "entry_json",
+        }:
+            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")
+        if item["classification"] not in PACKED_CLASSIFICATIONS:
+            raise _refuse(
+                "PACKED_FACTS_MEMBER", path, "an entry carries a publishable classification"
+            )
+        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
+        entry_ids.append(item["entry_id"])
+        classification_counts[item["classification"]] += 1
+        keys.append(item["key"])
+    if keys[0] != manifest["first_key"] or keys[-1] != manifest["last_key"]:
+        raise _refuse(
+            "PACKED_RANGE_ORDER",
+            "packed.range.facts",
+            "the facts member does not span the interval its range claims",
+        )
+    return tuple(entry_ids), tuple(classification_counts.items())
+
+
+def _verify_bounds(published: Sequence[LayerBounds], exact: Sequence[LayerBounds]) -> None:
+    for layer_ordinal, (summary, truth) in enumerate(zip(published, exact, strict=True)):
+        published_minima, published_maxima = summary
+        exact_minima, exact_maxima = truth
+        for dimension in range(len(exact_minima)):
+            if (
+                published_minima[dimension] > exact_minima[dimension]
+                or published_maxima[dimension] < exact_maxima[dimension]
+            ):
+                raise _refuse(
+                    "PACKED_BOUND_NOT_CONSERVATIVE",
+                    f"packed.range.bounds[{layer_ordinal}][{dimension}]",
+                    "a published bound excludes a vector this range actually contains",
+                )
+        if published_minima != exact_minima or published_maxima != exact_maxima:
+            raise _refuse(
+                "PACKED_BOUND_MISMATCH",
+                f"packed.range.bounds[{layer_ordinal}]",
+                "a published bound is not the exact publisher-derived summary of these packs",
+            )
+
+
+def verify_packed_generation(
+    root: Path, *, expected_head_sha256: str, root_descriptor: int | None = None
+) -> VerifiedPackedGeneration:
+    """Read one published generation end to end and refuse anything that is not exactly it."""
+
+    directory = PackedDirectory(Path(root), root_descriptor=root_descriptor)
+    with directory.opened():
+        raw = directory.read(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"
+            )
+        digest = sha256_bytes(raw)
+        if digest != expected_head_sha256:
+            raise _refuse(
+                "PACKED_HEAD_MISMATCH",
+                "packed.head",
+                "the installed head is not the caller's exact generation",
+            )
+        head = _parse_head(raw)
+        backends = tuple(
+            PackedBackend(
+                coordinate=item["coordinate"],
+                dimensions=item["dimensions"],
+                quantization=item["quantization"],
+                query_safe=item["query_safe"],
+            )
+            for item in head["backends"]
+        )
+        posting_backend = head["posting_backend_coordinate"]
+        descriptors = [
+            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 expected range chain is not the chain of its own descriptors",
+            )
+        member_count = 0
+        posting_term_count = 0
+        vector_payload_sha256s: list[str] = []
+        posting_member_sha256s: list[str] = []
+        bound_member_sha256s: list[str] = []
+        classification_counts = dict.fromkeys(PACKED_CLASSIFICATIONS, 0)
+        fresh_range_count = 0
+        previous: VerifiedPackedRange | None = None
+        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",
+                )
+            verified = verify_packed_range(
+                directory,
+                descriptor.manifest_sha256,
+                backends=backends,
+                posting_backend_coordinate=posting_backend,
+            )
+            if (
+                verified.range_index != descriptor.range_index
+                or verified.first_key != descriptor.first_key
+                or verified.last_key != descriptor.last_key
+                or verified.entry_count != descriptor.entry_count
+                or verified.facts_sha256 != descriptor.facts_sha256
+                or verified.range_binding_sha256 != descriptor.range_binding_sha256
+                or verified.manifest_bytes != descriptor.manifest_bytes
+                or verified.member_count != descriptor.member_count
+            ):
+                raise _refuse(
+                    "PACKED_RANGE_DIGEST",
+                    f"packed.head.ranges[{position}]",
+                    "a range descriptor does not describe the range it names",
+                )
+            is_final = position == len(descriptors) - 1
+            if not is_final and verified.entry_count != RANGE_ENTRIES:
+                raise _refuse(
+                    "PACKED_RANGE_SIZE",
+                    f"packed.head.ranges[{position}]",
+                    f"every range but the final one holds exactly {RANGE_ENTRIES} entries",
+                )
+            if previous is not None and not (
+                previous.last_key.encode("utf-8") < verified.first_key.encode("utf-8")
+            ):
+                raise _refuse(
+                    "PACKED_RANGE_ORDER",
+                    f"packed.head.ranges[{position}]",
+                    "ranges are consecutive intervals that ascend by key",
+                )
+            previous = verified
+            member_count += verified.member_count
+            posting_term_count += verified.posting_term_count
+            vector_payload_sha256s.extend(verified.vector_payload_sha256s)
+            posting_member_sha256s.extend(verified.posting_sha256s)
+            bound_member_sha256s.extend(verified.bound_sha256s)
+            range_counts = dict(verified.classification_counts)
+            for classification in PACKED_CLASSIFICATIONS:
+                classification_counts[classification] += range_counts[classification]
+            if any(range_counts[name] for name in ("changed", "new")):
+                fresh_range_count += 1
+        entry_count = sum(descriptor.entry_count for descriptor in descriptors)
+        if entry_count != head["entry_count"] or len(descriptors) != head["range_count"]:
+            raise _refuse(
+                "PACKED_HEAD_EXPECTED",
+                "packed.head.counts",
+                "the head's own counts disagree with its range descriptors",
+            )
+        return VerifiedPackedGeneration(
+            head_sha256=digest,
+            head=head,
+            range_count=len(descriptors),
+            entry_count=entry_count,
+            member_count=member_count,
+            posting_term_count=posting_term_count,
+            backends=tuple(backend.coordinate for backend in backends),
+            classification_counts=tuple(classification_counts.items()),
+            fresh_range_count=fresh_range_count,
+            vector_payload_sha256s=tuple(vector_payload_sha256s),
+            posting_member_sha256s=tuple(posting_member_sha256s),
+            bound_member_sha256s=tuple(bound_member_sha256s),
+        )
+
+
+_HEAD_MEMBERS = frozenset(
+    {
+        "schema_version",
+        "provider_id",
+        "generation_sha256",
+        "predecessor_head_sha256",
+        "backends",
+        "posting_backend_coordinate",
+        "range_count",
+        "entry_count",
+        "coverage",
+        "ranges",
+        "ranges_chain_sha256",
+        "counters",
+        "invocations",
+        "terminal_sha256",
+        "root_sha256",
+    }
+)
+
+
+def _parse_head(raw: bytes) -> dict[str, Any]:
+    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 set(head) != _HEAD_MEMBERS
+        or head["schema_version"] != PACKED_HEAD_SCHEMA
+        or not isinstance(head["ranges"], list)
+        or not isinstance(head["backends"], list)
+        or not isinstance(head["counters"], dict)
+    ):
+        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["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",
+        )
+    if not 1 <= len(head["backends"]) <= MAX_PACKED_BACKENDS:
+        raise _refuse(
+            "PACKED_BACKEND",
+            "packed.head.backends",
+            f"a packed generation carries 1 to {MAX_PACKED_BACKENDS} backends",
+        )
+    if set(head["counters"]) != set(COUNTER_MEMBERS):
+        raise _refuse(
+            "PACKED_COUNTER_CONTRACT",
+            "packed.head.counters",
+            f"the head carries exactly {list(COUNTER_MEMBERS)}",
+        )
+    if not coverage_is_valid(head["coverage"]):
+        raise _refuse(
+            "PACKED_HEAD_COVERAGE",
+            "packed.head.coverage",
+            "a published generation states what it covers and what it drew from",
+        )
+    return head