mostlyright-data 0.10.6__tar.gz → 0.10.7__tar.gz

{mostlyright_data-0.10.6 → mostlyright_data-0.10.7}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: mostlyright-data
-Version: 0.10.6
+Version: 0.10.7
 Summary: Mostly Right CLI for reproducible, reviewed Parquet datasets
 Project-URL: Homepage, https://mostlyright.md/
 Project-URL: Documentation, https://mostlyright.md/docs/guides/cli/

{mostlyright_data-0.10.6 → mostlyright_data-0.10.7}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "mostlyright-data"
-version = "0.10.6"
+version = "0.10.7"
 description = "Mostly Right CLI for reproducible, reviewed Parquet datasets"
 readme = "README.md"
 requires-python = ">=3.13,<3.14"

{mostlyright_data-0.10.6 → mostlyright_data-0.10.7}/src/mostlyright/data_harness/hosted_run_worker.py

@@ -18,8 +18,8 @@ takes it:
   :func:`_raw_snapshot_tar`.
 * **The ``cache`` field lives on the v4 ``receipt`` artifact, never on a sealed acquisition
   receipt.** See :func:`_receipt_document`.
-* **The restored predecessor tree is the authority; the job's ``predecessor`` block is only a
-  coordinate.** See :func:`restore_predecessor_tree`.
+* **The authenticated predecessor receipt is the authority; the job's ``predecessor`` block is
+  only a coordinate.** See :func:`restore_predecessor_record`.
 
 TWO SEAMS THIS REPOSITORY DOES NOT OWN, both named here so a reader does not go looking:
 
