techtree 0.1.0__py3-none-any.whl

techtree/runs/child_registry.py

@@ -0,0 +1,228 @@
+"""Which evaluation children a run currently owns. Spec section 6.16.
+
+Two variants running side by side turn a single question — "stop this run" —
+into two answers, and neither of them is reachable from the run's journal. The
+journal records that a run was asked to stop; only the process that started the
+children knows which processes those are. This module is that knowledge, and it
+is deliberately the smallest thing that can hold it: an in-memory map from run
+identifier to the live children, guarded by a lock because the poller and a
+signal-driven wind-down touch it from different threads.
+
+Nothing here is scientific truth. A registry entry says a process exists, not
+that an experiment happened, and the registry is discarded when the worker
+exits. What survives the worker is one diagnostic file,
+``execution/children.json``, written once both children are up: if the worker
+dies without unwinding, that file is the only record of which process groups
+were left holding Docker containers, and an operator cleaning up by hand has
+nothing else to go on.
+
+The file is written after both children start rather than after each one,
+because a write between the two launches would land inside the interval the
+run is measuring as launch skew.
+"""
+
+from __future__ import annotations
+
+import threading
+from collections.abc import Sequence
+from dataclasses import dataclass
+from datetime import datetime
+from pathlib import Path
+from typing import Final, Protocol, runtime_checkable
+
+from techtree.canonical import to_json_value
+from techtree.fs import atomic_write_json, ensure_private_directory
+from techtree.models.base import Digest, JsonValue
+from techtree.models.campaign import VariantSchedule
+from techtree.verifiers.models import ChildProcessOutcome, VariantName
+
+__all__ = [
+    "CHILDREN_FILENAME",
+    "CHILDREN_RECORD_SCHEMA_VERSION",
+    "EXECUTION_DIRECTORY",
+    "ChildRegistry",
+    "EvaluationChild",
+    "LaunchedChild",
+    "children_record_path",
+    "execution_dir",
+    "write_children_record",
+]
+
+#: Where a run keeps what its execution did, as opposed to what it was given.
+#: Spec section 6.19.
+EXECUTION_DIRECTORY: Final = "execution"
+
+#: The diagnostic record of which processes a run started. Spec sections 6.16
+#: and 6.19.
+CHILDREN_FILENAME: Final = "children.json"
+
+#: A local operational document, not a protocol object. It is named and
+#: versioned anyway so that a file found after a crash says what it is.
+CHILDREN_RECORD_SCHEMA_VERSION: Final = "techtree.run-children.v1"
+
+#: Variants always appear in comparison order, never in start order, so that a
+#: registry listing reads the same way whichever child happened to be quicker.
+_VARIANT_ORDER: Final[tuple[VariantName, ...]] = (
+    VariantName.BASELINE,
+    VariantName.CANDIDATE,
+)
+
+
+@runtime_checkable
+class EvaluationChild(Protocol):
+    """The part of one evaluation child process a run's control path uses.
+
+    :class:`~techtree.verifiers.child.VerifiersChild` is the implementation.
+    Stating the surface as a protocol is what lets the scheduler's own
+    behaviour — the start barrier, sibling termination, the launch-skew
+    measurement — be tested without a subprocess, a container, or a provider.
+    """
+
+    @property
+    def variant(self) -> VariantName:
+        """Which side of the comparison this child is running."""
+        ...
+
+    @property
+    def pid(self) -> int | None:
+        """The child's process id once it has started."""
+        ...
+
+    @property
+    def argv_digest(self) -> Digest:
+        """The digest of this child's invocation."""
+        ...
+
+    def start(self) -> int:
+        """Start the child and return its pid."""
+        ...
+
+    def poll(self) -> int | None:
+        """Return the exit code, or ``None`` while the child is still running."""
+        ...
+
+    def terminate(self, grace_seconds: float = ...) -> None:
+        """Stop the child's process group, allowing runtime teardown first."""
+        ...
+
+    def outcome(self) -> ChildProcessOutcome:
+        """Describe the finished child."""
+        ...
+
+
+@dataclass(frozen=True)
+class LaunchedChild:
+    """One child as it was at the moment the run started it.
+
+    The start time is the parent's observation of the launch rather than the
+    child's own, because it is taken the instant ``start`` returns and the
+    child's is only readable once the process has exited. The two bracket each
+    other within the cost of a ``fork``.
+    """
+
+    variant: VariantName
+    pid: int | None
+    argv_digest: Digest
+    started_at: datetime
+
+
+class ChildRegistry:
+    """The live evaluation children of every run this process is executing.
+
+    Registration is by variant, so a run holds at most one child per side and
+    re-registering a variant replaces it rather than accumulating a second
+    entry that nothing would ever terminate.
+    """
+
+    def __init__(self) -> None:
+        self._lock = threading.Lock()
+        self._children: dict[str, dict[VariantName, EvaluationChild]] = {}
+
+    def register(self, run_id: str, child: EvaluationChild) -> None:
+        """Record that this run owns one child process."""
+        with self._lock:
+            self._children.setdefault(run_id, {})[child.variant] = child
+
+    def children(self, run_id: str) -> tuple[EvaluationChild, ...]:
+        """Return this run's live children, in comparison order."""
+        with self._lock:
+            registered = dict(self._children.get(run_id, {}))
+        return tuple(
+            registered[variant] for variant in _VARIANT_ORDER if variant in registered
+        )
+
+    def terminate_all(self, run_id: str, grace_seconds: float) -> None:
+        """Stop every child this run owns, then forget them.
+
+        Each child is given the same grace period rather than sharing one, so
+        the second variant's containers get as long to tear down as the first
+        variant's did. Every child is attempted even if an earlier one raised:
+        a run that failed to stop one process group must still stop the other.
+        """
+        failures: list[BaseException] = []
+        for child in self.children(run_id):
+            try:
+                child.terminate(grace_seconds)
+            except BaseException as error:
+                failures.append(error)
+            finally:
+                self.unregister(run_id, child.variant)
+        if failures:
+            raise failures[0]
+
+    def unregister(self, run_id: str, variant: VariantName) -> None:
+        """Forget one child, and the run itself once it owns none."""
+        with self._lock:
+            registered = self._children.get(run_id)
+            if registered is None:
+                return
+            registered.pop(variant, None)
+            if not registered:
+                del self._children[run_id]
+
+
+def execution_dir(run_root: Path) -> Path:
+    """Return where one run records what its execution did."""
+    return run_root / EXECUTION_DIRECTORY
+
+
+def children_record_path(run_root: Path) -> Path:
+    """Return where one run's diagnostic child record lives."""
+    return execution_dir(run_root) / CHILDREN_FILENAME
+
+
+def write_children_record(
+    *,
+    run_root: Path,
+    run_id: str,
+    schedule: VariantSchedule,
+    children: Sequence[LaunchedChild],
+    launch_skew_seconds: float | None,
+) -> Path:
+    """Write the diagnostic record of what this run started.
+
+    ``launch_skew_seconds`` is the gap between the two launches under a
+    parallel schedule and ``None`` under a sequential one, where the second
+    child does not exist yet and a gap would be a measurement of the first
+    variant's duration rather than of a launch.
+    """
+    path = children_record_path(run_root)
+    ensure_private_directory(path.parent)
+    rows: list[JsonValue] = [
+        {
+            "variant": child.variant.value,
+            "pid": child.pid,
+            "argv_digest": child.argv_digest,
+            "started_at": to_json_value(child.started_at),
+        }
+        for child in children
+    ]
+    document: dict[str, JsonValue] = {
+        "schema_version": CHILDREN_RECORD_SCHEMA_VERSION,
+        "run_id": run_id,
+        "schedule": schedule.value,
+        "launch_skew_seconds": launch_skew_seconds,
+        "children": rows,
+    }
+    atomic_write_json(path, document)
+    return path

