mostlyright-data 0.9.0__py3-none-any.whl

mostlyright/data_harness/sources/stream_recorder.py

@@ -0,0 +1,1404 @@
+"""Deterministic stream capture: seal recorded messages, then read them back as batches.
+
+Capture and build stay separate.  A live socket can never satisfy the determinism contract --
+a Checker cannot replay a subscription -- so a connection is a *capture* role, not an
+acquisition transport.  This module is the half of that split which is deterministic, and it is
+the whole of what this build ships:
+
+* :func:`seal_recorded_capture` takes an already-recorded list of provider messages and turns
+  it into bounded, sealed, ordered batch files plus a capture manifest.  Epochs, rotation,
+  message classification, event identity, and gap boundaries are all decided here, from the
+  connector configuration, with no clock and no connection.
+* :class:`RecordedStreamGateway` implements the one-method ``StreamGateway`` the existing
+  ``StreamBatchAdapter`` already consumes, reading those sealed batches back off disk.
+
+What is deliberately absent is the socket.  Nothing in this module opens, resolves, or reads a
+network address; network access belongs to the Courier, and a Recorder that holds a long-lived
+connection is a separate trusted role that does not exist yet.  The recording this module reads
+is therefore an input the operator supplies, not something this build goes and gets.  Everything
+downstream of the recording -- rotation, sealing, identity, ordering, the bookmark -- is the
+real behaviour, exercised on real bytes.
+
+The recording format is one JSON object per line, each with exactly three keys::
+
+    {"epoch": 1, "received_at": "2026-07-17T12:00:00Z", "message": {...}}
+
+``epoch`` is the connection the message arrived on.  A disconnect closes an epoch and the next
+message carries the next epoch number; that boundary is a gap and is recorded as one.  Gaps stay
+loud: nothing here silently splices two connections together.
+"""
+
+from __future__ import annotations
+
+import os
+import re
+import stat
+from dataclasses import dataclass
+from datetime import datetime
+from pathlib import Path
+from typing import Any
+
+from mostlyright.data_harness.acquisition.http import seal_content_addressed_snapshot
+from mostlyright.data_harness.canonical import (
+    canonical_json_bytes,
+    canonical_sha256,
+    parse_json,
+    sha256_bytes,
+)
+from mostlyright.data_harness.sources.contracts import (
+    AcquisitionRequest,
+    SourceContractError,
+)
+from mostlyright.data_harness.sources.stream import (
+    EVENT_ID_GRAMMAR,
+    MAX_BATCH_EVENTS,
+    StreamBatch,
+)
+from mostlyright.data_harness.sources.stream_connector import (
+    EVENT_TIME_KINDS,
+    StreamConnectorConfig,
+    stream_connector,
+)
+
+STREAM_CAPTURE_VERSION = "harness-stream-capture.v1"
+
+CAPTURE_MANIFEST_NAME = "capture.json"
+BATCH_DIRECTORY_NAME = "batches"
+# The durable per-source bookmark ledger lives beside the batches it is about, so one capture
+# directory is the whole replayable unit.  ``stream_connector.RESERVED_STREAM_IDS`` keeps a
+# stream from claiming this name.
+LEDGER_DIRECTORY_NAME = "bookmarks"
+
+MAX_RECORDING_BYTES = 64 * 1024 * 1024
+MAX_MANIFEST_BYTES = 64 * 1024 * 1024
+MAX_RECORDED_FRAMES = 200_000
+MAX_EPOCHS = 4_096
+MAX_BATCHES = 4_096
+
+_TIMESTAMP = re.compile(r"[0-9]{4}-[0-9]{2}-[0-9]{2}T[0-9]{2}:[0-9]{2}:[0-9]{2}(?:\.[0-9]{1,9})?Z")
+_STORAGE_NAME = re.compile(r"[0-9a-f]{64}\.(?:json|ndjson)")
+# The bookmark grammar: the Recorder's own ``{epoch}:{counter}`` position, zero-padded so that
+# text order and number order are the same thing.  It is deliberately not the event name -- a
+# venue that assigns its own identifiers assigns ``8``, ``9``, ``10``, which do not sort as
+# text, and a bookmark that cannot be compared is not a bookmark.
+_BOOKMARK = re.compile(r"e([0-9]{8}):([0-9]{12})")
+_RECORDING_KEYS = frozenset({"epoch", "received_at", "message"})
+
+_MEDIA_TYPES = {"ndjson": "application/x-ndjson", "json": "application/json"}
+
+# A gap boundary is one of exactly these.  ``opening`` is the first connection of a capture and
+# is not a gap at all; the other two say whether the venue's own repair rule closed the hole.
+GAP_BOUNDARIES = ("opening", "repaired_by_snapshot", "recorded_gap")
+
+
+@dataclass(frozen=True)
+class CapturedEpoch:
+    """One connection: what it covered and whether the boundary before it left a hole."""
+
+    epoch: int
+    boundary: str
+    event_count: int
+    # Null when the connection admitted no event at all.  A connection that carried only
+    # heartbeats has no first or last event, and inventing one would be a claim about data that
+    # was never captured.
+    first_event_id: str | None
+    last_event_id: str | None
+    opened_at: str
+    closed_at: str
+
+    def to_dict(self) -> dict[str, Any]:
+        return {
+            "epoch": self.epoch,
+            "boundary": self.boundary,
+            "event_count": self.event_count,
+            "first_event_id": self.first_event_id,
+            "last_event_id": self.last_event_id,
+            "opened_at": self.opened_at,
+            "closed_at": self.closed_at,
+        }
+
+
+@dataclass(frozen=True)
+class CapturedBatch:
+    """One sealed batch file and the bookmark it advances to."""
+
+    batch_index: int
+    epoch: int
+    storage_name: str
+    content_sha256: str
+    size_bytes: int
+    previous_bookmark: str | None
+    next_bookmark: str
+    event_ids: tuple[str, ...]
+    first_event_time: str
+    last_event_time: str
+    first_received_at: str
+    last_received_at: str
+
+    def to_dict(self) -> dict[str, Any]:
+        return {
+            "batch_index": self.batch_index,
+            "epoch": self.epoch,
+            "storage_name": self.storage_name,
+            "content_sha256": self.content_sha256,
+            "size_bytes": self.size_bytes,
+            "previous_bookmark": self.previous_bookmark,
+            "next_bookmark": self.next_bookmark,
+            "event_ids": list(self.event_ids),
+            "first_event_time": self.first_event_time,
+            "last_event_time": self.last_event_time,
+            "first_received_at": self.first_received_at,
+            "last_received_at": self.last_received_at,
+        }
+
+
+@dataclass(frozen=True)
+class CaptureManifest:
+    """The capture's own evidence: what was configured, what arrived, and what was sealed.
+
+    This is not the chained capture-evidence contract that stream work still ahead describes.  It
+    is the flat, digest-bound record needed to read a capture back deterministically, and it is
+    versioned separately so a chained contract can supersede it without rewriting captures.
+
+    ``recorded_through`` is the arrival time of the last message the capture admitted, read out
+    of the recording.  It is deliberately not "when the recorder ran": a capture sealed from one
+    recording has one record whatever day it is sealed on, which is what lets a build be replayed
+    from the recording alone.
+    """
+
+    connector_id: str
+    connector_config_digest: str
+    stream_id: str
+    data_format: str
+    batch_filename: str
+    recorded_through: str
+    admitted_event_count: int
+    ignored_message_count: int
+    epochs: tuple[CapturedEpoch, ...]
+    batches: tuple[CapturedBatch, ...]
+    schema_version: str = STREAM_CAPTURE_VERSION
+
+    def to_dict(self) -> dict[str, Any]:
+        return {
+            "schema_version": self.schema_version,
+            "connector_id": self.connector_id,
+            "connector_config_digest": self.connector_config_digest,
+            "stream_id": self.stream_id,
+            "data_format": self.data_format,
+            "batch_filename": self.batch_filename,
+            "recorded_through": self.recorded_through,
+            "admitted_event_count": self.admitted_event_count,
+            "ignored_message_count": self.ignored_message_count,
+            "epochs": [epoch.to_dict() for epoch in self.epochs],
+            "batches": [batch.to_dict() for batch in self.batches],
+        }
+
+    @property
+    def digest(self) -> str:
+        return canonical_sha256(self.to_dict())
+
+    @property
+    def gap_count(self) -> int:
+        return sum(1 for epoch in self.epochs if epoch.boundary == "recorded_gap")
+
+
+@dataclass(frozen=True)
+class _Connection:
+    """One connection the recording saw, whether or not it contributed an event.
+
+    A connection that carried only heartbeats is still a connection, and dropping it from the
+    record would splice its neighbours together silently -- which is the one thing this module
+    promises not to do.
+    """
+
+    epoch: int
+    opened_at: str
+    closed_at: str
+    opened_with_snapshot: bool
+
+
+@dataclass(frozen=True)
+class _Frame:
+    """One recorded message after classification, with the identity the Recorder assigned."""
+
+    epoch: int
+    sequence: int
+    event_id: str
+    position: str
+    message_class: str
+    message_type: str
+    event_time: str
+    received_at: str
+    line: bytes
+
+
+def capture_root(captures_root: Path, stream_id: str) -> Path:
+    """Return the one directory a stream's sealed capture lives in.
+
+    The whole layout is derived from the capture root, never assembled by a caller, so a build
+    and a recording cannot disagree about where a capture is::
+
+        <captures_root>/bookmarks/                 the durable per-source ledger, shared
+        <captures_root>/<stream_id>/capture.json   one stream's sealed record
+        <captures_root>/<stream_id>/batches/       its digest-addressed sealed batches
+
+    The ledger is shared across streams because one build holds one bookmark store; the reserved
+    names in ``stream_connector`` are what keep a stream from claiming that directory.
+    """
+
+    return captures_root / _capture_component(stream_id)
+
+
+def ledger_root(captures_root: Path) -> Path:
+    """Return the durable bookmark ledger directory for a whole capture root."""
+
+    return captures_root / LEDGER_DIRECTORY_NAME
+
+
+def seal_recorded_capture(
+    *,
+    config: StreamConnectorConfig,
+    recording: bytes,
+    captures_root: Path,
+) -> CaptureManifest:
+    """Turn one recorded message log into sealed batches beneath ``captures_root``.
+
+    Every directory the layout needs is created if missing, so one call leaves a complete
+    capture a build can read.
+
+    Re-running the same recording is a no-op that produces the identical manifest: batch files
+    are content-addressed, sealing bytes that are already there returns the existing file, and
+    every time in the record is read out of the recording rather than off a clock.  There is no
+    clock input at all, which is what makes a capture reproducible from its recording alone.
+    """
+
+    if not captures_root.is_absolute():
+        raise SourceContractError(
+            "STREAM_CAPTURE_ROOT",
+            "captures_root",
+            "must be an absolute coordinator-owned path",
+        )
+    frames, ignored, connections = _classify_recording(config, recording)
+    epochs, batches_of_frames = _partition(config, frames, connections)
+    stream_root = capture_root(captures_root, config.stream_id)
+    batch_root = stream_root / BATCH_DIRECTORY_NAME
+    # Every directory is made and then checked to be a real directory rather than a link to
+    # one.  ``mkdir(exist_ok=True)`` accepts a pre-existing symlink to a directory, so the
+    # check is what stops a planted link from deciding where a capture is written.  It happens
+    # before any byte is written, so a refusal leaves nothing behind.
+    for directory in (captures_root, stream_root, batch_root, ledger_root(captures_root)):
+        _require_plain_directory(directory)
+    batches: list[CapturedBatch] = []
+    previous: str | None = None
+    for index, group in enumerate(batches_of_frames, start=1):
+        content = b"".join(frame.line for frame in group)
+        # The one sealing implementation, reused rather than written a second time: it is
+        # content-addressed, refuses to overwrite, follows no link, and returns the existing
+        # file when the bytes are already there, which is what makes re-sealing a no-op.  It
+        # raises ``AcquisitionSecurityError`` rather than this module's own error type; both
+        # are typed refusals the command boundary already renders.
+        #
+        # The path is handed over unresolved on purpose.  ``seal_content_addressed_snapshot``
+        # opens its root with ``O_NOFOLLOW``, and resolving the path here would hand it the
+        # link's target instead, so the guard would open a real directory and never fire.
+        path = seal_content_addressed_snapshot(
+            batch_root,
+            content=content,
+            suffix=config.data_format,
+        )
+        bookmark = group[-1].position
+        batches.append(
+            CapturedBatch(
+                batch_index=index,
+                epoch=group[0].epoch,
+                storage_name=path.name,
+                content_sha256=sha256_bytes(content),
+                size_bytes=len(content),
+                previous_bookmark=previous,
+                next_bookmark=bookmark,
+                event_ids=tuple(frame.event_id for frame in group),
+                first_event_time=group[0].event_time,
+                last_event_time=group[-1].event_time,
+                first_received_at=group[0].received_at,
+                last_received_at=group[-1].received_at,
+            )
+        )
+        previous = bookmark
+    manifest = CaptureManifest(
+        connector_id=config.connector_id,
+        connector_config_digest=config.digest,
+        stream_id=config.stream_id,
+        data_format=config.data_format,
+        batch_filename=f"{config.stream_id}.{config.data_format}",
+        recorded_through=frames[-1].received_at,
+        admitted_event_count=len(frames),
+        ignored_message_count=ignored,
+        epochs=epochs,
+        batches=tuple(batches),
+    )
+    _write_manifest(stream_root, manifest)
+    return manifest
+
+
+@dataclass(frozen=True)
+class RecordedStreamGateway:
+    """A ``StreamGateway`` over sealed recorded batches; it reaches no network at all.
+
+    ``observed_at`` and ``available_at`` are coordinator inputs, not capture facts.  The adapter
+    checks the batch it gets back against the observation evidence the coordinator recorded, and
+    a gateway that answered with times it read out of a file would make that check a tautology.
+    When the capture happened is separate evidence and lives in the manifest.
+    """
+
+    captures_root: Path
+    observed_at: str
+    available_at: str
+
+    def __post_init__(self) -> None:
+        if (
+            not self.captures_root.is_absolute()
+            or self.captures_root.is_symlink()
+            or not self.captures_root.is_dir()
+        ):
+            raise SourceContractError(
+                "STREAM_CAPTURE_ROOT",
+                "gateway.captures_root",
+                "must be an existing absolute non-symlink directory",
+            )
+        for name, value in (("observed_at", self.observed_at), ("available_at", self.available_at)):
+            _moment(value, f"gateway.{name}")
+
+    def read_batch(self, request: AcquisitionRequest) -> StreamBatch:
+        """Return the one sealed batch that follows the bookmark the request carries."""
+
+        query = request.query
+        stream_id = query["stream_id"]
+        manifest = self.manifest(stream_id)
+        if query["data_format"] != manifest.data_format:
+            raise SourceContractError(
+                "STREAM_CAPTURE_BINDING",
+                "request.query.data_format",
+                "differs from the format this capture was sealed in",
+            )
+        if query["filename"] != manifest.batch_filename:
+            raise SourceContractError(
+                "STREAM_CAPTURE_BINDING",
+                "request.query.filename",
+                "differs from the name this capture seals its batches under",
+            )
+        expected = query["expected_watermark"]
+        following = [batch for batch in manifest.batches if batch.previous_bookmark == expected]
+        if not following:
+            raise SourceContractError(
+                "STREAM_CAPTURE_EXHAUSTED",
+                "request.query.expected_watermark",
+                "this capture holds no sealed batch after the bookmark the request carries",
+            )
+        if len(following) > 1:
+            # The loader already refuses a record whose batches do not form one unbroken chain,
+            # so this cannot fire against a record that got this far.  It is kept as the second
+            # gate on the same invariant, at the point the choice is actually made: a bug that
+            # served two batches for one bookmark would have to defeat both.
+            raise SourceContractError(
+                "STREAM_CAPTURE_AMBIGUOUS",
+                "capture.batches",
+                "more than one sealed batch claims the same predecessor bookmark",
+            )
+        selected = following[0]
+        content = _read_sealed_batch(
+            capture_root(self.captures_root, stream_id) / BATCH_DIRECTORY_NAME,
+            storage_name=selected.storage_name,
+            expected_size=selected.size_bytes,
+        )
+        if sha256_bytes(content) != selected.content_sha256:
+            raise SourceContractError(
+                "STREAM_CAPTURE_DIGEST",
+                "capture.batches",
+                "sealed batch bytes do not match the digest the capture recorded",
+            )
+        return StreamBatch(
+            query_digest=request.query_digest,
+            previous_watermark=selected.previous_bookmark,
+            next_watermark=selected.next_bookmark,
+            provider_event_ids=selected.event_ids,
+            content=content,
+            content_sha256=selected.content_sha256,
+            media_type=_MEDIA_TYPES[manifest.data_format],
+            data_format=manifest.data_format,
+            filename=manifest.batch_filename,
+            observed_at=self.observed_at,
+            available_at=self.available_at,
+        )
+
+    def manifest(self, stream_id: str) -> CaptureManifest:
+        """Return the sealed capture manifest for one stream beneath the capture root."""
+
+        root = capture_root(self.captures_root, stream_id)
+        raw = _read_capture_file(root, CAPTURE_MANIFEST_NAME, MAX_MANIFEST_BYTES)
+        manifest = read_capture_manifest(raw)
+        if manifest.stream_id != stream_id:
+            raise SourceContractError(
+                "STREAM_CAPTURE_BINDING",
+                "capture.stream_id",
+                "the capture found under this name records a different stream",
+            )
+        return manifest
+
+
+def read_capture_manifest(raw: bytes) -> CaptureManifest:
+    """Parse and re-validate one sealed capture manifest.
+
+    Every structural rule the writer applied is checked again here, because a manifest is read
+    back from disk long after it was written and a build that trusted it unchecked would be
+    trusting a file, not evidence.
+    """
+
+    value = parse_json(raw)
+    _exact_keys(
+        value,
+        {
+            "schema_version",
+            "connector_id",
+            "connector_config_digest",
+            "stream_id",
+            "data_format",
+            "batch_filename",
+            "recorded_through",
+            "admitted_event_count",
+            "ignored_message_count",
+            "epochs",
+            "batches",
+        },
+        "capture",
+    )
+    if value["schema_version"] != STREAM_CAPTURE_VERSION:
+        raise SourceContractError(
+            "STREAM_CAPTURE_VERSION",
+            "capture.schema_version",
+            "is unsupported",
+        )
+    config = stream_connector(value["connector_id"])
+    if value["connector_config_digest"] != config.digest:
+        raise SourceContractError(
+            "STREAM_CAPTURE_CONNECTOR",
+            "capture.connector_config_digest",
+            "this capture was sealed under a different connector configuration",
+        )
+    if value["stream_id"] != config.stream_id or value["data_format"] != config.data_format:
+        raise SourceContractError(
+            "STREAM_CAPTURE_CONNECTOR",
+            "capture.stream_id",
+            "capture identity differs from its own connector configuration",
+        )
+    if value["batch_filename"] != f"{config.stream_id}.{config.data_format}":
+        raise SourceContractError(
+            "STREAM_CAPTURE_CONNECTOR",
+            "capture.batch_filename",
+            "capture batch name differs from its own connector configuration",
+        )
+    _moment(value["recorded_through"], "capture.recorded_through")
+    for name in ("admitted_event_count", "ignored_message_count"):
+        if type(value[name]) is not int or not 0 <= value[name] <= MAX_RECORDED_FRAMES:
+            raise SourceContractError("STREAM_CAPTURE", f"capture.{name}", "is out of bounds")
+    epochs = _read_epochs(value["epochs"])
+    batches = _read_batches(value["batches"], config=config)
+    admitted = sum(len(batch.event_ids) for batch in batches)
+    if admitted != value["admitted_event_count"]:
+        raise SourceContractError(
+            "STREAM_CAPTURE",
+            "capture.admitted_event_count",
+            "does not match the events the sealed batches hold",
+        )
+    _require_consistent_capture(epochs, batches, recorded_through=value["recorded_through"])
+    return CaptureManifest(
+        connector_id=value["connector_id"],
+        connector_config_digest=value["connector_config_digest"],
+        stream_id=value["stream_id"],
+        data_format=value["data_format"],
+        batch_filename=value["batch_filename"],
+        recorded_through=value["recorded_through"],
+        admitted_event_count=value["admitted_event_count"],
+        ignored_message_count=value["ignored_message_count"],
+        epochs=epochs,
+        batches=batches,
+    )
+
+
+def _classify_recording(
+    config: StreamConnectorConfig,
+    recording: bytes,
+) -> tuple[tuple[_Frame, ...], int, tuple[_Connection, ...]]:
+    """Read the recording, classify every message, and assign identity and event time.
+
+    Returns the admitted frames, how many messages the connector classified as ignored, and
+    every connection the recording saw.  The ignored count is carried rather than recomputed
+    because it is capture evidence: a capture that dropped a thousand heartbeats and one that
+    dropped none are different captures.  The connections are carried for the same reason and a
+    stronger one -- a connection that admitted nothing at all still has to appear in the record,
+    or its two neighbours are spliced together with nothing saying so.
+    """
+
+    if not isinstance(recording, bytes | bytearray):
+        raise SourceContractError("STREAM_RECORDING", "recording", "must be exact bytes")
+    if not recording or len(recording) > MAX_RECORDING_BYTES:
+        raise SourceContractError(
+            "STREAM_RECORDING",
+            "recording",
+            f"must be non-empty and no larger than {MAX_RECORDING_BYTES} bytes",
+        )
+    lines = bytes(recording).split(b"\n")
+    if lines[-1] != b"":
+        raise SourceContractError(
+            "STREAM_RECORDING",
+            "recording",
+            "every recorded line must end with a newline",
+        )
+    lines = lines[:-1]
+    if not lines or len(lines) > MAX_RECORDED_FRAMES:
+        raise SourceContractError(
+            "STREAM_RECORDING",
+            "recording",
+            f"must hold between one and {MAX_RECORDED_FRAMES} recorded messages",
+        )
+    frames: list[_Frame] = []
+    connections: list[dict[str, Any]] = []
+    ignored = 0
+    epoch = 0
+    sequence = 0
+    epoch_opened = False
+    previous_received: datetime | None = None
+    for number, line in enumerate(lines, start=1):
+        where = f"recording.line[{number}]"
+        value = parse_json(line)
+        _exact_keys(value, _RECORDING_KEYS, where)
+        frame_epoch = value["epoch"]
+        if type(frame_epoch) is not int or not 1 <= frame_epoch <= MAX_EPOCHS:
+            raise SourceContractError(
+                "STREAM_RECORDING",
+                f"{where}.epoch",
+                f"must be an integer between 1 and {MAX_EPOCHS}",
+            )
+        if frame_epoch != epoch:
+            if frame_epoch != epoch + 1:
+                raise SourceContractError(
+                    "STREAM_RECORDING",
+                    f"{where}.epoch",
+                    "connections must be numbered from one with no skipped connection",
+                )
+            epoch = frame_epoch
+            sequence = 0
+            epoch_opened = False
+            connections.append(
+                {
+                    "epoch": epoch,
+                    "opened_at": value["received_at"],
+                    "closed_at": value["received_at"],
+                    "opened_with_snapshot": False,
+                }
+            )
+        received = _moment(value["received_at"], f"{where}.received_at")
+        if previous_received is not None and received < previous_received:
+            raise SourceContractError(
+                "STREAM_RECORDING",
+                f"{where}.received_at",
+                "recorded messages must not move backwards in time",
+            )
+        previous_received = received
+        message = value["message"]
+        if not isinstance(message, dict) or not message:
+            raise SourceContractError(
+                "STREAM_RECORDING",
+                f"{where}.message",
+                "must be a non-empty JSON object",
+            )
+        message_type = message.get(config.message_type_field)
+        if not isinstance(message_type, str):
+            raise SourceContractError(
+                "STREAM_MESSAGE_TYPE",
+                f"{where}.message.{config.message_type_field}",
+                "must be the text message type the connector classifies on",
+            )
+        message_class = config.message_class(message_type)
+        connections[-1]["closed_at"] = value["received_at"]
+        if message_class == "ignored":
+            ignored += 1
+            continue
+        if not epoch_opened and config.gap_repair == "snapshot_on_subscribe":
+            if message_class != "snapshot":
+                raise SourceContractError(
+                    "STREAM_CAPTURE_GAP_UNREPAIRED",
+                    f"{where}.message",
+                    "this connector repairs a connection with a full snapshot and this "
+                    "connection did not open with one",
+                )
+        if not epoch_opened:
+            connections[-1]["opened_with_snapshot"] = message_class == "snapshot"
+        epoch_opened = True
+        sequence += 1
+        event_id = _event_id(config, message, epoch=epoch, sequence=sequence, where=where)
+        event_time = _event_time(config, message, where=where)
+        frames.append(
+            _Frame(
+                epoch=epoch,
+                sequence=sequence,
+                event_id=event_id,
+                position=_position(epoch, sequence),
+                message_class=message_class,
+                message_type=message_type,
+                event_time=event_time,
+                received_at=value["received_at"],
+                line=canonical_json_bytes(
+                    {
+                        "epoch": epoch,
+                        "event_id": event_id,
+                        "event_time": event_time,
+                        "message": message,
+                        "message_class": message_class,
+                        "message_type": message_type,
+                        "received_at": value["received_at"],
+                        "sequence": sequence,
+                    }
+                )
+                + b"\n",
+            )
+        )
+    if not frames:
+        raise SourceContractError(
+            "STREAM_RECORDING",
+            "recording",
+            "every recorded message was ignored, so there is nothing to seal",
+        )
+    identities = [frame.event_id for frame in frames]
+    if len(set(identities)) != len(identities):
+        raise SourceContractError(
+            "STREAM_EVENT_ID",
+            "recording",
+            "the connector's identity rule did not give every message a distinct name",
+        )
+    return (
+        tuple(frames),
+        ignored,
+        tuple(
+            _Connection(
+                epoch=item["epoch"],
+                opened_at=item["opened_at"],
+                closed_at=item["closed_at"],
+                opened_with_snapshot=item["opened_with_snapshot"],
+            )
+            for item in connections
+        ),
+    )
+
+
+def _partition(
+    config: StreamConnectorConfig,
+    frames: tuple[_Frame, ...],
+    connections: tuple[_Connection, ...],
+) -> tuple[tuple[CapturedEpoch, ...], tuple[tuple[_Frame, ...], ...]]:
+    """Split the classified frames into epochs and into rotation-bounded batches.
+
+    Every connection the recording saw becomes an epoch, including one that admitted nothing, so
+    the numbering stays unbroken and a dropped connection is visible as itself rather than as an
+    absence.  A batch never spans a connection: an order book reconstructs only within a
+    contiguous epoch, so a batch that straddled a gap would carry a hole no downstream check
+    could see.
+    """
+
+    by_epoch: dict[int, list[_Frame]] = {}
+    for frame in frames:
+        by_epoch.setdefault(frame.epoch, []).append(frame)
+    epochs: list[CapturedEpoch] = []
+    batches: list[tuple[_Frame, ...]] = []
+    for position, connection in enumerate(connections):
+        members = tuple(by_epoch.get(connection.epoch, ()))
+        epochs.append(
+            CapturedEpoch(
+                epoch=connection.epoch,
+                boundary=_boundary(config, connection, first=position == 0),
+                event_count=len(members),
+                first_event_id=members[0].event_id if members else None,
+                last_event_id=members[-1].event_id if members else None,
+                opened_at=connection.opened_at,
+                closed_at=connection.closed_at,
+            )
+        )
+        current: list[_Frame] = []
+        size = 0
+        opened = None if not members else _moment(members[0].received_at, "recording.received_at")
+        for frame in members:
+            arrived = _moment(frame.received_at, "recording.received_at")
+            rotate = bool(current) and (
+                len(current) >= config.max_batch_events
+                or size + len(frame.line) > config.max_batch_bytes
+                or (arrived - opened).total_seconds() > config.max_batch_seconds
+            )
+            if rotate:
+                batches.append(tuple(current))
+                current = []
+                size = 0
+                opened = arrived
+            current.append(frame)
+            size += len(frame.line)
+        if current:
+            batches.append(tuple(current))
+    if len(batches) > MAX_BATCHES:
+        raise SourceContractError(
+            "STREAM_CAPTURE",
+            "capture.batches",
+            f"one capture holds at most {MAX_BATCHES} sealed batches",
+        )
+    for group in batches:
+        if len(group) > MAX_BATCH_EVENTS:
+            raise SourceContractError(
+                "STREAM_EVENT_LIMIT",
+                "capture.batches",
+                "a sealed batch exceeds the adapter's own event bound",
+            )
+        if sum(len(frame.line) for frame in group) > config.max_batch_bytes:
+            raise SourceContractError(
+                "STREAM_CAPTURE_LIMIT",
+                "capture.batches",
+                "one recorded message is larger than this connector's whole batch bound",
+            )
+    return tuple(epochs), tuple(batches)
+
+
+def _boundary(config: StreamConnectorConfig, connection: _Connection, *, first: bool) -> str:
+    """Say what the boundary before one connection left behind.
+
+    The first connection of a capture opens it and has no boundary before it.  After that, a
+    hole is closed only when the venue's own repair rule actually ran: for a venue that re-sends
+    full state on subscribe, that means this connection really did open with a snapshot.  A
+    connection that admitted nothing never re-sent one, so its boundary is a recorded gap --
+    which is the honest answer and the reason the gap count is not decorative.
+    """
+
+    if first:
+        return "opening"
+    if config.gap_repair == "snapshot_on_subscribe" and connection.opened_with_snapshot:
+        return "repaired_by_snapshot"
+    return "recorded_gap"
+
+
+def _event_id(
+    config: StreamConnectorConfig,
+    message: dict[str, Any],
+    *,
+    epoch: int,
+    sequence: int,
+    where: str,
+) -> str:
+    """Assign one event its identity under the connector's declared rule."""
+
+    if config.event_id_rule == "derived":
+        return _position(epoch, sequence)
+    field = config.provider_event_id_field
+    assert field is not None  # the configuration contract pairs the rule with the field
+    value = message.get(field)
+    if isinstance(value, int) and not isinstance(value, bool):
+        value = str(value)
+    if not isinstance(value, str) or EVENT_ID_GRAMMAR.fullmatch(value) is None:
+        raise SourceContractError(
+            "STREAM_EVENT_ID",
+            f"{where}.message.{field}",
+            "the venue's own event identifier is missing or is not a usable name",
+        )
+    return value
+
+
+def _position(epoch: int, sequence: int) -> str:
+    """The Recorder-assigned ``{epoch}:{counter}`` position, ordered as text.
+
+    Zero padding is what makes text order and number order the same thing, which is what lets a
+    bookmark be compared without knowing how to take it apart.
+    """
+
+    return f"e{epoch:08d}:{sequence:012d}"
+
+
+def _event_time(config: StreamConnectorConfig, message: dict[str, Any], *, where: str) -> str:
+    """Read the event-time field and check it against its declared interpretation."""
+
+    value = message.get(config.event_time_field)
+    if isinstance(value, int) and not isinstance(value, bool):
+        value = str(value)
+    if not isinstance(value, str) or not 1 <= len(value) <= 64:
+        raise SourceContractError(
+            "STREAM_EVENT_TIME",
+            f"{where}.message.{config.event_time_field}",
+            "must carry the event time the connector declares",
+        )
+    if EVENT_TIME_KINDS[config.event_time_kind].fullmatch(value) is None:
+        raise SourceContractError(
+            "STREAM_EVENT_TIME",
+            f"{where}.message.{config.event_time_field}",
+            f"does not read as {config.event_time_kind}",
+        )
+    return value
+
+
+def _read_epochs(value: Any) -> tuple[CapturedEpoch, ...]:
+    if not isinstance(value, list) or not 1 <= len(value) <= MAX_EPOCHS:
+        raise SourceContractError("STREAM_CAPTURE", "capture.epochs", "must be a bounded list")
+    epochs: list[CapturedEpoch] = []
+    previous_closed: datetime | None = None
+    for index, item in enumerate(value, start=1):
+        _exact_keys(
+            item,
+            {
+                "epoch",
+                "boundary",
+                "event_count",
+                "first_event_id",
+                "last_event_id",
+                "opened_at",
+                "closed_at",
+            },
+            "capture.epochs",
+        )
+        if item["epoch"] != index or item["boundary"] not in GAP_BOUNDARIES:
+            raise SourceContractError(
+                "STREAM_CAPTURE",
+                "capture.epochs",
+                "connections must be numbered from one and carry a known boundary",
+            )
+        if (index == 1) != (item["boundary"] == "opening"):
+            raise SourceContractError(
+                "STREAM_CAPTURE",
+                "capture.epochs",
+                "only the first connection of a capture opens without a boundary before it",
+            )
+        if (
+            type(item["event_count"]) is not int
+            or not 0 <= item["event_count"] <= MAX_RECORDED_FRAMES
+        ):
+            raise SourceContractError(
+                "STREAM_CAPTURE",
+                "capture.epochs.event_count",
+                "each connection must record how many events it carried",
+            )
+        # A connection that admitted nothing has no first or last event, and one that admitted
+        # something has both.  Anything else is a record describing a connection that cannot
+        # exist.
+        named = [item["first_event_id"], item["last_event_id"]]
+        if item["event_count"] == 0:
+            if named != [None, None]:
+                raise SourceContractError(
+                    "STREAM_CAPTURE",
+                    "capture.epochs.first_event_id",
+                    "a connection that carried no event cannot name one",
+                )
+        else:
+            for name in ("first_event_id", "last_event_id"):
+                _event_name(item[name], f"capture.epochs.{name}")
+            if item["first_event_id"] > item["last_event_id"]:
+                raise SourceContractError(
+                    "STREAM_CAPTURE",
+                    "capture.epochs.last_event_id",
+                    "a connection cannot end at an event earlier than the one it began at",
+                )
+        opened = _moment(item["opened_at"], "capture.epochs.opened_at")
+        closed = _moment(item["closed_at"], "capture.epochs.closed_at")
+        if closed < opened:
+            raise SourceContractError(
+                "STREAM_CAPTURE",
+                "capture.epochs.closed_at",
+                "a connection cannot close before it opened",
+            )
+        if previous_closed is not None and opened < previous_closed:
+            raise SourceContractError(
+                "STREAM_CAPTURE",
+                "capture.epochs.opened_at",
+                "connections must not overlap in time",
+            )
+        previous_closed = closed
+        epochs.append(
+            CapturedEpoch(
+                epoch=item["epoch"],
+                boundary=item["boundary"],
+                event_count=item["event_count"],
+                first_event_id=item["first_event_id"],
+                last_event_id=item["last_event_id"],
+                opened_at=item["opened_at"],
+                closed_at=item["closed_at"],
+            )
+        )
+    return tuple(epochs)
+
+
+def _read_batches(value: Any, *, config: StreamConnectorConfig) -> tuple[CapturedBatch, ...]:
+    if not isinstance(value, list) or not 1 <= len(value) <= MAX_BATCHES:
+        raise SourceContractError("STREAM_CAPTURE", "capture.batches", "must be a bounded list")
+    batches: list[CapturedBatch] = []
+    previous: str | None = None
+    previous_epoch = 0
+    seen: set[str] = set()
+    for index, item in enumerate(value, start=1):
+        _exact_keys(
+            item,
+            {
+                "batch_index",
+                "epoch",
+                "storage_name",
+                "content_sha256",
+                "size_bytes",
+                "previous_bookmark",
+                "next_bookmark",
+                "event_ids",
+                "first_event_time",
+                "last_event_time",
+                "first_received_at",
+                "last_received_at",
+            },
+            "capture.batches",
+        )
+        if item["batch_index"] != index:
+            raise SourceContractError(
+                "STREAM_CAPTURE",
+                "capture.batches",
+                "sealed batches must be numbered from one in order",
+            )
+        if (
+            type(item["epoch"]) is not int
+            or not 1 <= item["epoch"] <= MAX_EPOCHS
+            or item["epoch"] < previous_epoch
+        ):
+            raise SourceContractError(
+                "STREAM_CAPTURE",
+                "capture.batches.epoch",
+                "each sealed batch belongs to one connection, in order",
+            )
+        previous_epoch = item["epoch"]
+        if (
+            not isinstance(item["storage_name"], str)
+            or _STORAGE_NAME.fullmatch(item["storage_name"]) is None
+        ):
+            raise SourceContractError(
+                "STREAM_CAPTURE",
+                "capture.batches.storage_name",
+                "must be the digest-addressed sealed batch name",
+            )
+        if item["storage_name"] != f"{item['content_sha256']}.{config.data_format}":
+            raise SourceContractError(
+                "STREAM_CAPTURE",
+                "capture.batches.storage_name",
+                "must be the exact digest-addressed name of its own bytes",
+            )
+        if (
+            type(item["size_bytes"]) is not int
+            or not 1 <= item["size_bytes"] <= config.max_batch_bytes
+        ):
+            raise SourceContractError(
+                "STREAM_CAPTURE",
+                "capture.batches.size_bytes",
+                "is outside the batch bound this connector declares",
+            )
+        if item["previous_bookmark"] != previous:
+            raise SourceContractError(
+                "STREAM_CAPTURE",
+                "capture.batches.previous_bookmark",
+                "sealed batches must form one unbroken chain of bookmarks",
+            )
+        if index == 1 and item["previous_bookmark"] is not None:
+            raise SourceContractError(
+                "STREAM_CAPTURE",
+                "capture.batches.previous_bookmark",
+                "the first sealed batch of a capture follows no bookmark",
+            )
+        identities = _read_event_ids(item["event_ids"], config=config)
+        if seen & set(identities):
+            raise SourceContractError(
+                "STREAM_CAPTURE",
+                "capture.batches.event_ids",
+                "one event name appears in more than one sealed batch",
+            )
+        seen |= set(identities)
+        marker = _BOOKMARK.fullmatch(item["next_bookmark"] or "")
+        if marker is None or int(marker.group(1)) != item["epoch"]:
+            raise SourceContractError(
+                "STREAM_CAPTURE",
+                "capture.batches.next_bookmark",
+                "a batch's bookmark is its own position in its own connection",
+            )
+        # The bookmark is what a build commits against and then asks to continue from, so it has
+        # to move one way.  A record whose batches walked backwards would rewind a source that
+        # has already been built, without anything downstream being able to tell.
+        if previous is not None and item["next_bookmark"] <= previous:
+            raise SourceContractError(
+                "STREAM_CAPTURE",
+                "capture.batches.next_bookmark",
+                "each sealed batch must advance the bookmark, never move it back",
+            )
+        for name in ("first_event_time", "last_event_time"):
+            _declared_event_time(item[name], config=config, path=f"capture.batches.{name}")
+        first = _moment(item["first_received_at"], "capture.batches.first_received_at")
+        if _moment(item["last_received_at"], "capture.batches.last_received_at") < first:
+            raise SourceContractError(
+                "STREAM_CAPTURE",
+                "capture.batches.last_received_at",
+                "a sealed batch cannot end before it began",
+            )
+        batches.append(
+            CapturedBatch(
+                batch_index=item["batch_index"],
+                epoch=item["epoch"],
+                storage_name=item["storage_name"],
+                content_sha256=item["content_sha256"],
+                size_bytes=item["size_bytes"],
+                previous_bookmark=item["previous_bookmark"],
+                next_bookmark=item["next_bookmark"],
+                event_ids=identities,
+                first_event_time=item["first_event_time"],
+                last_event_time=item["last_event_time"],
+                first_received_at=item["first_received_at"],
+                last_received_at=item["last_received_at"],
+            )
+        )
+        previous = item["next_bookmark"]
+    return tuple(batches)
+
+
+def _read_event_ids(value: Any, *, config: StreamConnectorConfig) -> tuple[str, ...]:
+    """Check one batch's event names are bounded, distinct, well formed, and in order."""
+
+    if not isinstance(value, list) or not 1 <= len(value) <= config.max_batch_events:
+        raise SourceContractError(
+            "STREAM_CAPTURE",
+            "capture.batches.event_ids",
+            "must be a bounded non-empty list of event names",
+        )
+    for item in value:
+        _event_name(item, "capture.batches.event_ids")
+    if len(set(value)) != len(value):
+        raise SourceContractError(
+            "STREAM_CAPTURE",
+            "capture.batches.event_ids",
+            "must name each event once",
+        )
+    return tuple(value)
+
+
+def _event_name(value: Any, path: str) -> str:
+    if not isinstance(value, str) or EVENT_ID_GRAMMAR.fullmatch(value) is None:
+        raise SourceContractError(
+            "STREAM_EVENT_ID",
+            path,
+            "must be one event name in the grammar the ledger admits",
+        )
+    return value
+
+
+def _declared_event_time(value: Any, *, config: StreamConnectorConfig, path: str) -> str:
+    if (
+        not isinstance(value, str)
+        or not 1 <= len(value) <= 64
+        or EVENT_TIME_KINDS[config.event_time_kind].fullmatch(value) is None
+    ):
+        raise SourceContractError(
+            "STREAM_EVENT_TIME",
+            path,
+            f"does not read as {config.event_time_kind}",
+        )
+    return value
+
+
+def _require_consistent_capture(
+    epochs: tuple[CapturedEpoch, ...],
+    batches: tuple[CapturedBatch, ...],
+    *,
+    recorded_through: str,
+) -> None:
+    """Check the two halves of a capture record describe the same capture.
+
+    Each half is well formed on its own by the time this runs.  What is left is whether they
+    agree: whether every batch belongs to a connection the record lists, whether each
+    connection's stated event count is the number of events its batches actually hold, whether
+    the connection's own first and last event names are the ones its batches begin and end with,
+    and whether the capture's stated end is where its last batch actually stopped.
+    """
+
+    numbers = {epoch.epoch for epoch in epochs}
+    unknown = sorted({batch.epoch for batch in batches} - numbers)
+    if unknown:
+        raise SourceContractError(
+            "STREAM_CAPTURE",
+            "capture.batches.epoch",
+            f"sealed batches name connections this capture does not record: {unknown[:10]}",
+        )
+    for epoch in epochs:
+        members = [batch for batch in batches if batch.epoch == epoch.epoch]
+        held = [identity for batch in members for identity in batch.event_ids]
+        if len(held) != epoch.event_count:
+            raise SourceContractError(
+                "STREAM_CAPTURE",
+                "capture.epochs.event_count",
+                "a connection's event count is not the number its sealed batches hold",
+            )
+        if held and (held[0] != epoch.first_event_id or held[-1] != epoch.last_event_id):
+            raise SourceContractError(
+                "STREAM_CAPTURE",
+                "capture.epochs.first_event_id",
+                "a connection does not begin and end at the events its batches do",
+            )
+    if batches[-1].last_received_at != recorded_through:
+        raise SourceContractError(
+            "STREAM_CAPTURE",
+            "capture.recorded_through",
+            "a capture ends where its last sealed batch ends",
+        )
+
+
+def _write_manifest(stream_root: Path, manifest: CaptureManifest) -> None:
+    """Replace the capture manifest atomically beneath a descriptor-bound root."""
+
+    payload = canonical_json_bytes(manifest.to_dict())
+    if len(payload) > MAX_MANIFEST_BYTES:
+        raise SourceContractError(
+            "STREAM_CAPTURE_LIMIT",
+            "capture",
+            f"the capture record exceeds its {MAX_MANIFEST_BYTES}-byte budget",
+        )
+    try:
+        root_fd = os.open(
+            stream_root,
+            os.O_RDONLY
+            | getattr(os, "O_DIRECTORY", 0)
+            | getattr(os, "O_NOFOLLOW", 0)
+            | getattr(os, "O_CLOEXEC", 0),
+        )
+    except OSError:
+        raise SourceContractError(
+            "STREAM_CAPTURE_ROOT",
+            "capture",
+            f"{stream_root.name} is not a plain directory this capture may be written into",
+        ) from None
+    temporary = f".{CAPTURE_MANIFEST_NAME}.{os.getpid()}.tmp"
+    try:
+        try:
+            os.unlink(temporary, dir_fd=root_fd)
+        except FileNotFoundError:
+            pass
+        descriptor = os.open(
+            temporary,
+            os.O_WRONLY | os.O_CREAT | os.O_EXCL | getattr(os, "O_NOFOLLOW", 0),
+            0o600,
+            dir_fd=root_fd,
+        )
+        try:
+            view = memoryview(payload)
+            written = 0
+            while written < len(view):
+                count = os.write(descriptor, view[written:])
+                if count <= 0:
+                    raise SourceContractError(
+                        "STREAM_CAPTURE_WRITE",
+                        "capture",
+                        "write made no progress",
+                    )
+                written += count
+            os.fsync(descriptor)
+        finally:
+            os.close(descriptor)
+        try:
+            os.replace(temporary, CAPTURE_MANIFEST_NAME, src_dir_fd=root_fd, dst_dir_fd=root_fd)
+            os.fsync(root_fd)
+        finally:
+            try:
+                os.unlink(temporary, dir_fd=root_fd)
+            except FileNotFoundError:
+                pass
+    except OSError:
+        raise SourceContractError(
+            "STREAM_CAPTURE_WRITE",
+            "capture",
+            "the capture record could not be written into its own directory",
+        ) from None
+    finally:
+        os.close(root_fd)
+
+
+def _capture_component(stream_id: Any) -> str:
+    """Check a stream name is one strict path component before it addresses a directory."""
+
+    if not isinstance(stream_id, str) or re.fullmatch(r"[a-z][a-z0-9-]{0,63}", stream_id) is None:
+        raise SourceContractError(
+            "STREAM_CAPTURE_ROOT",
+            "request.query.stream_id",
+            "must be one plain lowercase name, so it can address exactly one directory",
+        )
+    return stream_id
+
+
+def _require_plain_directory(path: Path) -> None:
+    """Make one directory if it is missing, then check it is a directory and not a link to one.
+
+    ``Path.mkdir(exist_ok=True)`` is satisfied by a pre-existing symlink to a directory, because
+    the existence test follows the link.  So making the directory proves nothing on its own, and
+    the ``lstat`` below is the check: a planted link must not get to decide where a capture is
+    written.  Everything this module opens afterwards uses ``O_NOFOLLOW``, so this runs once, up
+    front, and a refusal leaves nothing written.
+    """
+
+    try:
+        path.mkdir(mode=0o700, parents=True, exist_ok=True)
+    except OSError:
+        raise SourceContractError(
+            "STREAM_CAPTURE_ROOT",
+            "capture",
+            f"{path.name} could not be created as a plain directory",
+        ) from None
+    try:
+        info = os.lstat(path)
+    except OSError:
+        raise SourceContractError(
+            "STREAM_CAPTURE_ROOT",
+            "capture",
+            f"{path.name} could not be inspected",
+        ) from None
+    if not stat.S_ISDIR(info.st_mode):
+        raise SourceContractError(
+            "STREAM_CAPTURE_ROOT",
+            "capture",
+            f"{path.name} must be a plain directory, not a link to one",
+        )
+
+
+def _read_capture_file(root: Path, name: str, maximum: int) -> bytes:
+    """Read one bounded regular file beneath a root without following any link.
+
+    The controls are the ones ``adapters._read_confined_file`` already applies to a source file,
+    for the same reasons and in the same order: open non-blocking so a planted FIFO cannot hold
+    the command open forever, require one regular file with one link so a device or a hardlink
+    farm is refused, and compare the full descriptor and path identity before and after the read
+    so a file swapped underneath the read is caught rather than returned.
+    """
+
+    directory_flags = (
+        os.O_RDONLY
+        | getattr(os, "O_DIRECTORY", 0)
+        | getattr(os, "O_NOFOLLOW", 0)
+        | getattr(os, "O_CLOEXEC", 0)
+    )
+    try:
+        root_fd = os.open(root, directory_flags)
+    except OSError:
+        raise SourceContractError(
+            "STREAM_CAPTURE_ROOT",
+            "capture",
+            f"no readable capture directory at {root.name}",
+        ) from None
+    try:
+        try:
+            descriptor = os.open(
+                name,
+                os.O_RDONLY
+                | getattr(os, "O_NOFOLLOW", 0)
+                | getattr(os, "O_NONBLOCK", 0)
+                | getattr(os, "O_CLOEXEC", 0),
+                dir_fd=root_fd,
+            )
+        except OSError:
+            raise SourceContractError(
+                "STREAM_CAPTURE_ROOT",
+                "capture",
+                f"{name} is missing or is not a plain readable file",
+            ) from None
+        try:
+            before = os.fstat(descriptor)
+            if not stat.S_ISREG(before.st_mode) or before.st_nlink != 1:
+                raise SourceContractError(
+                    "STREAM_CAPTURE_ROOT",
+                    "capture",
+                    f"{name} must be one plain file with one name, not a link, a pipe, or a device",
+                )
+            if not 1 <= before.st_size <= maximum:
+                raise SourceContractError(
+                    "STREAM_CAPTURE_LIMIT",
+                    "capture",
+                    f"{name} is empty or over its {maximum}-byte budget",
+                )
+            chunks: list[bytes] = []
+            total = 0
+            while total <= maximum:
+                chunk = os.read(descriptor, min(64 * 1024, maximum + 1 - total))
+                if not chunk:
+                    break
+                chunks.append(chunk)
+                total += len(chunk)
+            after = os.fstat(descriptor)
+            named = os.stat(name, dir_fd=root_fd, follow_symlinks=False)
+            if (
+                total != before.st_size
+                or _capture_stat_signature(before) != _capture_stat_signature(after)
+                or _capture_stat_signature(before) != _capture_stat_signature(named)
+            ):
+                raise SourceContractError(
+                    "STREAM_CAPTURE_MUTATED",
+                    "capture",
+                    f"{name} changed while it was being read",
+                )
+            return b"".join(chunks)
+        finally:
+            os.close(descriptor)
+    except OSError:
+        raise SourceContractError(
+            "STREAM_CAPTURE_ROOT",
+            "capture",
+            f"{name} could not be read as one plain bounded file",
+        ) from None
+    finally:
+        os.close(root_fd)
+
+
+def _capture_stat_signature(info: os.stat_result) -> tuple[int, ...]:
+    """Bind the complete regular-file state one capture read is allowed to see."""
+
+    return (
+        info.st_dev,
+        info.st_ino,
+        info.st_uid,
+        info.st_gid,
+        info.st_mode,
+        info.st_nlink,
+        info.st_size,
+        info.st_mtime_ns,
+        info.st_ctime_ns,
+    )
+
+
+def _read_sealed_batch(root: Path, *, storage_name: str, expected_size: int) -> bytes:
+    if _STORAGE_NAME.fullmatch(storage_name) is None:
+        raise SourceContractError(
+            "STREAM_CAPTURE",
+            "capture.batches.storage_name",
+            "must be the digest-addressed sealed batch name",
+        )
+    content = _read_capture_file(root, storage_name, MAX_MANIFEST_BYTES)
+    if len(content) != expected_size:
+        raise SourceContractError(
+            "STREAM_CAPTURE_DIGEST",
+            "capture.batches.size_bytes",
+            "sealed batch is not the size the capture recorded",
+        )
+    return content
+
+
+def _exact_keys(value: Any, keys: frozenset[str] | set[str], path: str) -> None:
+    if not isinstance(value, dict) or set(value) != set(keys):
+        raise SourceContractError(
+            "STREAM_CAPTURE",
+            path,
+            f"must be an object holding exactly {sorted(keys)}",
+        )
+
+
+def _moment(value: Any, path: str) -> datetime:
+    """Check one canonical UTC time and return it, so spans can be measured from it."""
+
+    if not isinstance(value, str) or _TIMESTAMP.fullmatch(value) is None:
+        raise SourceContractError(
+            "STREAM_CAPTURE_TIME",
+            path,
+            "must be a canonical RFC 3339 UTC time",
+        )
+    return datetime.fromisoformat(value[:-1] + "+00:00")