@@ -80,12 +80,10 @@ from mostlyright.data_harness.hosted_worker import (
     ArtifactPayload,
     HostedWorkerError,
     _candidate_snapshot,
-    _decode_candidate_envelope,
     _new_transfer_client,
     _quiet_signed_transfer,
     _read_fd_once,
     _released_column_profile,
-    _restore_candidate_members,
     _run_bounded_in_submit_order,
     _seal_producer_artifact,
     _strict_json,
@@ -106,7 +104,7 @@ from mostlyright.data_harness.inprocess_acquisition import (
     inprocess_reader_policy_digest,
     v4_parse_policy_digest,
 )
-from mostlyright.data_harness.recipe import RecipeError, RecipeExecution, parse_recipe_execution
+from mostlyright.data_harness.recipe import RecipeError, parse_recipe_execution
 from mostlyright.data_harness.run_execution_v4 import (
     FAILED_STAGES,
     RunCallbacks,
@@ -150,7 +148,7 @@ from mostlyright.data_harness.v4_recipe import (
     source_ceilings,
     source_egress_origins,
 )
-from mostlyright.data_harness.v4_required_controls import run_required_controls
+from mostlyright.data_harness.v4_required_controls import profile_shape, run_required_controls
 from mostlyright.data_harness.v4_snapshot_artifact import SnapshotArtifactAdapter
 from mostlyright.data_harness.v4_transform import (
     SEALED_MEMBER_DIRECTORY,
@@ -675,8 +673,7 @@ def permitted_artifact_hosts(
     required them to agree refused every refresh a hosted deployment dispatched.
 
     This is defence in depth and it is not the authentication: the predecessor's bytes are still
-    authenticated end to end by ``candidate_digest``, checked by ``_decode_candidate_envelope``
-    and again by ``pipeline.verify_candidate`` on the restored tree.
+    authenticated end to end by ``candidate_digest``, checked before the receipt is read.
     """
 
     session = job.artifact_session
@@ -708,7 +705,7 @@ def _download_signed_bytes(
 
     A v4 signed session carries no expected size and no expected digest: the digest that
     authenticates these bytes is the block's ``candidate_digest``, checked by
-    ``_decode_candidate_envelope`` and again by ``pipeline.verify_candidate`` on the restored tree.
+    :func:`restore_predecessor_record` before the receipt is read.
 
     BOTH ADDRESS CHECKS RUN BEFORE THE STREAM OPENS, so a refused session costs no bytes.
     """
@@ -745,130 +742,165 @@ def _download_signed_bytes(
     return b"".join(chunks)
 
 
-def restore_predecessor_tree(
-    job: RunExecution, *, transfer: Any, root: Path, studio_origin: str = ""
-) -> Path:
-    """Download, decode, restore and replay-verify the predecessor's sealed candidate tree.
+@dataclass(frozen=True)
+class PredecessorRecord:
+    """What a refresh continues from: the predecessor's sealed receipt, read once and authenticated.
+
+    THE RECEIPT IS THE AUTHORITY AND THE BLOCK IS ONLY THE COORDINATE. Studio stamps the receipt's
+    own digest onto the run as ``candidate_digest`` (``docs/V4-WORKER-PROTOCOL.md``, *Callbacks*),
+    and the predecessor block carries that digest beside a signed session for those exact bytes.
+    So the bytes are authenticated end to end by the digest, and every fact below is read out of
+    them rather than out of the block: the table version the successor numbers itself after, the
+    sealed column shape the drift control compares against, and the committed state of every
+    source, which for a registered document is the digest of the bytes that were read.
+
+    A v4 run uploads five artifacts and never the sealed tree itself, so there is no tree to
+    restore and replay-verify here; ``candidate_digest`` on the record is the tree's digest as
+    the predecessor stated it, carried for the successor's own sealed execution.
+    """
 
-    This mirrors ``hosted_worker._restore_predecessor_input`` step for step -- redeem the session,
-    download bounded by ``MAX_CANDIDATE_ENVELOPE_BYTES``, ``_decode_candidate_envelope``,
-    ``_restore_candidate_members``, ``pipeline.verify_candidate``, compare the digest -- with the
-    v3 ``predecessor_artifact_handle`` replaced by the v4 block's
-    ``predecessor.artifact_download_session``.
+    run_id: UUID
+    workspace_id: UUID
+    recipe_digest: str
+    candidate_digest: str
+    table_id: str
+    table_version_id: str
+    table_version_number: int
+    columns: tuple[tuple[str, str], ...]
+    row_count: int | None
+    source_states: Mapping[str, str]
 
-    THE RESTORED TREE IS THE AUTHORITY AND THE BLOCK IS ONLY THE COORDINATE. The block says where
-    to look; what is found there says what it is. A block whose ``candidate_digest`` disagrees with
-    the verified tree is a refusal and never a correction, and ``table_id`` and
-    ``table_version_number`` are read from the tree's own sealed ``recipe-execution.json`` rather
-    than from the block -- which is what stops a spoofed block rebinding a run to a version it did
-    not come from (T-401-24).
 
-    Six failure points, one code, and the detail names which one: an absent block, a session that
-    will not answer, a download over its bound, an envelope that will not decode, a tree that will
-    not verify, and a digest that disagrees.
+def _receipt_table_record(snapshot: Mapping[str, bytes]) -> dict[str, Any]:
+    """The ``table`` member of a receipt: the sealed execution's version and the sealed shape.
 
-    ``studio_origin`` is the DEPLOYMENT's Studio origin, not anything the job document said, and it
-    is what lets :func:`permitted_artifact_hosts` judge both signed addresses against a policy the
-    document's author cannot move.
+    Both are read out of the sealed tree through the same door the artifacts are, so a receipt
+    states what was sealed and nothing the build happened to hold in memory.
     """
 
+    try:
+        execution = parse_recipe_execution(json.loads(snapshot["recipe-execution.json"]))
+    except (KeyError, RecipeError, ValueError) as error:
+        raise RunExecutionError(
+            "ARTIFACT_PERSIST_FAILED",
+            failure_detail("the sealed tree carries no readable execution to state in the receipt"),
+            stage="persist",
+        ) from error
+    shape = profile_shape(snapshot, "this version")
+    return {
+        "table_id": execution.table_id,
+        "table_version_id": execution.table_version_id,
+        "table_version_number": execution.table_version_number,
+        "columns": [{"name": name, "logical_type": kind} for name, kind in shape.columns],
+        "row_count": shape.row_count,
+    }
+
+
+def _decode_predecessor_receipt(raw: bytes, job: RunExecution) -> PredecessorRecord:
+    """Read the authenticated receipt bytes into the record, or refuse by name."""
+
     block = job.predecessor
-    if block is None:
-        raise _predecessor_refusal(f"a {job.mode} run carries no predecessor block")
-    raw = _download_signed_bytes(
-        transfer,
-        block.artifact_download_session,
-        maximum=MAX_CANDIDATE_ENVELOPE_BYTES,
-        permitted_hosts=permitted_artifact_hosts(job, studio_origin=studio_origin),
-    )
+    assert block is not None
     try:
-        members = _decode_candidate_envelope(raw, block.candidate_digest)
-    except HostedWorkerError as error:
+        value = json.loads(raw.decode("utf-8"))
+    except (UnicodeDecodeError, ValueError) as error:
         raise _predecessor_refusal(
-            f"the predecessor candidate envelope will not decode: {error.detail}"
+            "the predecessor receipt will not decode: not a JSON document"
         ) from error
-    previous = root / "predecessor"
-    previous.mkdir(mode=0o700)
-    _restore_candidate_members(members, previous)
+    if not isinstance(value, Mapping) or value.get("schema_version") != RECEIPT_DOCUMENT_SCHEMA:
+        raise _predecessor_refusal(
+            f"the predecessor receipt will not decode: not a {RECEIPT_DOCUMENT_SCHEMA} document"
+        )
+    if str(value.get("run_id")) != str(block.run_id):
+        raise _predecessor_refusal("the predecessor receipt names a different run than the block")
+    if str(value.get("workspace_id")) != str(job.workspace_id):
+        raise _predecessor_refusal("the predecessor receipt names a different workspace")
+    table = value.get("table")
+    if not isinstance(table, Mapping):
+        raise _predecessor_refusal(
+            "the predecessor receipt states no table version, so a successor cannot number "
+            "itself after it; rebuild the table with a full run on this worker first"
+        )
     try:
-        verified = pipeline.verify_candidate(previous)
-    except Exception as error:
+        table_id = str(table["table_id"])
+        table_version_id = str(table["table_version_id"])
+        table_version_number = int(table["table_version_number"])
+        columns = tuple(
+            (str(entry["name"]), str(entry["logical_type"])) for entry in table["columns"]
+        )
+    except (KeyError, TypeError, ValueError) as error:
         raise _predecessor_refusal(
-            f"the restored predecessor tree will not replay-verify: {type(error).__name__}"
+            "the predecessor receipt's table member is not readable"
         ) from error
-    if "sha256:" + verified.candidate_digest != block.candidate_digest:
+    if table_version_id != block.table_version_id:
         raise _predecessor_refusal(
-            "the restored predecessor tree's digest disagrees with the predecessor block"
+            "the predecessor block and the sealed receipt name different table versions"
         )
-    return previous
+    if table_version_number < 1:
+        raise _predecessor_refusal("the predecessor receipt states no positive table version")
+    row_count = table.get("row_count")
+    sources = value.get("sources")
+    states: dict[str, str] = {}
+    if isinstance(sources, list):
+        for item in sources:
+            if isinstance(item, Mapping):
+                source_id = item.get("source_id")
+                digest = item.get("digest")
+                if isinstance(source_id, str) and isinstance(digest, str):
+                    states[source_id] = digest
+    candidate_digest = value.get("candidate_digest")
+    recipe_digest = value.get("recipe_digest")
+    if not isinstance(candidate_digest, str) or not isinstance(recipe_digest, str):
+        raise _predecessor_refusal("the predecessor receipt states no digests")
+    return PredecessorRecord(
+        run_id=block.run_id,
+        workspace_id=job.workspace_id,
+        recipe_digest=recipe_digest,
+        candidate_digest=candidate_digest,
+        table_id=table_id,
+        table_version_id=table_version_id,
+        table_version_number=table_version_number,
+        columns=columns,
+        row_count=row_count if isinstance(row_count, int) else None,
+        source_states=MappingProxyType(states),
+    )
 
 
-def predecessor_lock_inputs(previous_run_dir: Path) -> tuple[RecipeExecution, dict[str, str]]:
-    """Read the two facts the execution lock needs out of the RESTORED tree.
+def restore_predecessor_record(
+    job: RunExecution, *, transfer: Any, studio_origin: str = ""
+) -> PredecessorRecord:
+    """Download and authenticate the predecessor's sealed receipt, and read the record from it.
 
-    ``recipe-execution.json`` supplies ``table_id`` and ``table_version_number``. Reading them from
-    the tree rather than from the job document is the whole of "the restored tree is the
-    authority".
+    Studio's predecessor session names the predecessor's ``receipt`` artifact -- the
+    ``candidate_evidence`` root a refresh resolves from -- and the block's ``candidate_digest`` is
+    that receipt's own digest. The bytes are authenticated by the digest BEFORE they are read, so
+    a block that disagrees with what the session serves is a refusal and never a correction, and a
+    spoofed block cannot rebind a run to a version it did not come from (T-401-24): the version
+    coordinates are read from the authenticated receipt and cross-checked against the block.
 
-    **WHAT A SOURCE'S COMMITTED STATE IS DEPENDS ON WHAT THE PREDECESSOR SEALED, AND BOTH ANSWERS
-    ARE READ RATHER THAN COMPOSED.** A tree built from a versioned-source chain records a
-    ``committed_state_digest`` per source in ``evidence/recipe-acquisition.json`` -- the cursor the
-    chain committed at -- and that member is where the chain is re-checked from. A tree built from
-    a registered document runs no versioned source and seals no such member; what it does seal, per
-    relation, is the digest of the exact member the relation was read from. That digest is the
-    honest answer to "what state was this source committed at", because for this lane the bytes ARE
-    the state: there is no cursor, no watermark and nothing else the predecessor advanced.
+    Six failure points, one code, and the detail names which one: an absent block, a session that
+    will not answer, a download over its bound, a digest that disagrees, a receipt that will not
+    decode, and a receipt naming another run, workspace or table version.
 
-    Neither is invented. A tree carrying neither member refuses, because a successor bound to a
-    state nobody recorded would be a version claiming a predecessor it cannot name.
+    ``studio_origin`` is the DEPLOYMENT's Studio origin, not anything the job document said, and it
+    is what lets :func:`permitted_artifact_hosts` judge the signed address against a policy the
+    document's author cannot move.
     """
 
-    _, snapshot = _candidate_snapshot(previous_run_dir)
-    try:
-        execution = parse_recipe_execution(json.loads(snapshot["recipe-execution.json"]))
-    except (KeyError, RecipeError, ValueError) as error:
-        raise _predecessor_refusal(
-            "the restored predecessor tree carries no readable sealed execution"
-        ) from error
-    states = _committed_source_states(snapshot)
-    if states is None:
+    block = job.predecessor
+    if block is None:
+        raise _predecessor_refusal(f"a {job.mode} run carries no predecessor block")
+    raw = _download_signed_bytes(
+        transfer,
+        block.artifact_download_session,
+        maximum=MAX_CANDIDATE_ENVELOPE_BYTES,
+        permitted_hosts=permitted_artifact_hosts(job, studio_origin=studio_origin),
+    )
+    if "sha256:" + hashlib.sha256(raw).hexdigest() != block.candidate_digest:
         raise _predecessor_refusal(
-            "the restored predecessor tree carries no committed source state"
+            "the predecessor receipt's digest disagrees with the predecessor block"
         )
-    return execution, states
-
-
-#: Where one predecessor member records a source's committed state, and under which key. Written
-#: as a table because there are exactly two sealed shapes and the difference between them is which
-#: member exists, not how it is read.
-_COMMITTED_STATE_MEMBERS: tuple[tuple[str, str], ...] = (
-    ("evidence/recipe-acquisition.json", "committed_state_digest"),
-    ("evidence/sources.json", "sha256"),
-)
-
-
-def _committed_source_states(snapshot: Mapping[str, bytes]) -> dict[str, str] | None:
-    """The per-source committed state one restored tree records, or ``None`` if it records none."""
-
-    for member, key in _COMMITTED_STATE_MEMBERS:
-        raw = snapshot.get(member)
-        if raw is None:
-            continue
-        decoded = json.loads(raw)
-        sources = decoded.get("sources") if isinstance(decoded, Mapping) else decoded
-        if not isinstance(sources, list):
-            continue
-        states: dict[str, str] = {}
-        for item in sources:
-            if not isinstance(item, Mapping):
-                continue
-            source_id = item.get("source_id")
-            digest = item.get(key)
-            if isinstance(source_id, str) and isinstance(digest, str):
-                states[source_id] = digest
-        if states:
-            return states
-    return None
+    return _decode_predecessor_receipt(raw, job)
 
 
 # ------------------------------------------------------------------------------------------------
@@ -981,6 +1013,7 @@ def _receipt_document(
     verified: pipeline.VerifiedCandidate,
     coverage: Sequence[V4AcquisitionCoverage],
     raw_members: Sequence[Mapping[str, Any]],
+    snapshot: Mapping[str, bytes],
 ) -> bytes:
     """The composed v4 receipt: one entry per source, the coverage, and the raw tar's members.
 
@@ -1031,6 +1064,10 @@ def _receipt_document(
                 "media_type": RAW_SNAPSHOT_MEDIA_TYPE,
                 "members": [dict(member) for member in raw_members],
             },
+            # THE VERSION AND THE SHAPE THIS RUN SEALED, so a later refresh can number itself
+            # after this version and hold its columns against these, reading the authenticated
+            # receipt alone: a v4 run uploads no sealed tree for a successor to restore.
+            "table": _receipt_table_record(snapshot),
         }
     )
 
@@ -1040,7 +1077,7 @@ def v4_artifact_payloads(
     candidate_run_dir: Path,
     *,
     coverage: Sequence[V4AcquisitionCoverage] = (),
-    predecessor_run_dir: Path | None = None,
+    predecessor: PredecessorRecord | None = None,
 ) -> tuple[pipeline.VerifiedCandidate, list[ArtifactPayload]]:
     """Derive all five v4 artifacts from the sealed candidate tree, in layout order.
 
@@ -1078,17 +1115,14 @@ def v4_artifact_payloads(
             stage="persist",
         )
     verified, snapshot = _candidate_snapshot(candidate_run_dir)
-    # The restored predecessor tree, for the drift control a refresh is held to. Read through the
-    # same replay-verifying door as the candidate: what is compared is what was sealed.
-    predecessor_snapshot = (
-        None if predecessor_run_dir is None else _candidate_snapshot(predecessor_run_dir)[1]
-    )
+    # The authenticated predecessor record, for the drift control a refresh is held to: the
+    # sealed shape it states is what this version's sealed shape is compared with.
     run_required_controls(
         job,
         verified=verified,
         snapshot=snapshot,
         coverage=coverage,
-        predecessor_snapshot=predecessor_snapshot,
+        predecessor=predecessor,
     )
     candidate_digest = "sha256:" + verified.candidate_digest
     # The tar is built BEFORE the receipt, because the receipt states the tar's members: the
@@ -1107,7 +1141,7 @@ def v4_artifact_payloads(
             candidate_digest=candidate_digest,
         ),
         "preview": _table_preview(snapshot["data/table.parquet"], candidate_digest),
-        "receipt": _receipt_document(job, verified, coverage, raw_members),
+        "receipt": _receipt_document(job, verified, coverage, raw_members, snapshot),
         "raw_snapshot": _raw_snapshot_tar(snapshot, raw_paths),
     }
     return verified, [
@@ -2562,9 +2596,9 @@ def run_v4(
     with ExitStack() as stack:
         root = Path(stack.enter_context(tempfile.TemporaryDirectory(prefix="mr-v4-run-"))).resolve()
         try:
-            previous_run_dir: Path | None = None
-            predecessor_execution: RecipeExecution | None = None
-            source_states: dict[str, str] | None = None
+            predecessor: PredecessorRecord | None = None
+            predecessor_execution: PredecessorRecord | None = None
+            source_states: Mapping[str, str] | None = None
             # THE DECLARED CHECKS ARE PARSED FIRST, BEFORE A BYTE IS FETCHED OR RESTORED.
             # `parse_declared_checks` is entirely static -- it validates every check's kind, its
             # exact parameter set, its domains and every column it names against the plan's own
@@ -2597,10 +2631,11 @@ def run_v4(
             if job.mode in {"refresh", "backfill"}:
                 if transfer is None:
                     transfer = stack.enter_context(_closing(_new_transfer_client()))
-                previous_run_dir = restore_predecessor_tree(
-                    job, transfer=transfer, root=root, studio_origin=origin
+                predecessor = restore_predecessor_record(
+                    job, transfer=transfer, studio_origin=origin
                 )
-                predecessor_execution, source_states = predecessor_lock_inputs(previous_run_dir)
+                predecessor_execution = predecessor
+                source_states = predecessor.source_states
 
             approval, execution = synthesize_execution_lock(
                 job,
@@ -2712,7 +2747,7 @@ def run_v4(
                 job,
                 output_dir,
                 coverage=coverage_log.entries(),
-                predecessor_run_dir=previous_run_dir,
+                predecessor=predecessor,
             )
             _upload_all(
                 job,
@@ -3082,6 +3117,7 @@ __all__ = [
     "RECEIPT_DOCUMENT_SCHEMA",
     "V4_ARTIFACT_LAYOUT",
     "ArtifactSealer",
+    "PredecessorRecord",
     "StudioArtifactSealer",
     "StudioCredentialRedeemer",
     "StudioRunCallbacks",
@@ -3089,9 +3125,8 @@ __all__ = [
     "artifact_id_for",
     "build_v4_candidate",
     "permitted_artifact_hosts",
-    "predecessor_lock_inputs",
     "recipe_governance",
-    "restore_predecessor_tree",
+    "restore_predecessor_record",
     "run_v4",
     "run_worker_main",
     "seal_coordinate",

{mostlyright_data-0.10.6 → mostlyright_data-0.10.7}/src/mostlyright/data_harness/run_execution_v4.py

@@ -1407,10 +1407,28 @@ def _refuse_unbindable_watermark(job: RunExecution) -> None:
             )
 
 
+class PredecessorExecution(Protocol):
+    """The three facts the lock reads off a predecessor: its table, its version, its number.
+
+    Satisfied by the engine's own ``RecipeExecution`` and by the worker's authenticated
+    ``PredecessorRecord`` alike, so the lock is indifferent to which sealed member they were read
+    from.
+    """
+
+    @property
+    def table_id(self) -> str: ...
+
+    @property
+    def table_version_id(self) -> str: ...
+
+    @property
+    def table_version_number(self) -> int: ...
+
+
 def synthesize_execution_lock(
     job: RunExecution,
     *,
-    predecessor_execution: RecipeExecution | None = None,
+    predecessor_execution: PredecessorExecution | None = None,
     predecessor_source_states: Mapping[str, str] | None = None,
     trusted_clock: str | None = None,
 ) -> tuple[RecipeApproval, RecipeExecution]:
@@ -1422,18 +1440,19 @@ def synthesize_execution_lock(
     keeps ``pipeline._RECIPE_STATIC_FILES`` intact and the synthesized documents are still sealed
     into the candidate as honest evidence of what ran.
 
-    ``predecessor_execution`` is the ``RecipeExecution`` parsed out of the RESTORED predecessor
-    tree's sealed ``recipe-execution.json``, not out of the job document: the sealed member is the
-    authority and the block is only the coordinate. 401-04 restores the tree, parses that member
-    and passes it in. A non-``initial`` call without it refuses ``PREDECESSOR_UNAVAILABLE`` rather
+    ``predecessor_execution`` is read out of the predecessor's AUTHENTICATED sealed receipt (the
+    ``table`` member it states), not out of the job document: the sealed member is the authority
+    and the block is only the coordinate. The driver downloads the receipt, authenticates it by
+    the block's digest and passes the record in. A non-``initial`` call without it refuses
+    ``PREDECESSOR_UNAVAILABLE`` rather
     than guessing a version number, and the one value that appears in both places --
     ``table_version_id`` -- is cross-checked, so a spoofed block cannot rebind a run to a tree it
     did not come from. (``candidate_digest`` has no counterpart on ``RecipeExecution``: the
     ``predecessor_candidate_digest`` member there names the predecessor's OWN predecessor, not
     itself. Authenticating the digest against the restored tree is 401-04's, where the tree is.)
 
-    ``predecessor_source_states`` carries the per-source ``committed_state_digest`` read from the
-    predecessor tree's sealed ``evidence/recipe-acquisition.json``.
+    ``predecessor_source_states`` carries the per-source committed state read from the same
+    receipt: for a registered document, the digest of the bytes each source was read as.
     ``_validate_recipe_execution`` requires one for every source of a non-``initial`` execution,
     and the job document carries none, so 401-04 supplies them from the same restored tree.
 

{mostlyright_data-0.10.6 → mostlyright_data-0.10.7}/src/mostlyright/data_harness/v4_required_controls.py

@@ -75,7 +75,7 @@ import json
 from collections.abc import Mapping, Sequence
 from dataclasses import dataclass
 from types import MappingProxyType
-from typing import Any
+from typing import Any, Protocol
 
 from mostlyright.data_harness import pipeline
 from mostlyright.data_harness.canonical import sha256_bytes
@@ -210,28 +210,39 @@ def _exact_candidate_replay(
 # ------------------------------------------------------------------------------------------------
 
 
+class PredecessorShape(Protocol):
+    """The sealed shape a predecessor stated; the authenticated receipt record reads it."""
+
+    @property
+    def columns(self) -> tuple[tuple[str, str], ...]: ...
+
+    @property
+    def row_count(self) -> int | None: ...
+
+
 def _recipe_drift(
     job: Any,
     snapshot: Mapping[str, bytes],
-    predecessor: Mapping[str, bytes] | None,
+    predecessor: PredecessorShape | None,
 ) -> ControlOutcome:
-    """NOT_APPLICABLE on a first version; APPLIED on a refresh, against the restored predecessor.
+    """NOT_APPLICABLE on a first version; APPLIED on a refresh, against the predecessor record.
 
     Every finding the older engine's drift report can raise is a comparison against a PREDECESSOR
     version -- a column set that lost a column, a column whose type moved, a row count outside the
     envelope a refresh policy stated. A ``sample`` or ``full`` creates version one and has nothing
     on the other side of any of the three, so the control does not apply and the outcome says why.
 
-    A ``refresh`` continues from a predecessor this worker restored and replay-verified, and the
-    comparison it can honestly make is the one both sealed trees state exactly: the column set and
-    the closed logical type of every column, read from each tree's ``evidence/profile.json``. A
-    column that disappeared, appeared or changed type is drift and the version is refused. The row
-    count is reported and NOT judged: the registered document has no member for a row-count
-    envelope, so any bound applied here would be one nobody set.
-
-    **THE PRECONDITION IS CHECKED EVERY RUN.** A refresh that reaches the seal with no restored
-    predecessor in hand is a worker fault -- something moved and this control was not handed the
-    tree -- and is refused rather than sealed as compared to nothing.
+    A ``refresh`` continues from a predecessor whose sealed receipt this worker authenticated, and
+    the comparison it can honestly make is the one both sealed records state exactly: the column
+    set and the closed logical type of every column -- the receipt's ``table.columns`` on one side
+    and this tree's ``evidence/profile.json`` on the other. A column that disappeared, appeared or
+    changed type is drift and the version is refused. The row count is reported and NOT judged:
+    the registered document has no member for a row-count envelope, so any bound applied here
+    would be one nobody set.
+
+    **THE PRECONDITION IS CHECKED EVERY RUN.** A refresh that reaches the seal with no
+    authenticated predecessor in hand is a worker fault -- something moved and this control was
+    not handed the record -- and is refused rather than sealed as compared to nothing.
     """
 
     mode = engine_execution_mode(job)
@@ -248,10 +259,10 @@ def _recipe_drift(
         raise _void(
             "RECIPE_DRIFT",
             f"this run continues from a predecessor as a {job.mode}, and the seal was handed no "
-            "restored predecessor tree to compare the successor with",
+            "authenticated predecessor record to compare the successor with",
         )
-    before = _profile_shape(predecessor, "the restored predecessor")
-    after = _profile_shape(snapshot, "this version")
+    before = _ProfileShape(columns=tuple(predecessor.columns), row_count=predecessor.row_count)
+    after = profile_shape(snapshot, "this version")
     if before.columns != after.columns:
         lost = [name for name, _ in before.columns if name not in dict(after.columns)]
         added = [name for name, _ in after.columns if name not in dict(before.columns)]
@@ -287,8 +298,12 @@ class _ProfileShape:
     row_count: int | None
 
 
-def _profile_shape(snapshot: Mapping[str, bytes], label: str) -> _ProfileShape:
-    """The sealed column set and row count a tree's ``evidence/profile.json`` states."""
+def profile_shape(snapshot: Mapping[str, bytes], label: str) -> _ProfileShape:
+    """The sealed column set and row count a tree's ``evidence/profile.json`` states.
+
+    Public because the receipt states this shape for the version it seals, so a later refresh
+    can compare against it without a tree to read: one reader for both sides of the comparison.
+    """
 
     try:
         profile = json.loads(snapshot["evidence/profile.json"])
@@ -574,7 +589,7 @@ def run_required_controls(
     verified: pipeline.VerifiedCandidate,
     snapshot: Mapping[str, bytes],
     coverage: Sequence[Any],
-    predecessor_snapshot: Mapping[str, bytes] | None = None,
+    predecessor: PredecessorShape | None = None,
 ) -> tuple[ControlOutcome, ...]:
     """Evaluate every required control's disposition for one sealed version, in inventory order.
 
@@ -592,7 +607,7 @@ def run_required_controls(
     reader looks for them in.
     """
 
-    drift = _recipe_drift(job, snapshot, predecessor_snapshot)
+    drift = _recipe_drift(job, snapshot, predecessor)
     temporal = _temporal_integrity(job)
     outcomes = (
         _exact_candidate_replay(verified, snapshot),