mostlyright-data 0.9.0__py3-none-any.whl

mostlyright/data_harness/ux/commands/catalog_publish.py

@@ -0,0 +1,1838 @@
+"""``mr-data catalog-publish``: classify one authored generation and publish it, once.
+
+The third and last provider-scale mutation.  It is handed the two receipts the first two stages
+wrote, together with the fingerprints of their exact bytes, and it refuses to start unless those
+two documents describe one staging checkpoint and one authored generation that is complete.  It
+then classifies the sweep against its predecessor identity/history, publishes one range-local
+packed generation, has an independent final reader scan the installed generation back off disk,
+and writes one composite receipt.
+
+That composite receipt is the authoritative evidence.  It *carries* the exact harvest and author
+receipts it was handed rather than a summary of them, binds the execution coordinate, the staging
+indexes, the policy, the classification, every range, vector, posting and bound digest the
+publication produced, the ordered per-invocation counter records and their totals, the expected
+final head, and the independent readback.  Downstream verification reads that document; it never
+reconstructs one from counts.
+
+Carrying a receipt is not believing it.  Every summary in the author receipt is re-derived from
+the authored manifest and the registered policy, and the three members that are not summaries --
+the retained work journal's fingerprint, the bounds the authoring invocation ran under, and the
+bytes it wrote -- are reconciled against the journal and the shards still on disk in the author
+root, as far as retained evidence reaches.  It reaches an exact value for one of them, an
+interval for another, and a floor for the rest; the composite states which of those it got for
+each, rather than carrying any of them as though this command had established it.
+
+A publication that stops on a bound its caller stated, or on an operator's interruption, writes
+the other receipt this command can write: one typed-incomplete composite receipt bound to the work
+journal the publisher left behind, to this output root, to the ranges that are already immutable,
+and to the ordered per-invocation counter records the work got as far as.  ``--resume`` validates
+exactly that receipt, requires the journal on disk to still be the one it names, continues the
+publisher's own resume path, and replaces the receipt with the complete one.
+
+A publication that is *killed* rather than stopped -- power, sleep, the kernel -- never writes
+that receipt, because nothing in it runs again.  Before the packed head becomes visible, the
+publisher installs a terminal record that the head binds and that captures the exact final journal
+and packed-receipt inputs.  ``--resume`` can therefore adopt either unfinished range work or a
+published head whose composite receipt is still absent, after requiring the retained state to be
+this argv's exact publication.  The composite an adopted resume ends with is the same document any
+other publication writes.  A resume with no retained publication is refused rather than started,
+and a complete receipt is never replaced.
+
+This command reaches no network.  It takes no key, no endpoint, no URL and no header, and its
+import closure holds nothing from ``acquisition``.
+"""
+
+from __future__ import annotations
+
+import argparse
+import contextlib
+import os
+from collections.abc import Mapping, Sequence
+from datetime import UTC, datetime
+from pathlib import Path
+from typing import Any
+
+from mostlyright.data_harness.canonical import canonical_sha256, sha256_bytes
+from mostlyright.data_harness.sources.catalog.authoring_policy import resolve_authoring_policy
+from mostlyright.data_harness.sources.catalog.authoring_shards import (
+    AUTHORING_JOURNAL_SCHEMA,
+    AUTHORING_MANIFEST_SCHEMA,
+    AUTHORING_RECEIPT_SCHEMA,
+    JOURNAL_FILENAME,
+    MANIFEST_FILENAME,
+    MAX_AUTHORING_JOURNAL_BYTES,
+    MAX_AUTHORING_MANIFEST_BYTES,
+    MAX_AUTHORING_SHARD_BYTES,
+    MAX_AUTHORING_SHARD_ENTRIES,
+    shard_descriptor_is_valid,
+)
+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 LexicalHashingBackend
+from mostlyright.data_harness.sources.catalog.generation_receipt import (
+    GENERATION_RECEIPT_SCHEMA,
+    HARVEST_RECEIPT_SCHEMA,
+    MAX_COMPOSITE_ARRAY_ITEMS,
+    MAX_COMPOSITE_RECEIPT_BYTES,
+    MAX_PREDECESSOR_HEAD_BYTES,
+    MAX_PREDECESSOR_HEAD_DEPTH,
+    MAX_PREDECESSOR_RANGE_DESCRIPTORS,
+    MAX_STAGE_RECEIPT_MEMBERS,
+    ReceiptInstallation,
+    compose_generation_receipt,
+    install_receipt,
+    is_digest,
+    load_bounded_json,
+    load_bounded_json_at,
+    load_execution_coordinate,
+    load_stage_receipt,
+    publication_output_lock,
+    receipt_installation_lock,
+    require_output_root_identity,
+    retained_child_directory,
+    retained_incomplete_receipt,
+    retained_input_directory,
+    root_coordinate,
+)
+from mostlyright.data_harness.sources.catalog.identity_history import (
+    IDENTITY_MANIFEST_FILENAME,
+    IDENTITY_MANIFEST_SCHEMA,
+)
+from mostlyright.data_harness.sources.catalog.packed_catalog import (
+    COUNTER_MEMBERS,
+    MAX_RANGE_DESCRIPTORS,
+    PACKED_HEAD_FILENAME,
+    RANGE_ENTRIES,
+    verify_packed_generation,
+)
+from mostlyright.data_harness.sources.catalog.packed_writer import (
+    MAX_PACKED_JOURNAL_BYTES,
+    PACKED_JOURNAL_FILENAME,
+    PACKED_JOURNAL_SCHEMA,
+    PackedLimits,
+    admit_authored_generation,
+    publish_packed_generation,
+    verify_packed_receipt,
+)
+from mostlyright.data_harness.sources.catalog.streaming_delta import (
+    DELTA_CLASSIFICATIONS,
+    DELTA_IDENTITY_DIRNAME,
+    DELTA_MANIFEST_FILENAME,
+    MAX_DELTA_MANIFEST_BYTES,
+    StreamingDeltaLimits,
+    SweepMeasures,
+    run_streaming_delta,
+)
+from mostlyright.data_harness.sources.contracts import SourceContractError
+from mostlyright.data_harness.ux.commands import CommandSpec
+
+PUBLISH_INCOMPLETE_STATUS = "generation_incomplete"
+PUBLISH_COMPLETE_STATUS = "generation_published"
+
+#: The refusals that mean *stopped*, not *wrong*: a publication that reached a bound its caller
+#: stated leaves every completed range durable and a typed-incomplete work journal beside them.
+#: Anything else is a defect in the generation and is raised.
+PUBLICATION_INTERRUPTIONS = frozenset({"PACKED_DISK_LIMIT", "PACKED_WALL_LIMIT"})
+
+#: What an operator's interruption is recorded as. A budget records the bound it reached instead.
+PUBLISH_INTERRUPTED_REASON = "PUBLISH_INTERRUPTED"
+
+#: The two backend coordinates this command admits, spelled the way the closed argv spells them.
+LEXICAL_BACKENDS = ("lexical-hash-v1",)
+NEURAL_BACKENDS = ("minilm-v1",)
+
+#: Directories this command owns inside its own output root.
+DELTA_DIRNAME = "delta"
+
+#: Every predecessor coordinate, and the mode that requires all six of them.
+_PREDECESSOR_ARGUMENTS = (
+    "predecessor_identity_root",
+    "predecessor_identity_digest",
+    "predecessor_history_root",
+    "predecessor_history_digest",
+    "predecessor_catalog_root",
+    "predecessor_catalog_digest",
+)
+
+#: The fixed shard/range shape this command may state but never widen.
+_FIXED = {
+    "max_ranges": MAX_RANGE_DESCRIPTORS,
+    "max_range_entries": RANGE_ENTRIES,
+    "max_facts_bytes": 8_388_608,
+    "max_member_bytes": 8_388_608,
+    "max_posting_segments": 8,
+    "max_open_files": 16,
+}
+
+_AUTHOR_RECEIPT_MEMBERS = frozenset(
+    {
+        "schema_version",
+        "status",
+        "reason_code",
+        "policy_id",
+        "policy_sha256",
+        "provider_id",
+        "harvester_coordinate",
+        "staging",
+        "coverage",
+        "counts",
+        "layer_text_digests",
+        "shard_count",
+        "shards",
+        "limits",
+        "manifest_sha256",
+        "journal_sha256",
+        "output_bytes",
+        "harvest_receipt_sha256",
+        "output_root_sha256",
+        "execution",
+    }
+)
+_AUTHOR_MANIFEST_MEMBERS = frozenset(
+    {
+        "schema_version",
+        "policy_id",
+        "policy_sha256",
+        "staging",
+        "coverage",
+        "counts",
+        "layer_text_digests",
+        "shards",
+        "root_sha256",
+    }
+)
+_AUTHOR_STAGING_MEMBERS = frozenset(
+    {
+        "checkpoint_sha256",
+        "config_sha256",
+        "endpoint",
+        "harvester_coordinate",
+        "pass_number",
+        "pass_map_sha256",
+        "pass_map_root_sha256",
+        "unique_records",
+        "raw_response_index_root_sha256",
+        "raw_response_index_count",
+        "normalized_page_index_root_sha256",
+        "normalized_page_index_count",
+        "record_index_root_sha256",
+        "record_index_count",
+    }
+)
+_AUTHOR_COUNT_MEMBERS = frozenset(
+    {"records", "authored", "flagged", "skipped", "failed", "layer_text_truncated"}
+)
+_AUTHOR_LIMIT_MEMBERS = frozenset(
+    {
+        "max_records",
+        "max_input_bytes",
+        "max_shard_entries",
+        "max_shard_bytes",
+        "max_disk_bytes",
+        "max_wall_seconds",
+    }
+)
+_AUTHOR_JOURNAL_MEMBERS = frozenset(
+    {
+        "schema_version",
+        "policy_sha256",
+        "staging_checkpoint_sha256",
+        "coverage",
+        "shards",
+        "counts",
+        "layer_text_digests",
+        "last_provider_record_id",
+        "reason_code",
+    }
+)
+
+#: Exactly how far this command got with each author-receipt member that is *not* a manifest
+#: summary. Every one of these used to be accepted on its own shape, and reconciling them is
+#: what this command now does; but three of them can only be bounded and three cannot be reached
+#: at all, and a composite that named only the unreachable ones would tell a reader the bounded
+#: ones had been established. So the composite states the standing of each, in these four terms:
+#:
+#: ``bound``             re-derived exactly from evidence retained in the author root.
+#: ``bounded_interval``  reconciled against an interval the retained outputs allow rather than an
+#:                       exact value, because the member measures one invocation of a stage that
+#:                       may have run more than once.
+#: ``bounded_below``     the authored generation proves the bound was at least this wide. Nothing
+#:                       retained can show it was not stated wider than the invocation ran under.
+#: ``unverified``        bounds work rather than output. No evidence in the author root reaches
+#:                       it, and this command does not pretend otherwise.
+AUTHOR_CLAIM_RECONCILIATION = {
+    "journal_sha256": "bound",
+    "limits.max_disk_bytes": "unverified",
+    "limits.max_input_bytes": "unverified",
+    "limits.max_records": "bounded_below",
+    "limits.max_shard_bytes": "bounded_below",
+    "limits.max_shard_entries": "bounded_below",
+    "limits.max_wall_seconds": "unverified",
+    "output_bytes": "bounded_interval",
+}
+
+
+def add_arguments(parser: argparse.ArgumentParser) -> None:
+    parser.add_argument(
+        "--author-root", type=Path, required=True, help="the authored generation's shard root"
+    )
+    parser.add_argument(
+        "--author-receipt", type=Path, required=True, help="the exact authoring stage receipt"
+    )
+    parser.add_argument(
+        "--author-receipt-sha256", required=True, help="the exact authoring receipt fingerprint"
+    )
+    parser.add_argument(
+        "--harvest-receipt", type=Path, required=True, help="the exact harvest stage receipt"
+    )
+    parser.add_argument(
+        "--harvest-receipt-sha256", required=True, help="the exact harvest receipt fingerprint"
+    )
+    parser.add_argument(
+        "--output-root", type=Path, required=True, help="the packed catalog output root"
+    )
+    parser.add_argument(
+        "--receipt-file",
+        type=Path,
+        required=True,
+        help="where this generation's one composite receipt is installed",
+    )
+    parser.add_argument(
+        "--execution-manifest",
+        type=Path,
+        required=True,
+        help="the committed execution coordinate document",
+    )
+    parser.add_argument(
+        "--execution-commit", required=True, help="the exact commit that coordinate was cut at"
+    )
+    parser.add_argument(
+        "--predecessor-mode",
+        choices=("none", "exact"),
+        required=True,
+        help="whether this generation has an exact predecessor, or none at all",
+    )
+    parser.add_argument(
+        "--predecessor-identity-root", type=Path, help="the predecessor identity generation root"
+    )
+    parser.add_argument(
+        "--predecessor-identity-digest", help="the exact predecessor identity manifest fingerprint"
+    )
+    parser.add_argument(
+        "--predecessor-history-root", type=Path, help="the predecessor classification root"
+    )
+    parser.add_argument(
+        "--predecessor-history-digest", help="the exact predecessor delta manifest fingerprint"
+    )
+    parser.add_argument(
+        "--predecessor-catalog-root", type=Path, help="the predecessor packed catalog root"
+    )
+    parser.add_argument(
+        "--predecessor-catalog-digest", help="the exact predecessor packed head fingerprint"
+    )
+    parser.add_argument(
+        "--lexical-backend",
+        choices=LEXICAL_BACKENDS,
+        required=True,
+        help="the closed lexical representation this generation publishes",
+    )
+    parser.add_argument(
+        "--neural-backend",
+        choices=NEURAL_BACKENDS,
+        help="the closed neural representation this generation also publishes",
+    )
+    parser.add_argument("--neural-pin", help="the exact pinned model fingerprint")
+    parser.add_argument("--model-root", type=Path, help="the governed local model root")
+    for name, ceiling in _FIXED.items():
+        parser.add_argument(
+            f"--{name.replace('_', '-')}",
+            type=int,
+            required=True,
+            help=f"the fixed packed bound, which is exactly {ceiling}",
+        )
+    parser.add_argument(
+        "--max-batch-invocations",
+        type=int,
+        required=True,
+        help="maximum batch encode calls across every backend",
+    )
+    parser.add_argument(
+        "--max-encoded-layer-items",
+        type=int,
+        required=True,
+        help="maximum encoded layer texts across every backend",
+    )
+    parser.add_argument(
+        "--max-backend-scalar-invocations",
+        type=int,
+        required=True,
+        help="maximum backend scalar calls across every backend",
+    )
+    parser.add_argument(
+        "--max-encoded-input-bytes",
+        type=int,
+        required=True,
+        help="maximum encoded UTF-8 input bytes across every backend",
+    )
+    parser.add_argument(
+        "--max-disk-bytes", type=int, required=True, help="maximum local working disk bytes"
+    )
+    parser.add_argument(
+        "--max-wall-seconds", type=int, required=True, help="maximum cumulative publication seconds"
+    )
+    parser.add_argument(
+        "--resume",
+        action="store_true",
+        help="continue the publication this receipt file was left incomplete at",
+    )
+
+
+def run(args: argparse.Namespace) -> dict[str, Any]:
+    _validate_limits(args)
+    predecessor = _predecessor_coordinates(args)
+    execution = load_execution_coordinate(args.execution_manifest, args.execution_commit)
+    output_root = Path(args.output_root)
+    harvest_raw, harvest = load_stage_receipt(
+        args.harvest_receipt,
+        args.harvest_receipt_sha256,
+        label="harvest_receipt",
+        schemas=frozenset({HARVEST_RECEIPT_SCHEMA}),
+    )
+    author_raw, author = load_stage_receipt(
+        args.author_receipt,
+        args.author_receipt_sha256,
+        label="author_receipt",
+        schemas=frozenset({AUTHORING_RECEIPT_SCHEMA}),
+    )
+    _verify_handoff(
+        harvest,
+        author,
+        harvest_sha256=sha256_bytes(harvest_raw),
+        execution=execution,
+    )
+    manifest_raw, manifest = _author_manifest(Path(args.author_root), author["manifest_sha256"])
+    author_evidence = _verify_author_receipt(
+        author,
+        manifest=manifest,
+        manifest_bytes=len(manifest_raw),
+        harvest=harvest,
+        harvest_sha256=sha256_bytes(harvest_raw),
+        author_root=Path(args.author_root),
+        execution=execution,
+    )
+    admit_authored_generation(Path(args.author_root), manifest)
+    predecessor_identity_context = (
+        contextlib.nullcontext(None)
+        if predecessor is None
+        else retained_input_directory(
+            predecessor["identity_root"],
+            label="predecessor_identity_root.manifest",
+            code_prefix="GENERATION",
+            refusal=SourceContractError,
+        )
+    )
+    with predecessor_identity_context as predecessor_identity_descriptor:
+        predecessor_heads = _read_predecessor_heads(
+            predecessor, identity_descriptor=predecessor_identity_descriptor
+        )
+        with publication_output_lock(
+            output_root,
+            label="output_root",
+            code_prefix="PUBLISH",
+            refusal=SourceContractError,
+        ) as output_descriptor:
+            with receipt_installation_lock(
+                args.receipt_file,
+                label="receipt_file",
+                code_prefix="PUBLISH",
+                refusal=SourceContractError,
+            ) as receipt_installation:
+                return _run_locked(
+                    args,
+                    output_descriptor=output_descriptor,
+                    receipt_installation=receipt_installation,
+                    predecessor=predecessor,
+                    predecessor_identity_descriptor=predecessor_identity_descriptor,
+                    predecessor_heads=predecessor_heads,
+                    execution=execution,
+                    output_root=output_root,
+                    harvest_raw=harvest_raw,
+                    harvest=harvest,
+                    author_raw=author_raw,
+                    author=author,
+                    manifest=manifest,
+                    author_evidence=author_evidence,
+                )
+
+
+def _run_locked(
+    args: argparse.Namespace,
+    *,
+    output_descriptor: int,
+    receipt_installation: ReceiptInstallation,
+    predecessor: dict[str, Any] | None,
+    predecessor_identity_descriptor: int | None,
+    predecessor_heads: dict[str, Any] | None,
+    execution: dict[str, Any],
+    output_root: Path,
+    harvest_raw: bytes,
+    harvest: dict[str, Any],
+    author_raw: bytes,
+    author: dict[str, Any],
+    manifest: dict[str, Any],
+    author_evidence: dict[str, Any],
+) -> dict[str, Any]:
+    retained = None
+    orphaned_journal = False
+    terminal_publication = False
+    if args.resume:
+        retained = retained_incomplete_receipt(
+            args.receipt_file,
+            maximum=MAX_COMPOSITE_RECEIPT_BYTES,
+            label="receipt_file",
+            schema=GENERATION_RECEIPT_SCHEMA,
+            incomplete_status=PUBLISH_INCOMPLETE_STATUS,
+            output_root=output_root,
+            code_prefix="PUBLISH",
+            refusal=SourceContractError,
+        )
+        if retained is None:
+            try:
+                os.stat(PACKED_HEAD_FILENAME, dir_fd=output_descriptor, follow_symlinks=False)
+                terminal_publication = True
+            except FileNotFoundError:
+                terminal_publication = False
+            if (
+                _retained_journal(output_descriptor, logical_output_root=output_root) is None
+                and not terminal_publication
+            ):
+                raise SourceContractError(
+                    "PUBLISH_RESUME_RECEIPT",
+                    "receipt_file",
+                    "a resume continues the typed-incomplete receipt its interruption left behind, "
+                    "or the work journal a publication was killed in the middle of",
+                )
+            orphaned_journal = not terminal_publication
+        else:
+            _require_retained_journal(retained, output_descriptor, logical_output_root=output_root)
+    elif Path(args.receipt_file).exists():
+        raise SourceContractError(
+            "PUBLISH_RECEIPT_DESTINATION",
+            "receipt_file",
+            "receipt destination must be an absent no-follow path",
+        )
+
+    require_output_root_identity(
+        output_root,
+        output_descriptor,
+        label="output_root",
+        code_prefix="PUBLISH",
+        refusal=SourceContractError,
+    )
+    delta_root = output_root / DELTA_DIRNAME
+    logical_delta_root = output_root / DELTA_DIRNAME
+    classification = _classify(
+        args,
+        author=author,
+        harvest=harvest,
+        delta_root=delta_root,
+        output_descriptor=output_descriptor,
+        coordinate_root=logical_delta_root,
+        predecessor=predecessor,
+        predecessor_identity_descriptor=predecessor_identity_descriptor,
+        resumed=args.resume,
+    )
+    backends = _backends(args)
+    # Every block that describes this generation rather than this invocation of it. Both receipts
+    # this command can write state exactly these, so an interruption cannot describe its inputs
+    # differently from the publication that completes them.
+    common: dict[str, Any] = {
+        "components": {
+            "harvest_receipt": harvest,
+            "harvest_receipt_sha256": sha256_bytes(harvest_raw),
+            "author_receipt": author,
+            "author_receipt_sha256": sha256_bytes(author_raw),
+        },
+        "execution": execution,
+        "staging": author["staging"],
+        "policy": {
+            "policy_id": author["policy_id"],
+            "policy_sha256": author["policy_sha256"],
+            "provider_id": author["provider_id"],
+            "harvester_coordinate": author["harvester_coordinate"],
+        },
+        "author": {
+            "manifest_sha256": author["manifest_sha256"],
+            "root_sha256": manifest["root_sha256"],
+            "shard_count": len(manifest["shards"]),
+            # What this generation covers, stated in the composite's own summary as well as
+            # carried in the author receipt beside it. A reader of the authoritative receipt
+            # answers "is this the whole sweep" without opening a component document.
+            "coverage": manifest["coverage"],
+            "counts": manifest["counts"],
+            "layer_text_digests": manifest["layer_text_digests"],
+            **author_evidence,
+        },
+        "classification": classification,
+        "predecessor": predecessor_heads,
+        "limits": _limits_evidence(args),
+    }
+    if retained is not None:
+        _require_retained_generation(retained, common)
+    publication_binding_sha256 = _generation_binding_sha256(common)
+    if orphaned_journal:
+        _adopt_orphaned_journal(
+            author=author,
+            predecessor=predecessor,
+            output_root=output_root,
+            output_descriptor=output_descriptor,
+            publication_binding_sha256=publication_binding_sha256,
+        )
+    try:
+        with retained_child_directory(
+            output_descriptor,
+            DELTA_DIRNAME,
+            create=False,
+            label="delta.output",
+            code_prefix="PUBLISH",
+            refusal=SourceContractError,
+        ) as delta_descriptor:
+            publication = publish_packed_generation(
+                delta_root=delta_root,
+                delta_descriptor=delta_descriptor,
+                expected_delta_manifest_sha256=classification["manifest_sha256"],
+                authoring_root=Path(args.author_root),
+                expected_authoring_manifest_sha256=author["manifest_sha256"],
+                output_root=output_root,
+                output_descriptor=output_descriptor,
+                backends=backends,
+                predecessor_root=None if predecessor is None else predecessor["catalog_root"],
+                expected_predecessor_head_sha256=(
+                    None if predecessor is None else predecessor["catalog_digest"]
+                ),
+                expected_predecessor_generation_sha256=(
+                    None if predecessor is None else predecessor["history_digest"]
+                ),
+                limits=PackedLimits(
+                    max_ranges=args.max_ranges,
+                    max_entries=args.max_ranges * args.max_range_entries,
+                    max_disk_bytes=args.max_disk_bytes,
+                    max_wall_seconds=args.max_wall_seconds,
+                ),
+                resume=args.resume,
+                publication_binding_sha256=publication_binding_sha256,
+            )
+    except SourceContractError as refusal:
+        if refusal.code not in PUBLICATION_INTERRUPTIONS:
+            raise
+        require_output_root_identity(
+            output_root,
+            output_descriptor,
+            label="output_root",
+            code_prefix="PUBLISH",
+            refusal=SourceContractError,
+        )
+        stopped = _incomplete_receipt(
+            args,
+            common=common,
+            output_root=output_root,
+            output_descriptor=output_descriptor,
+            reason_code=refusal.code,
+            retained=retained,
+            receipt_installation=receipt_installation,
+        )
+        if stopped is None:
+            raise
+        return stopped
+    except KeyboardInterrupt:
+        require_output_root_identity(
+            output_root,
+            output_descriptor,
+            label="output_root",
+            code_prefix="PUBLISH",
+            refusal=SourceContractError,
+        )
+        stopped = _incomplete_receipt(
+            args,
+            common=common,
+            output_root=output_root,
+            output_descriptor=output_descriptor,
+            reason_code=PUBLISH_INTERRUPTED_REASON,
+            retained=retained,
+            receipt_installation=receipt_installation,
+        )
+        if stopped is None:
+            raise
+        return stopped
+    receipt = publication.receipt
+    _verify_work_budget(args, receipt)
+    verify_packed_receipt(receipt, root=output_root, root_descriptor=output_descriptor)
+    installed = verify_packed_generation(
+        output_root,
+        expected_head_sha256=publication.head_sha256,
+        root_descriptor=output_descriptor,
+    )
+
+    payload = compose_generation_receipt(
+        {
+            "schema_version": GENERATION_RECEIPT_SCHEMA,
+            "status": PUBLISH_COMPLETE_STATUS,
+            "reason_code": None,
+            "published_at": datetime.now(UTC).strftime("%Y-%m-%dT%H:%M:%SZ"),
+            "output_root_sha256": root_coordinate(output_root),
+            **common,
+            "publication": _publication_evidence(receipt, publication, backends),
+            "readback": {
+                "reader": "packed_catalog.verify_packed_generation",
+                "head_sha256": installed.head_sha256,
+                "range_count": installed.range_count,
+                "entry_count": installed.entry_count,
+                "member_count": installed.member_count,
+                "posting_term_count": installed.posting_term_count,
+                "backends": list(installed.backends),
+                "readback_sha256": canonical_sha256(
+                    {
+                        "backends": list(installed.backends),
+                        "entry_count": installed.entry_count,
+                        "head_sha256": installed.head_sha256,
+                        "member_count": installed.member_count,
+                        "posting_term_count": installed.posting_term_count,
+                        "range_count": installed.range_count,
+                    }
+                ),
+            },
+        }
+    )
+    require_output_root_identity(
+        output_root,
+        output_descriptor,
+        label="output_root",
+        code_prefix="PUBLISH",
+        refusal=SourceContractError,
+    )
+    install_receipt(
+        args.receipt_file,
+        payload,
+        maximum=MAX_COMPOSITE_RECEIPT_BYTES,
+        label="receipt_file",
+        code_prefix="PUBLISH",
+        refusal=SourceContractError,
+        replaces=retained,
+        installation=receipt_installation,
+        commit_guard=lambda: require_output_root_identity(
+            output_root,
+            output_descriptor,
+            label="output_root",
+            code_prefix="PUBLISH",
+            refusal=SourceContractError,
+        ),
+    )
+    return payload
+
+
+# ------------------------------------------------------------------------------------------------
+# Stopping: the receipt an interruption leaves, and the resume that continues exactly it
+# ------------------------------------------------------------------------------------------------
+
+
+def _retained_journal(
+    output_descriptor: int, *, logical_output_root: Path
+) -> tuple[bytes, dict[str, Any]] | None:
+    """The typed-incomplete work journal an interruption left in this root, or nothing at all.
+
+    A journal that is absent, that is complete, or that was written for another root is not
+    something to continue: each of those is reported as *no retained publication* rather than
+    guessed at, and the caller decides what that means where it stands.
+    """
+
+    try:
+        raw, journal = load_bounded_json_at(
+            output_descriptor,
+            PACKED_JOURNAL_FILENAME,
+            label="packed.journal",
+            maximum=MAX_PACKED_JOURNAL_BYTES,
+            max_depth=MAX_PREDECESSOR_HEAD_DEPTH,
+            max_members=MAX_STAGE_RECEIPT_MEMBERS,
+            max_items=MAX_COMPOSITE_ARRAY_ITEMS,
+        )
+    except SourceContractError as error:
+        if error.code == "GENERATION_INPUT_PATH":
+            try:
+                os.stat(PACKED_JOURNAL_FILENAME, dir_fd=output_descriptor, follow_symlinks=False)
+            except FileNotFoundError:
+                return None
+        raise
+    if (
+        journal.get("schema_version") != PACKED_JOURNAL_SCHEMA
+        or journal.get("status") != "incomplete"
+        or journal.get("head_sha256") is not None
+        or journal.get("output_root") != os.path.abspath(os.fspath(logical_output_root))
+    ):
+        return None
+    return raw, journal
+
+
+def _candidate_journals(output_descriptor: int) -> list[str]:
+    """Every document directly inside this output root that claims to be a packed work journal.
+
+    A publication writes exactly one, under one name. Anything else here -- a copy somebody kept,
+    a journal moved aside by hand -- makes *which publication is being continued* a question, and
+    a resume answers questions like that by refusing rather than by picking one.
+    """
+
+    names: list[str] = []
+    for name in sorted(os.listdir(output_descriptor)):
+        try:
+            _raw, document = load_bounded_json_at(
+                output_descriptor,
+                name,
+                label="packed.journal",
+                maximum=MAX_PACKED_JOURNAL_BYTES,
+                max_depth=MAX_PREDECESSOR_HEAD_DEPTH,
+                max_members=MAX_STAGE_RECEIPT_MEMBERS,
+                max_items=MAX_COMPOSITE_ARRAY_ITEMS,
+            )
+        except SourceContractError:
+            # Anything that is not a bounded canonical document is not a work journal. Directories,
+            # packs, heads and receipts all land here, which is why this reads rather than lists.
+            continue
+        if document.get("schema_version") == PACKED_JOURNAL_SCHEMA:
+            names.append(name)
+    return names
+
+
+def _adopt_orphaned_journal(
+    *,
+    author: Mapping[str, Any],
+    predecessor: Mapping[str, Any] | None,
+    output_root: Path,
+    output_descriptor: int,
+    publication_binding_sha256: str,
+) -> None:
+    """Continue the publication a hard kill left behind, which left no receipt to continue.
+
+    A publication that reaches a bound it was given writes down where it got to. One that is
+    killed outright -- power, sleep, the kernel -- writes nothing, because nothing in it ever runs
+    again: the only state left is the work journal and the immutable members it names. That state
+    is adoptable, and for a multi-hour publication it is the difference between continuing and
+    starting again. It is adopted only when it is *this* argv's publication, so the journal has to
+    bind:
+
+    * this exact output root, which the journal states and which ``_retained_journal`` checks;
+    * one interrupted publication, and not a choice between several;
+    * the exact execution, component receipts, staging, policy, authoring, classification,
+      predecessor and immutable limit evidence bound before the first packed range was written;
+    * the provider and the exact predecessor head this invocation was given.
+
+    The rest of the generation coordinate -- backends, posting backend, classification and identity
+    manifests -- and the exact bytes of every member each completed range names are re-derived by
+    the publisher's own resume law, before it does one byte of new work and before anything here
+    is written. That law is not copied into this command; a second copy of it would be a second
+    thing to keep true.
+    """
+
+    candidates = _candidate_journals(output_descriptor)
+    if len(candidates) > 1:
+        raise SourceContractError(
+            "PUBLISH_RESUME_JOURNAL",
+            "packed.journal",
+            "this output root holds more than one work journal, and a resume continues exactly one",
+        )
+    found = _retained_journal(output_descriptor, logical_output_root=output_root)
+    if found is None:
+        raise SourceContractError(
+            "PUBLISH_RESUME_RECEIPT",
+            "receipt_file",
+            "a resume continues the typed-incomplete receipt its interruption left behind, or the "
+            "work journal a publication was killed in the middle of",
+        )
+    generation = found[1].get("generation")
+    stated = {
+        "authoring_manifest_sha256": author["manifest_sha256"],
+        "publication_binding_sha256": publication_binding_sha256,
+        "provider_id": author["provider_id"],
+        "predecessor_head_sha256": None if predecessor is None else predecessor["catalog_digest"],
+    }
+    if not isinstance(generation, Mapping) or any(
+        generation.get(member) != value for member, value in stated.items()
+    ):
+        raise SourceContractError(
+            "PUBLISH_RESUME_JOURNAL",
+            "packed.journal",
+            "the interrupted publication in this output root is of another generation than the "
+            "one this invocation was given",
+        )
+
+
+def _require_retained_journal(
+    retained: Mapping[str, Any], output_descriptor: int, *, logical_output_root: Path
+) -> None:
+    """A resume continues the exact interrupted publication its receipt was written against."""
+
+    stated = retained.get("publication")
+    stated_sha256 = stated.get("journal_sha256") if isinstance(stated, Mapping) else None
+    found = _retained_journal(output_descriptor, logical_output_root=logical_output_root)
+    if found is None or not is_digest(stated_sha256) or sha256_bytes(found[0]) != stated_sha256:
+        raise SourceContractError(
+            "PUBLISH_RESUME_RECEIPT",
+            "packed.journal",
+            "a resume continues the exact interrupted publication its receipt was left bound to",
+        )
+
+
+def _require_retained_generation(retained: Mapping[str, Any], common: Mapping[str, Any]) -> None:
+    """Require every generation-defining block to match the interrupted invocation."""
+
+    retained_components = retained.get("components")
+    current_components = common.get("components")
+    if isinstance(retained_components, Mapping) and isinstance(current_components, Mapping):
+        for stage in ("author", "harvest"):
+            member = f"{stage}_receipt_sha256"
+            if retained_components.get(member) != current_components.get(member):
+                raise SourceContractError(
+                    "PUBLISH_RESUME_RECEIPT",
+                    f"{stage}_receipt",
+                    "the retained publication was built from another stage receipt",
+                )
+    for member in (
+        "components",
+        "execution",
+        "staging",
+        "policy",
+        "author",
+        "classification",
+        "predecessor",
+    ):
+        if retained.get(member) != common.get(member):
+            raise SourceContractError(
+                "PUBLISH_RESUME_RECEIPT",
+                member,
+                "a resume must use the exact generation evidence retained at interruption",
+            )
+    retained_limits = retained.get("limits")
+    current_limits = common.get("limits")
+    mutable = {"max_disk_bytes", "max_wall_seconds"}
+    if (
+        not isinstance(retained_limits, Mapping)
+        or not isinstance(current_limits, Mapping)
+        or {key: value for key, value in retained_limits.items() if key not in mutable}
+        != {key: value for key, value in current_limits.items() if key not in mutable}
+    ):
+        raise SourceContractError(
+            "PUBLISH_RESUME_RECEIPT",
+            "limits",
+            "a resume may change only its cumulative disk and wall-time ceilings",
+        )
+
+
+def _generation_binding_sha256(common: Mapping[str, Any]) -> str:
+    """Bind immutable generation evidence into the packed work journal."""
+
+    limits = common.get("limits")
+    if not isinstance(limits, Mapping):
+        raise SourceContractError(
+            "PUBLISH_LIMIT", "limits", "generation limits must be one exact object"
+        )
+    mutable = {"max_disk_bytes", "max_wall_seconds"}
+    return canonical_sha256(
+        {
+            **common,
+            "limits": {key: value for key, value in limits.items() if key not in mutable},
+        }
+    )
+
+
+def _journal_evidence(journal: Mapping[str, Any]) -> dict[str, Any] | None:
+    """What one typed-incomplete journal states about the work it got as far as.
+
+    Nothing here is believed because the journal says it: a record whose shape is not the one the
+    publisher writes makes this report nothing, and the publication's own refusal is raised
+    instead of a receipt describing work that cannot be read.
+    """
+
+    invocations = journal.get("invocations")
+    completed = journal.get("completed_ranges")
+    generation = journal.get("generation")
+    if (
+        not isinstance(invocations, list)
+        or not invocations
+        or not isinstance(completed, list)
+        or not isinstance(generation, Mapping)
+    ):
+        return None
+    records: list[dict[str, int]] = []
+    for record in invocations:
+        if not isinstance(record, Mapping) or set(record) != set(COUNTER_MEMBERS):
+            return None
+        if any(type(record[name]) is not int or record[name] < 0 for name in COUNTER_MEMBERS):
+            return None
+        records.append({name: record[name] for name in COUNTER_MEMBERS})
+    ranges: list[str] = []
+    for descriptor in completed:
+        if not isinstance(descriptor, Mapping) or not is_digest(
+            descriptor.get("range_manifest_sha256")
+        ):
+            return None
+        ranges.append(descriptor["range_manifest_sha256"])
+    backends = generation.get("backends")
+    if not isinstance(backends, list) or not all(isinstance(name, str) for name in backends):
+        return None
+    return {
+        "journal_status": "incomplete",
+        "completed_range_count": len(ranges),
+        "range_manifest_sha256s": ranges,
+        "counter_records": records,
+        "counters": {name: sum(record[name] for record in records) for name in COUNTER_MEMBERS},
+        "backends": list(backends),
+        "predecessor": generation.get("predecessor_head_sha256"),
+    }
+
+
+def _incomplete_receipt(
+    args: argparse.Namespace,
+    *,
+    common: Mapping[str, Any],
+    output_root: Path,
+    output_descriptor: int,
+    reason_code: str,
+    retained: Mapping[str, Any] | None,
+    receipt_installation: ReceiptInstallation,
+) -> dict[str, Any] | None:
+    """Install the typed-incomplete composite receipt one stopped publication leaves behind.
+
+    A publication that stops between two ranges has left every range before it durable and a
+    typed-incomplete work journal beside them.  This binds that journal's exact bytes, this output
+    root, the ranges that are already immutable and the ordered per-invocation counter records the
+    work got as far as -- which is precisely what ``--resume`` validates and replaces.
+
+    A publication that stopped before its first range committed anything has left nothing to
+    continue, and gets no receipt: the refusal that stopped it is raised instead.
+    """
+
+    found = _retained_journal(output_descriptor, logical_output_root=output_root)
+    if found is None:
+        return None
+    raw, journal = found
+    evidence = _journal_evidence(journal)
+    if evidence is None:
+        return None
+    payload = compose_generation_receipt(
+        {
+            "schema_version": GENERATION_RECEIPT_SCHEMA,
+            "status": PUBLISH_INCOMPLETE_STATUS,
+            "reason_code": reason_code,
+            "published_at": datetime.now(UTC).strftime("%Y-%m-%dT%H:%M:%SZ"),
+            "output_root_sha256": root_coordinate(output_root),
+            **common,
+            "publication": {"journal_sha256": sha256_bytes(raw), **evidence},
+            # A generation that was not published has nothing to read back. The block is stated
+            # rather than dropped, because a composite receipt states every one of its blocks.
+            "readback": None,
+        }
+    )
+    install_receipt(
+        args.receipt_file,
+        payload,
+        maximum=MAX_COMPOSITE_RECEIPT_BYTES,
+        label="receipt_file",
+        code_prefix="PUBLISH",
+        refusal=SourceContractError,
+        replaces=retained,
+        installation=receipt_installation,
+    )
+    return payload
+
+
+# ------------------------------------------------------------------------------------------------
+# The handoff: two receipts that have to describe one staging checkpoint
+# ------------------------------------------------------------------------------------------------
+
+
+def _verify_handoff(
+    harvest: Mapping[str, Any],
+    author: Mapping[str, Any],
+    *,
+    harvest_sha256: str,
+    execution: Mapping[str, Any],
+) -> None:
+    if harvest.get("status") != "harvest_complete" or author.get("status") != "complete":
+        raise SourceContractError(
+            "PUBLISH_UPSTREAM_INCOMPLETE",
+            "components",
+            "a generation is published from a complete sweep and a complete authored generation",
+        )
+    if not is_digest(author.get("manifest_sha256")):
+        raise SourceContractError(
+            "PUBLISH_UPSTREAM_INCOMPLETE",
+            "author_receipt.manifest_sha256",
+            "the authored generation published no manifest to classify",
+        )
+    if author.get("harvest_receipt_sha256") != harvest_sha256:
+        raise SourceContractError(
+            "PUBLISH_STAGE_HANDOFF",
+            "author_receipt.harvest_receipt_sha256",
+            "the authoring receipt must bind the exact harvest receipt supplied for publication",
+        )
+    if harvest.get("execution") != execution or author.get("execution") != execution:
+        raise SourceContractError(
+            "PUBLISH_STAGE_HANDOFF",
+            "components.execution",
+            "harvest, author, and publisher must use one exact execution coordinate",
+        )
+    staging = author.get("staging")
+    if not isinstance(staging, Mapping):
+        raise SourceContractError(
+            "PUBLISH_STAGE_HANDOFF",
+            "author_receipt.staging",
+            "an authoring receipt names the staging coordinate it authored",
+        )
+    for stated, retained, member in (
+        (harvest.get("checkpoint_sha256"), staging.get("checkpoint_sha256"), "checkpoint_sha256"),
+        (harvest.get("config_sha256"), staging.get("config_sha256"), "config_sha256"),
+        (harvest.get("endpoint"), staging.get("endpoint"), "endpoint"),
+        (
+            harvest.get("harvester_coordinate"),
+            staging.get("harvester_coordinate"),
+            "harvester_coordinate",
+        ),
+    ):
+        if stated is None or stated != retained:
+            raise SourceContractError(
+                "PUBLISH_STAGE_HANDOFF",
+                f"author_receipt.staging.{member}",
+                "the two stage receipts describe two different sweeps",
+            )
+    measures = harvest.get("measures")
+    if not isinstance(measures, Mapping) or set(measures) != {
+        "requests",
+        "responses",
+        "pages",
+        "provider_records",
+    }:
+        raise SourceContractError(
+            "PUBLISH_STAGE_HANDOFF",
+            "harvest_receipt.measures",
+            "a sweep states requests, responses, pages and provider records as four numbers",
+        )
+
+
+def _author_manifest(root: Path, expected_sha256: str) -> tuple[bytes, dict[str, Any]]:
+    raw, manifest = load_bounded_json(
+        root / MANIFEST_FILENAME,
+        label="author_root.manifest",
+        maximum=MAX_AUTHORING_MANIFEST_BYTES,
+        max_depth=MAX_PREDECESSOR_HEAD_DEPTH,
+        max_members=MAX_STAGE_RECEIPT_MEMBERS,
+        max_items=MAX_PREDECESSOR_RANGE_DESCRIPTORS,
+        expected_sha256=expected_sha256,
+    )
+    if manifest.get("schema_version") != AUTHORING_MANIFEST_SCHEMA:
+        raise SourceContractError(
+            "PUBLISH_STAGE_HANDOFF",
+            "author_root.manifest",
+            "the authored root does not hold an authoring manifest",
+        )
+    return raw, manifest
+
+
+def _author_journal(root: Path, expected_sha256: str) -> tuple[bytes, dict[str, Any]]:
+    """Read the work journal the authoring stage retained beside its shards, by exact digest.
+
+    The authoring stage publishes ``journal.json`` on every invocation and never removes it, so
+    the digest an author receipt states is a claim about bytes that are still on disk. Reading it
+    here is what turns that claim back into evidence.
+    """
+
+    return load_bounded_json(
+        root / JOURNAL_FILENAME,
+        label="author_root.journal",
+        maximum=MAX_AUTHORING_JOURNAL_BYTES,
+        max_depth=MAX_PREDECESSOR_HEAD_DEPTH,
+        max_members=MAX_STAGE_RECEIPT_MEMBERS,
+        max_items=MAX_PREDECESSOR_RANGE_DESCRIPTORS,
+        expected_sha256=expected_sha256,
+    )
+
+
+def _verify_author_receipt(
+    author: Mapping[str, Any],
+    *,
+    manifest: Mapping[str, Any],
+    manifest_bytes: int,
+    harvest: Mapping[str, Any],
+    harvest_sha256: str,
+    author_root: Path,
+    execution: Mapping[str, Any],
+) -> dict[str, Any]:
+    """Re-derive an author receipt from its exact manifest and registered policy.
+
+    The receipt is carried into the authoritative composite, so none of its duplicated summaries
+    may be accepted merely because the receipt bytes have a caller-supplied digest. This check is
+    deliberately before the publication lock: a false receipt cannot create either output root.
+
+    What it returns is the generation evidence this command established for itself, which the
+    composite states beside the carried receipt.
+    """
+
+    if set(author) != _AUTHOR_RECEIPT_MEMBERS:
+        raise SourceContractError(
+            "PUBLISH_STAGE_HANDOFF",
+            "author_receipt",
+            "the authoring receipt must carry exactly its closed contract members",
+        )
+    if set(manifest) != _AUTHOR_MANIFEST_MEMBERS:
+        raise SourceContractError(
+            "PUBLISH_STAGE_HANDOFF",
+            "author_root.manifest",
+            "the authoring manifest must carry exactly its closed contract members",
+        )
+
+    staging = manifest["staging"]
+    coverage = manifest["coverage"]
+    counts = manifest["counts"]
+    layer_text_digests = manifest["layer_text_digests"]
+    shards = manifest["shards"]
+    limits = author["limits"]
+    if not isinstance(staging, dict) or set(staging) != _AUTHOR_STAGING_MEMBERS:
+        raise SourceContractError(
+            "PUBLISH_STAGE_HANDOFF",
+            "author_root.manifest.staging",
+            "the authoring manifest must carry the complete staging coordinate",
+        )
+    if (
+        not isinstance(counts, dict)
+        or set(counts) != _AUTHOR_COUNT_MEMBERS
+        or any(type(value) is not int or value < 0 for value in counts.values())
+    ):
+        raise SourceContractError(
+            "PUBLISH_STAGE_HANDOFF",
+            "author_root.manifest.counts",
+            "the authoring manifest must carry its exact non-negative count contract",
+        )
+    if not coverage_is_valid(coverage):
+        raise SourceContractError(
+            "PUBLISH_STAGE_HANDOFF",
+            "author_root.manifest.coverage",
+            "the authoring manifest must state what it covers and what it drew from",
+        )
+    if (
+        not isinstance(layer_text_digests, dict)
+        or set(layer_text_digests) != set(EMBEDDING_LAYERS)
+        or any(value is not None and not is_digest(value) for value in layer_text_digests.values())
+    ):
+        raise SourceContractError(
+            "PUBLISH_STAGE_HANDOFF",
+            "author_root.manifest.layer_text_digests",
+            "the authoring manifest must bind every retrieval layer digest",
+        )
+    if not isinstance(shards, list) or len(shards) > MAX_RANGE_DESCRIPTORS:
+        raise SourceContractError(
+            "PUBLISH_STAGE_HANDOFF",
+            "author_root.manifest.shards",
+            "the authoring manifest shard population exceeds its fixed contract",
+        )
+    if (
+        not isinstance(limits, dict)
+        or set(limits) != _AUTHOR_LIMIT_MEMBERS
+        or any(type(value) is not int or value < 1 for value in limits.values())
+        or limits["max_shard_entries"] > MAX_AUTHORING_SHARD_ENTRIES
+        or limits["max_shard_bytes"] > MAX_AUTHORING_SHARD_BYTES
+    ):
+        raise SourceContractError(
+            "PUBLISH_STAGE_HANDOFF",
+            "author_receipt.limits",
+            "the authoring receipt must carry its exact bounded limit contract",
+        )
+
+    digest_staging = _AUTHOR_STAGING_MEMBERS - {
+        "endpoint",
+        "harvester_coordinate",
+        "pass_number",
+        "unique_records",
+        "raw_response_index_count",
+        "normalized_page_index_count",
+        "record_index_count",
+    }
+    count_staging = {
+        "unique_records",
+        "raw_response_index_count",
+        "normalized_page_index_count",
+        "record_index_count",
+    }
+    if (
+        any(not is_digest(staging[name]) for name in digest_staging)
+        or not isinstance(staging["endpoint"], str)
+        or not staging["endpoint"]
+        or not isinstance(staging["harvester_coordinate"], str)
+        or not staging["harvester_coordinate"]
+        or type(staging["pass_number"]) is not int
+        or staging["pass_number"] < 1
+        or any(type(staging[name]) is not int or staging[name] < 0 for name in count_staging)
+    ):
+        raise SourceContractError(
+            "PUBLISH_STAGE_HANDOFF",
+            "author_root.manifest.staging",
+            "the authoring manifest staging coordinate has invalid members",
+        )
+
+    manifest_body = {name: value for name, value in manifest.items() if name != "root_sha256"}
+    if manifest["root_sha256"] != canonical_sha256(manifest_body):
+        raise SourceContractError(
+            "PUBLISH_STAGE_HANDOFF",
+            "author_root.manifest.root_sha256",
+            "the authoring manifest does not reproduce its own root coordinate",
+        )
+    try:
+        policy = resolve_authoring_policy(manifest["policy_id"])
+    except SourceContractError as error:
+        raise SourceContractError(
+            "PUBLISH_STAGE_HANDOFF",
+            "author_root.manifest.policy_id",
+            "the authoring manifest does not name a registered policy",
+        ) from error
+
+    expected = {
+        "schema_version": AUTHORING_RECEIPT_SCHEMA,
+        "status": "complete",
+        "reason_code": None,
+        "policy_id": manifest["policy_id"],
+        "policy_sha256": manifest["policy_sha256"],
+        "provider_id": policy.provider_id,
+        "harvester_coordinate": policy.harvester_coordinate,
+        "staging": staging,
+        "coverage": coverage,
+        "counts": counts,
+        "layer_text_digests": layer_text_digests,
+        "shard_count": len(shards),
+        "shards": shards,
+        "manifest_sha256": author["manifest_sha256"],
+        "harvest_receipt_sha256": harvest_sha256,
+        "output_root_sha256": root_coordinate(author_root),
+        "execution": execution,
+    }
+    # The two populations a coverage statement names are not free either. It draws from the
+    # corpus this generation's own staging coordinate found, and it accounts for every record
+    # this generation's own shards hold. `coverage_is_valid` above closed the statement against
+    # itself; this closes it against the generation it describes.
+    if (
+        coverage["corpus_records"] != staging["unique_records"]
+        or coverage["selected_records"] != counts["records"]
+    ):
+        raise SourceContractError(
+            "PUBLISH_STAGE_HANDOFF",
+            "author_root.manifest.coverage",
+            "the stated coverage does not draw from this generation's corpus or does not "
+            "account for every record it authored",
+        )
+    if manifest["policy_sha256"] != policy.digest:
+        raise SourceContractError(
+            "PUBLISH_STAGE_HANDOFF",
+            "author_root.manifest.policy_sha256",
+            "the authoring manifest policy fingerprint differs from its registered policy",
+        )
+    if staging["harvester_coordinate"] != policy.harvester_coordinate:
+        raise SourceContractError(
+            "PUBLISH_STAGE_HANDOFF",
+            "author_root.manifest.staging.harvester_coordinate",
+            "the staging coordinate differs from the registered authoring policy",
+        )
+    if (
+        harvest.get("provider") != policy.provider_id
+        or harvest.get("harvester_coordinate") != policy.harvester_coordinate
+    ):
+        raise SourceContractError(
+            "PUBLISH_STAGE_HANDOFF",
+            "harvest_receipt",
+            "the harvest receipt differs from the registered authoring policy",
+        )
+    for member, value in expected.items():
+        if author[member] != value:
+            raise SourceContractError(
+                "PUBLISH_STAGE_HANDOFF",
+                f"author_receipt.{member}",
+                "the authoring receipt differs from its exact manifest or resolved input",
+            )
+    return _verify_author_generation_evidence(
+        author, manifest=manifest, manifest_bytes=manifest_bytes, author_root=author_root
+    )
+
+
+def _verify_author_generation_evidence(
+    author: Mapping[str, Any],
+    *,
+    manifest: Mapping[str, Any],
+    manifest_bytes: int,
+    author_root: Path,
+) -> dict[str, Any]:
+    """Bind the author receipt's journal, bounds and byte total to the generation it authored.
+
+    Everything above this point re-derives the receipt's *summaries* from the manifest. Three
+    members are left over, and each one used to be believed on the strength of its own shape:
+    the journal fingerprint, the bounds the invocation ran under, and the bytes it wrote.
+
+    Each is reconciled here against evidence the author root still holds. The journal digest is
+    read back from the retained ``journal.json`` and the journal is required to describe exactly
+    this manifest's generation. The bounds are required to admit the shards that were actually
+    authored, which shows only that each was stated at least that wide. The byte total is an
+    invocation-scoped measure -- a resumed authoring writes only what it added -- so it is
+    reconciled against the interval the retained outputs allow: never less than the journal and
+    manifest this invocation had to publish, and never more than the bytes that manifest and
+    journal account for.
+
+    None of that reaches an exact value for six of the eight, so the returned evidence carries
+    ``AUTHOR_CLAIM_RECONCILIATION`` rather than a list of the unreachable ones: naming only what
+    could not be reached would leave a reader to conclude that everything unnamed was.
+    """
+
+    if (
+        not is_digest(author["journal_sha256"])
+        or type(author["output_bytes"]) is not int
+        or author["output_bytes"] < 0
+    ):
+        raise SourceContractError(
+            "PUBLISH_STAGE_HANDOFF",
+            "author_receipt",
+            "the authoring receipt carries invalid generation evidence",
+        )
+    shards = manifest["shards"]
+    for descriptor in shards:
+        if not shard_descriptor_is_valid(descriptor):
+            raise SourceContractError(
+                "PUBLISH_STAGE_HANDOFF",
+                "author_root.manifest.shards[]",
+                "an authored shard descriptor must carry exactly its closed contract members",
+            )
+
+    journal_raw, journal = _author_journal(author_root, author["journal_sha256"])
+    if (
+        set(journal) != _AUTHOR_JOURNAL_MEMBERS
+        or journal["schema_version"] != AUTHORING_JOURNAL_SCHEMA
+    ):
+        raise SourceContractError(
+            "PUBLISH_STAGE_HANDOFF",
+            "author_root.journal",
+            "the retained authoring journal must carry exactly its closed contract members",
+        )
+    if (
+        journal["reason_code"] is not None
+        or journal["policy_sha256"] != manifest["policy_sha256"]
+        or journal["staging_checkpoint_sha256"] != manifest["staging"]["checkpoint_sha256"]
+        or journal["coverage"] != manifest["coverage"]
+        or journal["shards"] != shards
+        or journal["counts"] != manifest["counts"]
+        or journal["layer_text_digests"] != manifest["layer_text_digests"]
+        or journal["last_provider_record_id"]
+        != (shards[-1]["last_provider_record_id"] if shards else None)
+    ):
+        raise SourceContractError(
+            "PUBLISH_STAGE_HANDOFF",
+            "author_root.journal",
+            "the retained authoring journal describes another authored generation",
+        )
+
+    limits = author["limits"]
+    if (
+        limits["max_records"] < manifest["counts"]["records"]
+        or any(limits["max_shard_entries"] < descriptor["item_count"] for descriptor in shards)
+        or any(limits["max_shard_bytes"] < descriptor["bytes"] for descriptor in shards)
+    ):
+        raise SourceContractError(
+            "PUBLISH_STAGE_HANDOFF",
+            "author_receipt.limits",
+            "the authoring receipt states bounds the generation it authored exceeds",
+        )
+
+    # One shard is one immutable digest-named member, so a repeated digest is one file.
+    shard_bytes = sum({descriptor["sha256"]: descriptor["bytes"] for descriptor in shards}.values())
+    published_bytes = len(journal_raw) + manifest_bytes
+    accounted_root_bytes = shard_bytes + published_bytes
+    if not published_bytes <= author["output_bytes"] <= accounted_root_bytes:
+        raise SourceContractError(
+            "PUBLISH_STAGE_HANDOFF",
+            "author_receipt.output_bytes",
+            "the authoring receipt states a byte total the authored root cannot account for",
+        )
+    return {
+        "journal_sha256": author["journal_sha256"],
+        "accounted_root_bytes": accounted_root_bytes,
+        "claim_reconciliation": dict(AUTHOR_CLAIM_RECONCILIATION),
+    }
+
+
+# ------------------------------------------------------------------------------------------------
+# Predecessor coordinates
+# ------------------------------------------------------------------------------------------------
+
+
+def _predecessor_coordinates(args: argparse.Namespace) -> dict[str, Any] | None:
+    stated = [name for name in _PREDECESSOR_ARGUMENTS if getattr(args, name) is not None]
+    if args.predecessor_mode == "none":
+        if stated:
+            raise SourceContractError(
+                "PUBLISH_PREDECESSOR_COORDINATE",
+                stated[0],
+                "a generation with no predecessor takes no predecessor argument at all",
+            )
+        return None
+    if len(stated) != len(_PREDECESSOR_ARGUMENTS):
+        missing = [name for name in _PREDECESSOR_ARGUMENTS if getattr(args, name) is None]
+        raise SourceContractError(
+            "PUBLISH_PREDECESSOR_COORDINATE",
+            missing[0],
+            "an exact predecessor is named by all six of its roots and digests",
+        )
+    for name in (
+        "predecessor_identity_digest",
+        "predecessor_history_digest",
+        "predecessor_catalog_digest",
+    ):
+        if not is_digest(getattr(args, name)):
+            raise SourceContractError(
+                "PUBLISH_PREDECESSOR_COORDINATE", name, "must be a lowercase SHA-256"
+            )
+    return {
+        "identity_root": Path(args.predecessor_identity_root),
+        "identity_digest": args.predecessor_identity_digest,
+        "history_root": Path(args.predecessor_history_root),
+        "history_digest": args.predecessor_history_digest,
+        "catalog_root": Path(args.predecessor_catalog_root),
+        "catalog_digest": args.predecessor_catalog_digest,
+    }
+
+
+def _read_predecessor_heads(
+    predecessor: Mapping[str, Any] | None, *, identity_descriptor: int | None = None
+) -> dict[str, Any] | None:
+    """Read all three predecessor heads under the fixed caps, and cross-check what they claim."""
+
+    if predecessor is None:
+        return None
+    # The identity generation is opened through the exact manifest name its writer owns.
+    if identity_descriptor is None:
+        _raw, identity = load_bounded_json(
+            predecessor["identity_root"] / IDENTITY_MANIFEST_FILENAME,
+            label="predecessor_identity_root.manifest",
+            maximum=MAX_PREDECESSOR_HEAD_BYTES,
+            max_depth=MAX_PREDECESSOR_HEAD_DEPTH,
+            max_members=MAX_STAGE_RECEIPT_MEMBERS,
+            max_items=MAX_PREDECESSOR_RANGE_DESCRIPTORS,
+            expected_sha256=predecessor["identity_digest"],
+        )
+    else:
+        _raw, identity = load_bounded_json_at(
+            identity_descriptor,
+            IDENTITY_MANIFEST_FILENAME,
+            label="predecessor_identity_root.manifest",
+            maximum=MAX_PREDECESSOR_HEAD_BYTES,
+            max_depth=MAX_PREDECESSOR_HEAD_DEPTH,
+            max_members=MAX_STAGE_RECEIPT_MEMBERS,
+            max_items=MAX_PREDECESSOR_RANGE_DESCRIPTORS,
+        )
+        if sha256_bytes(_raw) != predecessor["identity_digest"]:
+            raise SourceContractError(
+                "GENERATION_INPUT_DIGEST",
+                "predecessor_identity_root.manifest",
+                "the retained identity manifest differs from its required digest",
+            )
+    if identity.get("schema_version") != IDENTITY_MANIFEST_SCHEMA:
+        raise SourceContractError(
+            "PUBLISH_PREDECESSOR_COORDINATE",
+            "predecessor_identity_root.manifest",
+            "the predecessor identity root does not hold an identity generation",
+        )
+    identity_records = identity.get("record_count")
+    if type(identity_records) is not int or identity_records < 0:
+        raise SourceContractError(
+            "PUBLISH_PREDECESSOR_COORDINATE",
+            "predecessor_identity_root.manifest",
+            "an identity generation states how many records it carries",
+        )
+    _raw, history = load_bounded_json(
+        predecessor["history_root"] / DELTA_MANIFEST_FILENAME,
+        label="predecessor_history_root.manifest",
+        maximum=min(MAX_PREDECESSOR_HEAD_BYTES, MAX_DELTA_MANIFEST_BYTES),
+        max_depth=MAX_PREDECESSOR_HEAD_DEPTH,
+        max_members=MAX_STAGE_RECEIPT_MEMBERS,
+        max_items=MAX_PREDECESSOR_RANGE_DESCRIPTORS,
+        expected_sha256=predecessor["history_digest"],
+    )
+    if history.get("outputs", {}).get("identity_manifest_sha256") != predecessor["identity_digest"]:
+        raise SourceContractError(
+            "PUBLISH_PREDECESSOR_COORDINATE",
+            "predecessor_history_root",
+            "the predecessor's classification does not name the identity generation given here",
+        )
+    _raw, head = load_bounded_json(
+        predecessor["catalog_root"] / "packed-head.json",
+        label="predecessor_catalog_root.head",
+        maximum=MAX_PREDECESSOR_HEAD_BYTES,
+        max_depth=MAX_PREDECESSOR_HEAD_DEPTH,
+        max_members=MAX_STAGE_RECEIPT_MEMBERS,
+        max_items=MAX_PREDECESSOR_RANGE_DESCRIPTORS,
+        expected_sha256=predecessor["catalog_digest"],
+    )
+    if head.get("generation_sha256") != predecessor["history_digest"]:
+        raise SourceContractError(
+            "PUBLISH_PREDECESSOR_COORDINATE",
+            "predecessor_catalog_root.head.generation_sha256",
+            "the predecessor packed catalog was not published from the named history generation",
+        )
+    ranges = head.get("ranges", ())
+    if not isinstance(ranges, list) or len(ranges) > MAX_PREDECESSOR_RANGE_DESCRIPTORS:
+        raise SourceContractError(
+            "PUBLISH_PREDECESSOR_COORDINATE",
+            "predecessor_catalog_root.head.ranges",
+            f"a predecessor head states at most {MAX_PREDECESSOR_RANGE_DESCRIPTORS} ranges",
+        )
+    return {
+        "identity_manifest_sha256": predecessor["identity_digest"],
+        "identity_root_sha256": root_coordinate(predecessor["identity_root"]),
+        "history_manifest_sha256": predecessor["history_digest"],
+        "history_root_sha256": root_coordinate(predecessor["history_root"]),
+        "catalog_head_sha256": predecessor["catalog_digest"],
+        "catalog_root_sha256": root_coordinate(predecessor["catalog_root"]),
+        "catalog_range_count": len(ranges),
+        # The predecessor record count comes from the identity manifest's required member.
+        "identity_record_count": identity_records,
+    }
+
+
+# ------------------------------------------------------------------------------------------------
+# Classification and publication
+# ------------------------------------------------------------------------------------------------
+
+
+def _classify(
+    args: argparse.Namespace,
+    *,
+    author: Mapping[str, Any],
+    harvest: Mapping[str, Any],
+    delta_root: Path,
+    output_descriptor: int,
+    coordinate_root: Path | None = None,
+    predecessor: Mapping[str, Any] | None,
+    resumed: bool,
+    predecessor_identity_descriptor: int | None = None,
+) -> dict[str, Any]:
+    with retained_child_directory(
+        output_descriptor,
+        DELTA_DIRNAME,
+        create=not resumed,
+        label="delta.output",
+        code_prefix="PUBLISH",
+        refusal=SourceContractError,
+    ) as delta_descriptor:
+        if resumed:
+            try:
+                raw, existing = load_bounded_json_at(
+                    delta_descriptor,
+                    DELTA_MANIFEST_FILENAME,
+                    label="delta.manifest",
+                    maximum=MAX_DELTA_MANIFEST_BYTES,
+                    max_depth=MAX_PREDECESSOR_HEAD_DEPTH,
+                    max_members=MAX_STAGE_RECEIPT_MEMBERS,
+                    max_items=MAX_PREDECESSOR_RANGE_DESCRIPTORS,
+                )
+            except SourceContractError as error:
+                if error.code == "GENERATION_INPUT_PATH":
+                    raise SourceContractError(
+                        "PUBLISH_RESUME_RECEIPT",
+                        "classification",
+                        "the interrupted publication must retain its exact classification manifest",
+                    ) from error
+                raise
+            return {
+                "manifest_sha256": sha256_bytes(raw),
+                "identity_manifest_sha256": existing["outputs"]["identity_manifest_sha256"],
+                "counts": {name: existing["counts"][name] for name in DELTA_CLASSIFICATIONS},
+                "reuse": existing["reuse"],
+                "measures": existing["measures"],
+                "shard_count": existing["outputs"]["shard_count"],
+                "classification_digests": existing["outputs"]["classification_digests"],
+                "identity_root_sha256": root_coordinate(
+                    (coordinate_root or delta_root) / DELTA_IDENTITY_DIRNAME
+                ),
+                "history_root_sha256": root_coordinate(coordinate_root or delta_root),
+            }
+        measures = harvest["measures"]
+        result = run_streaming_delta(
+            authoring_root=Path(args.author_root),
+            expected_authoring_manifest_sha256=author["manifest_sha256"],
+            output_root=delta_root,
+            output_descriptor=delta_descriptor,
+            measures=SweepMeasures(
+                requests=measures["requests"],
+                responses=measures["responses"],
+                pages=measures["pages"],
+                provider_records=measures["provider_records"],
+            ),
+            observed_at=_observed_at(harvest),
+            limits=StreamingDeltaLimits(
+                max_records=args.max_ranges * args.max_range_entries,
+                max_disk_bytes=args.max_disk_bytes,
+                max_wall_seconds=args.max_wall_seconds,
+            ),
+            predecessor_root=None if predecessor is None else predecessor["identity_root"],
+            expected_predecessor_manifest_sha256=(
+                None if predecessor is None else predecessor["identity_digest"]
+            ),
+            predecessor_root_descriptor=predecessor_identity_descriptor,
+        )
+    receipt = result.receipt
+    return {
+        "manifest_sha256": result.manifest_sha256,
+        "identity_manifest_sha256": result.identity_manifest_sha256,
+        "counts": result.counts,
+        "reuse": receipt["reuse"],
+        "measures": receipt["measures"],
+        "shard_count": receipt["outputs"]["shard_count"],
+        "classification_digests": receipt["outputs"]["classification_digests"],
+        "identity_root_sha256": root_coordinate(
+            (coordinate_root or delta_root) / DELTA_IDENTITY_DIRNAME
+        ),
+        "history_root_sha256": root_coordinate(coordinate_root or delta_root),
+    }
+
+
+def _observed_at(harvest: Mapping[str, Any]) -> str:
+    observed = harvest.get("observed_at")
+    if isinstance(observed, str) and observed:
+        return observed
+    return datetime.now(UTC).strftime("%Y-%m-%dT%H:%M:%SZ")
+
+
+def _backends(args: argparse.Namespace) -> list[Any]:
+    backends: list[Any] = [LexicalHashingBackend()]
+    if args.neural_backend is None:
+        if args.neural_pin is not None or args.model_root is not None:
+            raise SourceContractError(
+                "PUBLISH_BACKEND_COORDINATE",
+                "neural_backend",
+                "a pinned model root belongs to the neural backend that reads it",
+            )
+        return backends
+    if args.model_root is None or not is_digest(args.neural_pin):
+        raise SourceContractError(
+            "PUBLISH_BACKEND_COORDINATE",
+            "neural_backend",
+            "a neural representation names its governed model root and its exact pin",
+        )
+    from mostlyright.data_harness.sources.catalog.neural import resolve_local_neural_backend
+
+    backends.append(resolve_local_neural_backend(args.model_root))
+    return backends
+
+
+def _publication_evidence(
+    receipt: Mapping[str, Any], publication: Any, backends: Sequence[Any]
+) -> dict[str, Any]:
+    del backends
+    outputs = receipt["outputs"]
+    return {
+        # The publication receipt is carried whole, not summarised. A packed search authenticates
+        # its store against exactly this document, so a reader that had to rebuild it from the
+        # block below would be authenticating against a copy somebody made.
+        "packed_receipt": dict(receipt),
+        "coordinate_sha256": receipt["coordinate_sha256"],
+        "expected_head_sha256": publication.head_sha256,
+        "journal_sha256": publication.journal_sha256,
+        "backends": list(receipt["backends"]),
+        "posting_backend_coordinate": receipt["posting_backend_coordinate"],
+        "adapter_mode": receipt["adapter_mode"],
+        "predecessor": receipt["inputs"]["predecessor_head_sha256"],
+        "counts": dict(publication.counts),
+        "counters": dict(publication.counters),
+        "counter_records": [dict(record) for record in receipt["invocations"]],
+        "range_manifest_sha256s": [
+            descriptor["manifest_sha256"] for descriptor in outputs["ranges"]
+        ],
+        "ranges_chain_sha256": outputs["ranges_chain_sha256"],
+        "vector_payload_sha256s": list(outputs["vector_member_sha256s"]),
+        "posting_member_sha256s": list(outputs["posting_member_sha256s"]),
+        "bound_member_sha256s": list(outputs["bound_member_sha256s"]),
+        "residency": receipt["residency"],
+    }
+
+
+# ------------------------------------------------------------------------------------------------
+# Bounds
+# ------------------------------------------------------------------------------------------------
+
+
+def _validate_limits(args: argparse.Namespace) -> None:
+    for name, exact in _FIXED.items():
+        value = getattr(args, name)
+        if type(value) is not int or value != exact:
+            raise SourceContractError(
+                "PUBLISH_LIMIT",
+                name,
+                f"this bound is fixed at {exact} and is not caller-widenable",
+            )
+    for name in (
+        "max_batch_invocations",
+        "max_encoded_layer_items",
+        "max_backend_scalar_invocations",
+        "max_encoded_input_bytes",
+        "max_disk_bytes",
+        "max_wall_seconds",
+    ):
+        value = getattr(args, name)
+        if type(value) is not int or value < 1:
+            raise SourceContractError(
+                "PUBLISH_LIMIT", name, "must be a positive canonical decimal integer"
+            )
+
+
+def _verify_work_budget(args: argparse.Namespace, receipt: Mapping[str, Any]) -> None:
+    """The three work counters and the encoded input bytes, checked as totals and as sums.
+
+    The publisher owns these numbers -- it produces them from seam-minted records rather than
+    accepting them -- so the caller's budget is checked against what was actually done, and against
+    the ordered per-invocation records the composite receipt is about to state.
+    """
+
+    counters = receipt["counters"]
+    for counter, cap in (
+        ("batch_invocations", args.max_batch_invocations),
+        ("encoded_layer_items", args.max_encoded_layer_items),
+        ("backend_scalar_invocations", args.max_backend_scalar_invocations),
+        ("encoded_utf8_bytes", args.max_encoded_input_bytes),
+    ):
+        if counters[counter] > cap:
+            raise SourceContractError(
+                "PUBLISH_WORK_LIMIT",
+                f"counters.{counter}",
+                "the publication did more of this work than the caller allowed it to",
+            )
+        stated = sum(record[counter] for record in receipt["invocations"])
+        if stated != counters[counter]:
+            raise SourceContractError(
+                "PUBLISH_WORK_LIMIT",
+                f"counters.{counter}",
+                "the ordered per-invocation records do not sum to the stated total",
+            )
+
+
+def _limits_evidence(args: argparse.Namespace) -> dict[str, int]:
+    return {
+        **{name: getattr(args, name) for name in _FIXED},
+        "max_batch_invocations": args.max_batch_invocations,
+        "max_encoded_layer_items": args.max_encoded_layer_items,
+        "max_backend_scalar_invocations": args.max_backend_scalar_invocations,
+        "max_encoded_input_bytes": args.max_encoded_input_bytes,
+        "max_disk_bytes": args.max_disk_bytes,
+        "max_wall_seconds": args.max_wall_seconds,
+    }
+
+
+def _exit_code(payload: Mapping[str, Any]) -> int:
+    return 0 if payload.get("status") == PUBLISH_COMPLETE_STATUS else 1
+
+
+SPEC = CommandSpec(
+    name="catalog-publish",
+    help="classify one authored generation, publish it, and write its one composite receipt",
+    add_arguments=add_arguments,
+    run=run,
+    exit_code=_exit_code,
+)