techtree/runs/events.py

@@ -0,0 +1,478 @@
+"""The append-only run event log and its vocabulary. Spec sections 18.1, 7.4.
+
+One run event is one line of canonical JSON. The log is only ever appended to,
+never rewritten, which is what lets a reader that arrives halfway through a run
+reconstruct everything that has happened without coordinating with the writer.
+
+Three properties are deliberate.
+
+*Canonical bytes.* Lines are serialized with
+:func:`techtree.canonical.canonical_json_bytes`, so the same events always
+produce the same file and :func:`event_digest` is a meaningful identity for a
+run's history rather than an accident of dictionary ordering.
+
+*Durability.* Each append is a single write to a file opened with ``O_APPEND``
+followed by an ``fsync``. A crash can therefore lose a whole trailing event, but
+it cannot interleave one event's bytes with another's.
+
+*Discontinuity is fatal.* Sequence numbers start at zero and increase by exactly
+one. A log that skips is a log that lost something, and a state projected from
+it would be quietly wrong; :func:`read_events` refuses it instead. That check is
+also what catches a truncated final line, because a partly written event fails
+to parse before its sequence is ever considered.
+
+The kinds a run may record are a closed set. ``RunEvent.kind`` is a string in
+the frozen protocol model, but thirteen names exhaust what a local run can say
+about itself, and each name fixes the phases it may appear between and the
+details it carries. :func:`validate_event_kind` holds every reader to that, so a
+log cannot contain an event whose name and position disagree.
+"""
+
+from __future__ import annotations
+
+import os
+from pathlib import Path
+from typing import Final
+
+from pydantic import ValidationError as PydanticValidationError
+
+from techtree.canonical import canonical_json_bytes, sha256_digest_bytes
+from techtree.errors import NotFoundError, ValidationError
+from techtree.fs import fsync_directory
+from techtree.models.base import Digest, JsonValue
+from techtree.models.run import RunEvent, RunPhase
+
+__all__ = [
+    "CANCEL_REQUESTED",
+    "DETAIL_ACTOR",
+    "DETAIL_APPROVED_AT",
+    "DETAIL_COMPLETED",
+    "DETAIL_CURRENT",
+    "DETAIL_DRAFT_DIGEST",
+    "DETAIL_ERROR",
+    "DETAIL_ERRORED",
+    "DETAIL_LABEL",
+    "DETAIL_REQUESTED_BY",
+    "DETAIL_REQUEST_DIGEST",
+    "DETAIL_RESULT_DIGEST",
+    "DETAIL_RUNNING",
+    "DETAIL_STATE",
+    "DETAIL_TOTAL",
+    "DETAIL_VARIANT",
+    "DETAIL_WORKER_PID",
+    "EVENT_KINDS",
+    "PHASE_ENTERED",
+    "PROGRESS_UPDATED",
+    "RESULT_WRITTEN",
+    "RUN_APPROVED",
+    "RUN_CANCELLED",
+    "RUN_COMPLETED",
+    "RUN_CREATED",
+    "RUN_FAILED",
+    "SAME_PHASE_EVENT_KINDS",
+    "VARIANT_COMPLETED",
+    "VARIANT_EVENT_KINDS",
+    "VARIANT_PROGRESS",
+    "VARIANT_STARTED",
+    "WORKER_STARTED",
+    "append_event",
+    "event_digest",
+    "next_sequence",
+    "read_events",
+    "validate_event_kind",
+]
+
+_LINE_SEPARATOR: Final = b"\n"
+#: Owner read and write only, matching every other file Techtree writes.
+_FILE_MODE: Final = 0o600
+
+
+# ---------------------------------------------------------------------------
+# Event kinds
+#
+# Twelve names, and no thirteenth. A kind is not a free-text annotation: it
+# fixes what the event means, which phases it may sit between, and which details
+# it must carry, so a reader can interpret an event without guessing.
+# ---------------------------------------------------------------------------
+
+#: The run exists and its request is fixed. Always sequence zero.
+RUN_CREATED: Final = "run.created"
+#: A person read the review of what this run would do and approved it. Decisions
+#: document 0019 section 2: an audit fact recorded beside everything else that
+#: happened to the run, not a cryptographic acceptance artifact.
+RUN_APPROVED: Final = "run.approved"
+#: A detached worker took the run on and announced its process id.
+WORKER_STARTED: Final = "worker.started"
+#: The run moved from one phase to another.
+PHASE_ENTERED: Final = "phase.entered"
+#: How far through the current phase the worker is.
+PROGRESS_UPDATED: Final = "progress.updated"
+#: Someone asked the run to stop.
+CANCEL_REQUESTED: Final = "cancel.requested"
+#: The run stopped because something went wrong.
+RUN_FAILED: Final = "run.failed"
+#: The run stopped because it was asked to.
+RUN_CANCELLED: Final = "run.cancelled"
+#: The report was persisted and its digest recorded.
+RESULT_WRITTEN: Final = "result.written"
+#: The run finished the normal path.
+RUN_COMPLETED: Final = "run.completed"
+#: One side of a concurrent comparison began. Spec section 3.3.
+VARIANT_STARTED: Final = "variant.started"
+#: How far one side of a concurrent comparison has got.
+VARIANT_PROGRESS: Final = "variant.progress"
+#: One side of a concurrent comparison stopped, whichever way it stopped.
+VARIANT_COMPLETED: Final = "variant.completed"
+
+#: The three kinds that speak for one variant rather than for the run. They
+#: exist only while both variants are in flight, which is one phase and no
+#: other.
+VARIANT_EVENT_KINDS: Final[frozenset[str]] = frozenset(
+    {VARIANT_STARTED, VARIANT_PROGRESS, VARIANT_COMPLETED}
+)
+
+#: Every kind a run may record. Anything else is a corrupt log.
+EVENT_KINDS: Final[frozenset[str]] = frozenset(
+    {
+        RUN_CREATED,
+        RUN_APPROVED,
+        WORKER_STARTED,
+        PHASE_ENTERED,
+        PROGRESS_UPDATED,
+        CANCEL_REQUESTED,
+        RUN_FAILED,
+        RUN_CANCELLED,
+        RESULT_WRITTEN,
+        RUN_COMPLETED,
+        *VARIANT_EVENT_KINDS,
+    }
+)
+
+#: The kinds that report something true of a run without moving it on. Every
+#: other kind changes the phase. Spec section 7.6, extended by section 3.3.
+SAME_PHASE_EVENT_KINDS: Final[frozenset[str]] = frozenset(
+    {
+        RUN_APPROVED,
+        WORKER_STARTED,
+        PROGRESS_UPDATED,
+        RESULT_WRITTEN,
+        *VARIANT_EVENT_KINDS,
+    }
+)
+
+
+# ---------------------------------------------------------------------------
+# Detail keys
+#
+# ``RunEvent.details`` is free-form JSON so that a worker can record whatever a
+# human will want to read later. These keys are the exception: each is part of
+# the definition of the kind that carries it, and the projection interprets it.
+# ---------------------------------------------------------------------------
+
+#: The digest of the ``RunRequest`` this run executes.
+DETAIL_REQUEST_DIGEST: Final = "request_digest"
+#: The digest of the draft that was reviewed and approved.
+DETAIL_DRAFT_DIGEST: Final = "draft_digest"
+#: Who approved it: a person answering the prompt, or an operator who passed
+#: the flag that stands in for the answer.
+DETAIL_ACTOR: Final = "actor"
+#: When the approval was given.
+DETAIL_APPROVED_AT: Final = "approved_at"
+#: The process id of the detached worker executing this run.
+DETAIL_WORKER_PID: Final = "worker_pid"
+#: Position within the work the current phase describes.
+DETAIL_CURRENT: Final = "current"
+#: How much work the current phase amounts to.
+DETAIL_TOTAL: Final = "total"
+#: What the current phase is working through.
+DETAIL_LABEL: Final = "label"
+#: Who asked the run to stop.
+DETAIL_REQUESTED_BY: Final = "requested_by"
+#: A ``CliError`` object saying why the run failed.
+DETAIL_ERROR: Final = "error"
+#: The digest of the ``UpliftReport`` this run produced.
+DETAIL_RESULT_DIGEST: Final = "result_digest"
+#: Which side of a concurrent comparison a variant event speaks for.
+DETAIL_VARIANT: Final = "variant"
+#: Episodes of this variant that have finished.
+DETAIL_COMPLETED: Final = "completed"
+#: Episodes of this variant currently in flight.
+DETAIL_RUNNING: Final = "running"
+#: Episodes of this variant that failed.
+DETAIL_ERRORED: Final = "errored"
+#: Where this variant is in its own lifecycle.
+DETAIL_STATE: Final = "state"
+
+#: The details every variant event carries. They are the whole of
+#: :class:`~techtree.models.run.VariantProgress`, because a variant event that
+#: reported only part of it would leave the projection guessing at the rest.
+_VARIANT_DETAILS: Final[tuple[str, ...]] = (
+    DETAIL_VARIANT,
+    DETAIL_COMPLETED,
+    DETAIL_TOTAL,
+    DETAIL_RUNNING,
+    DETAIL_ERRORED,
+    DETAIL_STATE,
+)
+
+#: What each kind is defined to carry. A kind missing one of its own details
+#: cannot be interpreted, so it is refused rather than projected as a blank.
+_REQUIRED_DETAILS: Final[dict[str, tuple[str, ...]]] = {
+    RUN_CREATED: (DETAIL_REQUEST_DIGEST,),
+    RUN_APPROVED: (DETAIL_DRAFT_DIGEST, DETAIL_ACTOR, DETAIL_APPROVED_AT),
+    WORKER_STARTED: (DETAIL_WORKER_PID,),
+    PROGRESS_UPDATED: (DETAIL_CURRENT, DETAIL_TOTAL, DETAIL_LABEL),
+    CANCEL_REQUESTED: (DETAIL_REQUESTED_BY,),
+    RUN_FAILED: (DETAIL_ERROR,),
+    RESULT_WRITTEN: (DETAIL_RESULT_DIGEST,),
+    RUN_COMPLETED: (DETAIL_RESULT_DIGEST,),
+    VARIANT_STARTED: _VARIANT_DETAILS,
+    VARIANT_PROGRESS: _VARIANT_DETAILS,
+    VARIANT_COMPLETED: _VARIANT_DETAILS,
+}
+
+
+# ---------------------------------------------------------------------------
+# Kind and phase agreement
+# ---------------------------------------------------------------------------
+
+#: Four phases each belong to exactly one kind, in both directions: no other
+#: kind may enter the phase, and the kind may enter no other phase. Ending a run
+#: is too consequential to be recorded by a generic phase change.
+_EXCLUSIVE_PHASE_KINDS: Final[dict[RunPhase, str]] = {
+    RunPhase.CANCEL_REQUESTED: CANCEL_REQUESTED,
+    RunPhase.FAILED: RUN_FAILED,
+    RunPhase.CANCELLED: RUN_CANCELLED,
+    RunPhase.COMPLETED: RUN_COMPLETED,
+}
+
+#: The one phase each of these kinds may appear in. A worker announces itself
+#: before the run starts working; a result exists only while the report is
+#: being built.
+_ONLY_IN_PHASE: Final[dict[str, RunPhase]] = {
+    # Approval is given before anything is launched, so it can only ever be
+    # recorded against the phase a run exists in and has not yet left.
+    RUN_APPROVED: RunPhase.CREATED,
+    WORKER_STARTED: RunPhase.CREATED,
+    RESULT_WRITTEN: RunPhase.BUILDING_REPORT,
+    # A variant is a side of a concurrent comparison, and nothing is running
+    # two variants at once outside the one phase that says so.
+    **dict.fromkeys(VARIANT_EVENT_KINDS, RunPhase.RUNNING_VARIANTS),
+}
+
+#: The phase each of these kinds must have been reached from. Both are the last
+#: step of a path, and the step before it is not optional.
+_REQUIRED_PREVIOUS_PHASE: Final[dict[str, RunPhase]] = {
+    RUN_CANCELLED: RunPhase.CANCEL_REQUESTED,
+    RUN_COMPLETED: RunPhase.BUILDING_REPORT,
+}
+
+
+def validate_event_kind(event: RunEvent) -> None:
+    """Reject unknown kinds, kind and phase mismatches, and missing details."""
+    if event.kind not in EVENT_KINDS:
+        known: list[JsonValue] = [kind for kind in sorted(EVENT_KINDS)]
+        raise ValidationError(
+            f"{event.kind!r} is not a run event kind",
+            code="run_event_kind_invalid",
+            details={
+                "run_id": event.run_id,
+                "sequence": event.sequence,
+                "kind": event.kind,
+                "known": known,
+            },
+        )
+
+    _check_phases(event)
+    _check_required_details(event)
+
+
+def _check_phases(event: RunEvent) -> None:
+    """Refuse an event whose kind and phases describe different things."""
+    if event.kind == RUN_CREATED:
+        _check_created_event(event)
+    elif event.previous_phase is None:
+        raise _kind_mismatch(
+            event,
+            f"only {RUN_CREATED} comes from no earlier phase",
+        )
+
+    # The exclusive kinds own the *transition into* their phase. An event that
+    # stays where it is (a progress report landing just after cancellation was
+    # requested, for instance) is governed by the same-phase whitelist instead.
+    entering = event.previous_phase is not event.phase
+    for phase, kind in _EXCLUSIVE_PHASE_KINDS.items():
+        if entering and event.phase is phase and event.kind != kind:
+            raise _kind_mismatch(event, f"only {kind} enters {phase.value}")
+        if event.kind == kind and event.phase is not phase:
+            raise _kind_mismatch(event, f"{kind} enters {phase.value}")
+
+    required_phase = _ONLY_IN_PHASE.get(event.kind)
+    if required_phase is not None and event.phase is not required_phase:
+        raise _kind_mismatch(
+            event,
+            f"{event.kind} belongs to {required_phase.value}, "
+            f"not to {event.phase.value}",
+        )
+
+    required_previous = _REQUIRED_PREVIOUS_PHASE.get(event.kind)
+    if required_previous is not None and event.previous_phase is not required_previous:
+        raise _kind_mismatch(
+            event,
+            f"{event.kind} follows {required_previous.value}",
+        )
+
+    # The same-phase kinds report something true of a run while it stays where
+    # it is; every other kind exists to move it. Neither may pretend to be the
+    # other, so the two are checked as one equivalence.
+    same_phase = event.phase is event.previous_phase
+    if same_phase and event.kind not in SAME_PHASE_EVENT_KINDS:
+        raise _kind_mismatch(
+            event,
+            f"{event.kind} moves a run on, but this one stays in {event.phase.value}",
+        )
+    if not same_phase and event.kind in SAME_PHASE_EVENT_KINDS:
+        raise _kind_mismatch(
+            event,
+            f"{event.kind} does not move a run out of {event.phase.value}",
+        )
+
+
+def _check_created_event(event: RunEvent) -> None:
+    """Refuse a created event anywhere but at the opening of a log."""
+    if event.sequence != 0:
+        raise _kind_mismatch(
+            event,
+            f"{RUN_CREATED} opens a log at sequence 0, not {event.sequence}",
+        )
+    if event.previous_phase is not None:
+        raise _kind_mismatch(
+            event,
+            "a run's first event comes from no earlier phase, but this one "
+            f"claims to leave {event.previous_phase.value}",
+        )
+    if event.phase is not RunPhase.CREATED:
+        raise _kind_mismatch(
+            event,
+            f"{RUN_CREATED} opens a run in {RunPhase.CREATED.value}",
+        )
+
+
+def _check_required_details(event: RunEvent) -> None:
+    """Refuse an event that omits a detail its kind is defined to carry."""
+    for key in _REQUIRED_DETAILS.get(event.kind, ()):
+        if key not in event.details:
+            raise _kind_mismatch(
+                event,
+                f"a {event.kind} event carries details.{key}",
+            )
+
+
+def _kind_mismatch(event: RunEvent, reason: str) -> ValidationError:
+    """Return the one failure every kind and phase disagreement raises."""
+    previous = None if event.previous_phase is None else event.previous_phase.value
+    return ValidationError(
+        reason,
+        code="run_event_kind_invalid",
+        details={
+            "run_id": event.run_id,
+            "sequence": event.sequence,
+            "kind": event.kind,
+            "phase": event.phase.value,
+            "event_previous_phase": previous,
+        },
+    )
+
+
+# ---------------------------------------------------------------------------
+# Bytes
+# ---------------------------------------------------------------------------
+
+
+def append_event(path: Path, event: RunEvent) -> None:
+    """Append compact JSONL and fsync."""
+    line = canonical_json_bytes(event) + _LINE_SEPARATOR
+
+    flags = os.O_WRONLY | os.O_CREAT | os.O_APPEND
+    descriptor = os.open(path, flags, _FILE_MODE)
+    try:
+        written = 0
+        while written < len(line):
+            written += os.write(descriptor, line[written:])
+        os.fsync(descriptor)
+    finally:
+        os.close(descriptor)
+
+    # The first append also creates the directory entry, and a durable file
+    # whose name is not durable is not much use after a crash.
+    fsync_directory(path.parent)
+
+
+def read_events(path: Path) -> list[RunEvent]:
+    """Read events and reject sequence discontinuity."""
+    try:
+        raw = path.read_bytes()
+    except FileNotFoundError as error:
+        raise NotFoundError(
+            f"no run event log at {path}",
+            details={"path": str(path)},
+        ) from error
+
+    lines = raw.split(_LINE_SEPARATOR)
+    # A well-formed log ends with a separator, which leaves one empty trailing
+    # element. Any other empty line is damage.
+    if lines and lines[-1] == b"":
+        lines.pop()
+
+    events: list[RunEvent] = []
+    for number, line in enumerate(lines, start=1):
+        if not line.strip():
+            raise ValidationError(
+                f"run event log line {number} is empty: {path}",
+                code="run_event_log_corrupt",
+                details={"path": str(path), "line": number},
+            )
+        try:
+            event = RunEvent.model_validate_json(line)
+        except PydanticValidationError as error:
+            raise ValidationError(
+                f"run event log line {number} is not a run event: {path} "
+                f"({error.errors()[0]['msg']})",
+                code="run_event_log_corrupt",
+                details={"path": str(path), "line": number},
+            ) from error
+
+        expected = len(events)
+        if event.sequence != expected:
+            raise ValidationError(
+                f"run event log skips from sequence {expected - 1} to "
+                f"{event.sequence}: {path}",
+                code="run_event_sequence_invalid",
+                details={
+                    "path": str(path),
+                    "line": number,
+                    "expected_sequence": expected,
+                    "sequence": event.sequence,
+                },
+            )
+        events.append(event)
+
+    return events
+
+
+def next_sequence(events: list[RunEvent]) -> int:
+    """Return next sequence number."""
+    if not events:
+        return 0
+    return events[-1].sequence + 1
+
+
+def event_digest(path: Path) -> Digest:
+    """Digest exact event-log bytes."""
+    try:
+        return sha256_digest_bytes(path.read_bytes())
+    except FileNotFoundError as error:
+        raise NotFoundError(
+            f"no run event log at {path}",
+            details={"path": str(path)},
+        ) from error