mostlyright-data 0.9.0__py3-none-any.whl

mostlyright/data_harness/events.py

@@ -0,0 +1,2152 @@
+"""Append-only run events for live status views.
+
+The feed is a derived projection, not durable authority, and is excluded from sealed digests. Event
+pointers use candidate-relative paths and SHA-256 digests. The five-field record shape is fixed;
+new event names are added to the closed name sets and fact specification in this module.
+
+The vocabulary is extensible by NAME and never by FIELD, so a new fact means a new name. Build
+events cost three things in one commit: an `EVENT_FACTS` entry, a live emit site in `pipeline.py`,
+and a matching branch in `project_sealed_run` that derives the identical record from sealed bytes
+alone. The third is the binding one -- a live BUILD event a projection cannot re-derive is
+forbidden, which is why a time-throttled heartbeat is not in this vocabulary and is not to be
+added to it.
+
+The one explicit exception is the bounded post-seal notebook-sidecar sequence. It narrates an
+unsealed convenience write performed by the CLI after the Build exists, carries no path, digest,
+or authority, and cannot be projected from sealed bytes. Its three names are separated below so a
+consumer can never mistake sidecar state for Build evidence. Feed length remains bounded by the
+shape of one Build plus that fixed sequence; per-byte, per-row and per-chunk emission are refused.
+
+Live hosted progress is NOT here and is not to be moved here. `progress_events` carries a second,
+avowedly unsealed vocabulary for the hosted timeline; it is disjoint from every name set in this
+module by construction, `project_sealed_run` has no branch for any of its names, and it reads this
+feed only through the `observer` seam below, which adds no name and no record shape. The two
+vocabularies never merge: a progress record proves nothing, and a Build record must always prove
+itself from sealed bytes.
+"""
+
+from __future__ import annotations
+
+import contextlib
+import datetime
+import errno
+import hashlib
+import heapq
+import json
+import math
+import os
+import re
+import socket
+import stat
+import threading
+import time
+from collections.abc import Callable, Iterator, Mapping, Sequence
+from contextvars import ContextVar
+from pathlib import Path, PurePath
+from typing import Any
+
+FEED_SCHEMA_VERSION = "mr-run-events.v2"
+FEED_DIR_NAME = ".mr-events"
+
+# Untrusted-input ceilings. A feed may have been produced by another local user or hand-edited, so
+# the reader refuses rather than allocates.
+MAX_FEED_BYTES = 4 * 1024 * 1024
+MAX_FEED_RECORDS = 20_000
+MAX_TEXT_CHARS = 512
+MAX_FACT_KEYS = 24
+
+# Bound the aggregate attempt set as well as each file. Selection keeps the newest attempts. If a
+# matching attempt is outside the retained set, callers fall back to sealed receipts.
+MAX_FEED_ATTEMPTS = 32
+
+
+def _empty_attempt_size(name: str) -> int:
+    """Exact byte size of the header-only attempt ``EventWriter`` creates for ``name``."""
+
+    header = {
+        "v": 1,
+        "kind": "header",
+        "schema_version": FEED_SCHEMA_VERSION,
+        "run": Path(name).stem,
+    }
+    return len((_dumps(header) + "\n").encode("utf-8"))
+
+
+# Valid event times fit Python's UTC datetime range. The bound also rejects non-finite values and
+# finite numbers that cannot represent supported timestamps.
+_EARLIEST_MOMENT = datetime.datetime.min.replace(tzinfo=datetime.UTC).timestamp()
+_LATEST_MOMENT = datetime.datetime.max.replace(tzinfo=datetime.UTC).timestamp()
+
+# Write-side ceilings on the shape of a fact value.
+_MAX_FACT_DEPTH = 6
+_MAX_LIST_ITEMS = 256
+_TRUNCATION_MARKER = "..."
+
+_O_NOFOLLOW = getattr(os, "O_NOFOLLOW", 0)
+_O_NONBLOCK = getattr(os, "O_NONBLOCK", 0)
+_O_DIRECTORY = getattr(os, "O_DIRECTORY", 0)
+
+# Extend the vocabulary by adding names, not record fields. Local and hosted Build producers share
+# the same record shape.
+BUILD_EVENT_NAMES = frozenset(
+    {
+        "run_started",
+        "rights_checked",
+        "sources_read_started",
+        "source_read",
+        "sources_parsed_started",
+        "source_parsed",
+        "evidence_matched",
+        "cleaning_started",
+        "cleaning_applied",
+        "sources_profiled",
+        "join_completed",
+        "rows_selected",
+        "checks_started",
+        "check_completed",
+        "checks_completed",
+        "table_written",
+        "members_sealed_started",
+        "member_sealed",
+        "candidate_installed",
+        "snapshot_verify_started",
+        "member_verified",
+        "snapshot_verified",
+        "build_sealed",
+        "build_failed",
+        "run_interrupted",
+    }
+)
+
+# CLI-only narration of the unsealed ``table.ipynb`` convenience write. These records are
+# intentionally not in ``project_sealed_run``: sealed bytes cannot prove that a sibling file was
+# attempted or written. They carry no location or digest and grant no handoff authority.
+NOTEBOOK_SIDECAR_EVENT_NAMES = frozenset(
+    {
+        "notebook_sidecar_started",
+        "notebook_sidecar_ready",
+        "notebook_sidecar_failed",
+    }
+)
+NOTEBOOK_SIDECAR_OUTCOME_EVENT_NAMES = NOTEBOOK_SIDECAR_EVENT_NAMES - {"notebook_sidecar_started"}
+
+EVENT_NAMES = BUILD_EVENT_NAMES | NOTEBOOK_SIDECAR_EVENT_NAMES
+
+# The manifest version a recipe run seals under, spelled here as a LITERAL rather than imported.
+# `project_sealed_run` is pure and imports nothing from `pipeline` -- a module-level import would
+# close a cycle, and a deferred one inside the projector would give the projection a harness
+# dependency it does not otherwise have. `evidence_matched` needs this value to gate on, because a
+# recipe candidate seals `evidence/package.json` and still never matches proposal evidence. A test
+# asserts this equals `pipeline.RECIPE_MANIFEST_VERSION` so the two spellings cannot drift.
+_RECIPE_MANIFEST_VERSION = "candidate-manifest.v9"
+
+# Terminal events for attempts that did not seal a Build.
+TERMINAL_EVENT_NAMES = frozenset({"build_failed", "run_interrupted"})
+
+# Reserved Courier and Reader event names have bounded but otherwise unenforced fact mappings.
+# These events may
+# carry a scheme-qualified remote locator (`https://`, `s3://`, `gs://`) in a fact value. See
+# `_require_placeless`: that is placeless, because it resolves to the same bytes from every machine.
+# A path on this disk, a `file://` URL and a loopback authority remain refused.
+RESERVED_EVENT_NAMES = frozenset(
+    {
+        "fetch_started",
+        "slice_received",
+        "reader_opened",
+        "messages_decoded",
+        "cycle_locked",
+    }
+)
+
+# This mapping is the authoritative declaration of what each event asserts. Two producers write
+# Build records -- the live emitter in `pipeline.py` and the post-hoc projector
+# `project_sealed_run` -- and a test asserts their Build prefixes agree. The CLI alone writes the
+# three unsealed sidecar names. No producer may add, drop or rename a fact key; all read this table.
+# A fact set change is a change HERE, and every applicable producer plus its tests moves together.
+# `validate_facts` runs inside `EventWriter.write`, so a producer that drifts raises rather than
+# writing a record that quietly contradicts the declared shape.
+#
+# Three entries need explicit constraints:
+#
+# * `checks_completed` has no `failing` key. `_validate_output` RAISES on the first failed check, so
+#   a `checks_completed` record can only ever exist for a run where every check passed; a `failing`
+#   key would be a list that is structurally always empty, which reads as a claim the data cannot
+#   make. A failed check is narrated by `build_failed`.
+# * `source_read` has no `sha256` key. The live emitter has the raw bytes in hand but must not hash
+#   them -- the seal hashes every source already, and a second hash on the read path is work a
+#   event feed does not need. The digest is available through the record's
+#   `evidence_member` is `raw/<source_id>.csv`, which IS a sealed member, so its `member_sealed`
+#   record carries the digest.
+# * `join_completed` requires all seven join keys with no omissions. `_join` always emits every one
+#   of them, and a plan always carries exactly one join over at least two sources, so there is no
+#   shape where a key is absent. Do not write a "skip if missing" branch.
+# * `check_completed` has no `passed`, `observed` or `expected` key, on the exact precedent
+#   `checks_completed` sets immediately above: `_validate_output` raises on the first failed check,
+#   so those three would be structurally constant on every record that survives to be read. The
+#   record IS emitted before the refusal, so a failing check is still counted; the `build_failed`
+#   that follows carries that check's id as its `finding_id`, which is where a failure is narrated.
+# * The six `*_started` markers each carry a `total` and nothing else. The admission test for one is
+#   that its denominator is fixed BEFORE its loop starts and is readable out of a sealed member
+#   afterwards -- a stage whose size is only knowable once it is finished is not progress, it is a
+#   spinner with a number on it. All six anchor `plan.json`, because the plan is what fixes every
+#   one of those totals: the source count and the cleaning-step count are literally in it, the check
+#   total is `2 + len(grain) + len(quality.not_null)`, and the member set is the static file set for
+#   the manifest version plus one `raw/<source_id>.csv` per planned source.
+# * `member_verified` mirrors `member_sealed` exactly, for the same reason: its pointer varies per
+#   member and rides in `evidence` rather than in a fact.
+EVENT_FACTS: Mapping[str, tuple[str, ...]] = {
+    "run_started": ("sources", "output_intent", "grain", "columns", "evidence_member"),
+    "rights_checked": ("sources", "evidence_member"),
+    "sources_read_started": ("total", "evidence_member"),
+    "source_read": ("source_id", "bytes", "evidence_member"),
+    "sources_parsed_started": ("total", "evidence_member"),
+    "source_parsed": ("source_id", "rows", "columns", "evidence_member"),
+    "evidence_matched": ("matched", "total", "evidence_member"),
+    "cleaning_started": ("total", "evidence_member"),
+    "cleaning_applied": (
+        "step_index",
+        "step_total",
+        "source_id",
+        "operation",
+        "evidence_member",
+    ),
+    "sources_profiled": ("sources", "columns", "evidence_member"),
+    "join_completed": (
+        "left_rows",
+        "right_rows",
+        "output_rows",
+        "matched_left_rows",
+        "unmatched_left_rows",
+        "row_multiplier",
+        "cardinality",
+        "evidence_member",
+    ),
+    "rows_selected": ("rows", "columns", "evidence_member"),
+    "checks_started": ("total", "evidence_member"),
+    "check_completed": ("check_id", "index", "total", "evidence_member"),
+    "checks_completed": ("passed", "total", "evidence_member"),
+    "table_written": ("rows", "columns", "evidence_member"),
+    "members_sealed_started": ("total", "evidence_member"),
+    "member_sealed": ("bytes",),
+    "candidate_installed": ("members", "bytes", "evidence_member"),
+    "snapshot_verify_started": ("total", "evidence_member"),
+    "member_verified": ("bytes",),
+    "snapshot_verified": ("members", "table_sha256", "evidence_member"),
+    "build_sealed": ("candidate_digest", "table_sha256", "manifest_version", "row_count"),
+    "build_failed": ("finding_id", "severity", "message"),
+    "run_interrupted": (),
+    "notebook_sidecar_started": (),
+    "notebook_sidecar_ready": (),
+    "notebook_sidecar_failed": ("code",),
+}
+
+# The fixed member each event points at. `member_sealed`, `member_verified` and `build_sealed` are
+# absent BY DESIGN: the first two carry their pointer in `evidence` directly, one per member, and
+# `build_sealed` anchors on the candidate digest, which is not a member of anything. The one event
+# whose pointer varies is `source_read`; `source_member` builds it.
+#
+# `manifest.json` is NOT in `manifest["members"]`, so it can never appear here: `_pointer` would
+# raise on it during projection. Every anchor below is a real member.
+EVIDENCE_MEMBER: Mapping[str, str] = {
+    "run_started": "plan.json",
+    "rights_checked": "evidence/sources.json",
+    "sources_read_started": "plan.json",
+    "sources_parsed_started": "plan.json",
+    "source_parsed": "evidence/source_profiles.json",
+    "evidence_matched": "evidence/package.json",
+    "cleaning_started": "plan.json",
+    "cleaning_applied": "evidence/lineage.json",
+    "sources_profiled": "evidence/source_profiles.json",
+    "join_completed": "evidence/join.json",
+    # `evidence/profile.json`, not `evidence/lineage.json`: lineage redeems the column count and
+    # says nothing about rows, and the profile is the one member carrying BOTH numbers this record
+    # states. It is also what the projection actually reads.
+    "rows_selected": "evidence/profile.json",
+    "checks_started": "plan.json",
+    "check_completed": "evidence/quality.json",
+    "checks_completed": "evidence/quality.json",
+    "table_written": "data/table.parquet",
+    "members_sealed_started": "plan.json",
+    "candidate_installed": "data/table.parquet",
+    "snapshot_verify_started": "plan.json",
+    "snapshot_verified": "data/table.parquet",
+}
+
+_ATTEMPT_RE = re.compile(r"\A[A-Za-z0-9._-]{1,64}\Z")
+_SOURCE_ID_RE = re.compile(r"\A[A-Za-z0-9._-]{1,64}\Z")
+_MEMBER_PATH_RE = re.compile(r"\A[A-Za-z0-9._/-]{1,128}\Z")
+_SHA256_RE = re.compile(r"\A[0-9a-f]{64}\Z")
+# A Windows drive prefix ANYWHERE in a string. The lookbehind is what keeps `https://` out of it:
+# without it, the `s:/` inside every `https://` locator reads as a drive letter.
+_WINDOWS_DRIVE_RE = re.compile(r"(?<![A-Za-z0-9])[A-Za-z]:[\\/]")
+
+# A `/`-rooted path of two or more segments, ANYWHERE in a string. The guard used to test only
+# `text.startswith("/")`, and every `BuildError` message in the tree reads
+# "<what went wrong>: <path>", so this host's absolute paths reached the feed and both UI surfaces
+# untouched. The lookbehind is what keeps a date (`2026/08/07`) and a relative member path
+# (`evidence/sources.json`) out of it: a rooted path's leading slash never follows a word character.
+_EMBEDDED_ABS_PATH_RE = re.compile(r"(?<![A-Za-z0-9_.~-])(?:/[^\s/\\'\"<>|]+){2,}")
+
+# A scheme-qualified locator (`https://`, `s3://`, `gs://`, `abfss://`, ...), matched at the start
+# of ONE whitespace-delimited token rather than of the whole string, so a locator quoted inside
+# prose ("downloading from https://noaa.gov/...") is read as the locator it is.
+_URL_SCHEME_RE = re.compile(r"\A([A-Za-z][A-Za-z0-9+.-]*)://")
+
+# Punctuation a locator gets wrapped in when a sentence carries it.
+_TOKEN_TRIM = "()[]{}<>\"'`,;"
+# The schemes that mean "this machine" however they are dressed.
+_LOCAL_URL_SCHEMES = frozenset({"file", "localhost", "unix", "fd"})
+_LOCAL_URL_HOSTS = frozenset({"localhost", "127.0.0.1", "0.0.0.0", "::1", "0:0:0:0:0:0:0:1"})
+
+# Computed once at import. A hostname shorter than four characters is skipped: a two-letter host
+# name would match inside half the English language, and a guard with absurd false positives is a
+# guard someone turns off.
+try:
+    _HOSTNAME = socket.gethostname()
+except OSError:  # pragma: no cover - gethostname does not fail on a supported platform
+    _HOSTNAME = ""
+_HOSTNAME_MATCH = _HOSTNAME.lower() if len(_HOSTNAME) >= 4 else ""
+
+_RECORD_KEYS = frozenset({"seq", "at", "event", "facts", "evidence"})
+_EVIDENCE_KEYS = frozenset({"member", "sha256"})
+
+_ALL_EVENT_NAMES = EVENT_NAMES | RESERVED_EVENT_NAMES
+
+
+def source_member(source_id: str) -> str:
+    """Return the candidate-relative member path carrying the raw bytes of ``source_id``.
+
+    The source id is matched against the member-path character class before it is interpolated, so
+    a source id can never widen the pointer vocabulary or introduce a traversal segment.
+    """
+
+    if not isinstance(source_id, str) or not _SOURCE_ID_RE.match(source_id):
+        raise ValueError(f"source id is not a member-path token: {source_id!r}")
+    return f"raw/{source_id}.csv"
+
+
+def validate_facts(event: str, facts: Mapping[str, Any]) -> None:
+    """Enforce the normative fact set for ``event``; raise ``ValueError`` naming the difference.
+
+    The error names missing and extra keys. Reserved event names without an ``EVENT_FACTS`` entry
+    accept any mapping within ``MAX_FACT_KEYS``.
+    """
+
+    if event not in _ALL_EVENT_NAMES:
+        raise ValueError(f"event name is outside the closed vocabulary: {event!r}")
+    if not isinstance(facts, Mapping):
+        raise ValueError(f"facts for {event!r} is not a mapping")
+    if any(not isinstance(key, str) for key in facts):
+        raise ValueError(f"facts for {event!r} carries a non-string key")
+    if len(facts) > MAX_FACT_KEYS:
+        raise ValueError(f"facts for {event!r} carries {len(facts)} keys, over {MAX_FACT_KEYS}")
+
+    declared = EVENT_FACTS.get(event)
+    if declared is None:
+        return None
+
+    present = set(facts)
+    expected = set(declared)
+    if present == expected:
+        return None
+    missing = sorted(expected - present)
+    extra = sorted(present - expected)
+    raise ValueError(
+        f"facts for {event!r} do not match the declared set: "
+        f"missing={missing} extra={extra} declared={list(declared)}"
+    )
+
+
+def run_feed_dir(run_dir: str | os.PathLike[str]) -> Path:
+    """Return the feed directory for ONE run: ``<runs parent>/.mr-events/<run name>/``.
+
+    The feed lives in the runs PARENT and never inside the run directory, for two reasons that both
+    matter:
+
+    * A failed build has no run directory at all. `build_candidate` stages into a hidden temporary
+      directory and renames only at the very end, and pre-creating the output raises
+      ``OUTPUT_EXISTS``. A feed inside the run directory could therefore never show a failure --
+      the exact case a watcher most wants to see.
+    * A file inside the run directory would be a new file inside a closed candidate member set
+      (G1). The feed must never be a member of anything.
+
+    It is scoped by the RUN'S OWN NAME, which is what makes a feed belong to a run. ``mr-data
+    build`` and ``mr-data recipe-run`` routinely put many runs in one parent; a flat feed directory
+    made "newest file wins" the only available rule, and a reader following it narrated one run's
+    build under another run's name and then raised a tamper refusal on the first receipt link,
+    because the digests it cited belonged to the other run. A directory per run removes the
+    ambiguity rather than resolving it: a foreign feed is not in the directory at all.
+    """
+
+    resolved = Path(run_dir).absolute()
+    return resolved.parent / FEED_DIR_NAME / _require_run_name(resolved.name)
+
+
+def feed_path(output_dir: str | os.PathLike[str], producer_attempt: str) -> Path:
+    """Return the feed file for one build attempt: ``<run feed dir>/<attempt>.jsonl``.
+
+    ``producer_attempt`` is matched against ``[A-Za-z0-9._-]{1,64}`` before it reaches a path, so an
+    attempt id can never traverse. Each attempt has its own file and timestamp origin.
+    """
+
+    return run_feed_dir(output_dir) / f"{_require_attempt_id(producer_attempt)}.jsonl"
+
+
+def _require_run_name(name: str) -> str:
+    """Refuse a run name that cannot be one path component. Never repairs, only refuses."""
+
+    if not name or name in {".", ".."} or len(name) > 128:
+        raise ValueError(f"run name is not a safe path component: {name!r}")
+    if "/" in name or "\\" in name or "\x00" in name:
+        raise ValueError(f"run name is not a safe path component: {name!r}")
+    return name
+
+
+def _require_attempt_id(producer_attempt: str) -> str:
+    if not isinstance(producer_attempt, str) or not _ATTEMPT_RE.match(producer_attempt):
+        raise ValueError(f"producer attempt id is not a safe token: {producer_attempt!r}")
+    if producer_attempt in {".", ".."}:
+        raise ValueError(f"producer attempt id is not a safe token: {producer_attempt!r}")
+    return producer_attempt
+
+
+def _require_member_path(value: Any, key: str) -> None:
+    if not isinstance(value, str) or not _MEMBER_PATH_RE.match(value):
+        raise ValueError(f"{key} is not a candidate-relative member path: {value!r}")
+    if value.startswith("/") or ".." in value.split("/"):
+        raise ValueError(f"{key} is not a candidate-relative member path: {value!r}")
+
+
+def _iter_strings(value: Any, key: str) -> Any:
+    """Yield every ``(key, string)`` pair reachable in a fact or evidence value."""
+
+    if isinstance(value, str):
+        yield key, value
+    elif isinstance(value, Mapping):
+        for inner_key, inner in value.items():
+            yield from _iter_strings(inner, f"{key}.{inner_key}")
+    elif isinstance(value, (list, tuple)):
+        for index, item in enumerate(value):
+            yield from _iter_strings(item, f"{key}[{index}]")
+
+
+class PlaceNamedError(ValueError):
+    """A fact string named a local place instead of portable evidence.
+
+    A distinct type because a distinct RECOVERY applies. A producer whose fact KEYS drifted from
+    ``EVENT_FACTS`` is a code defect and disarms the sink deliberately, so the drift shows up as a
+    truncated feed rather than as a feed full of wrong records. A fact whose VALUE happened to
+    carry a path is not that: the record is still true, only unportable, so the sink redacts the
+    offending strings and continues writing the feed.
+    """
+
+
+class UnwritableTextError(ValueError):
+    """A fact string carried text no surface can encode as UTF-8 -- a lone surrogate.
+
+    A distinct type for the same reason ``PlaceNamedError`` is one: a distinct RECOVERY applies.
+    The record is still true, only unwritable, so the sink repairs the offending strings through
+    ``writable_text`` and keeps narrating rather than disarming. See ``writable_text`` for what a
+    lone surrogate costs every surface that has to encode it.
+    """
+
+
+def _require_location_blind(record: Mapping[str, Any]) -> None:
+    """Refuse any record that names a local place instead of portable evidence.
+
+    Local and hosted workers must emit identical records. Absolute paths, home directories,
+    ``file://`` URLs, UNC prefixes, and host names are therefore refused. Pointers use a
+    candidate-relative member path and SHA-256 digest.
+    """
+
+    evidence = record.get("evidence")
+    if evidence is not None:
+        if not isinstance(evidence, Mapping) or set(evidence) != _EVIDENCE_KEYS:
+            raise ValueError("evidence must be exactly {'member', 'sha256'} or None")
+        _require_member_path(evidence["member"], "evidence.member")
+        if not isinstance(evidence["sha256"], str) or not _SHA256_RE.match(evidence["sha256"]):
+            raise ValueError(f"evidence.sha256 is not a sha256 digest: {evidence['sha256']!r}")
+
+    facts = record.get("facts") or {}
+    if "evidence_member" in facts:
+        _require_member_path(facts["evidence_member"], "facts.evidence_member")
+
+    for scope, container in (("facts", facts), ("evidence", evidence)):
+        if container is None:
+            continue
+        for key, text in _iter_strings(container, scope):
+            _require_placeless(key, text)
+
+
+def _locator_tokens(text: str) -> Iterator[str]:
+    """Yield the whitespace-delimited tokens of ``text``, unwrapped from sentence punctuation.
+
+    The guard reads a fact string token by token rather than as one blob because local paths and
+    remote locators can both live inside prose. ``output already exists: /private/tmp/run`` carries
+    a place in its last token; ``downloading from https://noaa.gov/t00z.grib2`` carries a placeless
+    locator in its last token. A rule anchored at position 0 gets both wrong in opposite directions.
+    """
+
+    for raw in text.split():
+        token = raw.strip(_TOKEN_TRIM)
+        if token:
+            yield token
+
+
+def _require_placeless(key: str, text: str) -> None:
+    """Refuse a string that names THIS machine. A remote locator is not such a string.
+
+    The invariant is portability, not punctuation: the record a Cloud Run job emits for a Build
+    must be the record this laptop emits for it. ``/Users/rob/runs/out.csv`` fails that test;
+    ``https://noaa.gov/hrrr/t00z.grib2`` passes it, because the URL resolves to the same bytes from
+    either machine. Both tests apply WHEREVER the string in question sits:
+
+    * a place is refused anywhere -- ``output already exists: /private/tmp/run`` is the shape every
+      ``BuildError`` message in this tree has, and a guard anchored at position 0 admitted all of
+      them, so a real ``build_failed`` record carried this disk's paths onto the feed and onto both
+      UI surfaces;
+    * a scheme-qualified remote locator is admitted anywhere -- the guard used to refuse every
+      string containing ``//``, which refused exactly the fact the Courier and Reader lanes carry.
+
+    Still refused, however the string is dressed: ``file://`` and any other local scheme, a rooted
+    absolute path, a Windows drive, a UNC share, ``~``, a loopback or ``.localhost`` authority
+    (this machine wearing a URL), and this host's own name.
+
+    Raises :class:`PlaceNamedError` so a caller can tell "this record is unportable" (redactable)
+    apart from "this record is malformed" (a producer defect).
+    """
+
+    lowered = text.lower()
+    if "file://" in lowered:
+        raise PlaceNamedError(f"{key} names a file URL: {text!r}")
+    # A UNC share, checked literally rather than through `os.sep` so the rule is the same on every
+    # platform (on POSIX `os.sep + os.sep` is just `//`, which the per-token branch below catches).
+    if "\\\\" in text:
+        raise PlaceNamedError(f"{key} names a network share: {text!r}")
+    if _HOSTNAME_MATCH and _HOSTNAME_MATCH in lowered:
+        raise PlaceNamedError(f"{key} names this machine")
+
+    for token in _locator_tokens(text):
+        scheme_match = _URL_SCHEME_RE.match(token)
+        if scheme_match is not None:
+            scheme = scheme_match.group(1).lower()
+            if scheme in _LOCAL_URL_SCHEMES:
+                raise PlaceNamedError(f"{key} names a location on this machine: {token!r}")
+            if _authority_is_local(token.lower()[scheme_match.end() :]):
+                raise PlaceNamedError(f"{key} names this machine: {token!r}")
+            # A remote locator means the same thing from every machine, so it is placeless.
+            continue
+
+        if token.startswith("/") or _EMBEDDED_ABS_PATH_RE.search(token):
+            raise PlaceNamedError(f"{key} names an absolute path: {token!r}")
+        if _WINDOWS_DRIVE_RE.search(token):
+            raise PlaceNamedError(f"{key} names an absolute path: {token!r}")
+        if token.startswith("~") or "~/" in token:
+            raise PlaceNamedError(f"{key} names a home directory: {token!r}")
+        if "//" in token:
+            raise PlaceNamedError(f"{key} names a network or URL location: {token!r}")
+
+
+def _authority_is_local(remainder: str) -> bool:
+    """True when a URL's authority is a loopback name this machine alone resolves."""
+
+    authority = remainder.split("/", 1)[0].split("?", 1)[0].split("#", 1)[0]
+    authority = authority.rsplit("@", 1)[-1]
+    if authority.startswith("["):
+        host = authority.split("]", 1)[0].lstrip("[")
+    else:
+        host = authority.split(":", 1)[0]
+    return host in _LOCAL_URL_HOSTS or host.endswith(".localhost")
+
+
+def _normalize_json(value: Any, *, key: str, depth: int = 0) -> Any:
+    """Return a JSON-safe copy of ``value`` or raise ``ValueError``.
+
+    Fact values are JSON scalars, lists, and flat mappings of scalars -- `rights_checked` reports
+    one mapping per source, and a tuple on a dataclass has to arrive here as a list because JSON has
+    no tuple. Depth and width are bounded so a fact value can never be a document.
+    """
+
+    if depth > _MAX_FACT_DEPTH:
+        raise ValueError(f"fact {key!r} nests deeper than {_MAX_FACT_DEPTH}")
+    if value is None or isinstance(value, bool):
+        return value
+    if isinstance(value, str):
+        if writable_text(value) != value:
+            # BESIDE THE NON-FINITE FLOAT REFUSAL, and for the identical reason: a fact this writer
+            # accepts must be one every surface downstream can encode. `_dumps` uses
+            # `ensure_ascii=True`, so a lone surrogate was written out as a pure-ASCII `\ud800`
+            # escape and read back as a lone surrogate -- the writer's boundary and the reader's
+            # boundary were both open on the same value class. Refused here rather than repaired,
+            # so a producer that builds a fact out of undecodable bytes learns it; `event_sink`
+            # turns the refusal into a repaired record rather than a lost one, which is exactly
+            # what it already does for a fact that named a place.
+            raise UnwritableTextError(f"fact {key!r} carries text no surface can encode")
+        return value
+    if isinstance(value, int):
+        return value
+    if isinstance(value, float):
+        if not math.isfinite(value):
+            raise ValueError(f"fact {key!r} is not a finite number")
+        return value
+    if isinstance(value, Mapping):
+        if len(value) > MAX_FACT_KEYS:
+            raise ValueError(f"fact {key!r} carries more than {MAX_FACT_KEYS} keys")
+        normalized: dict[str, Any] = {}
+        for inner_key, inner in value.items():
+            if not isinstance(inner_key, str):
+                raise ValueError(f"fact {key!r} carries a non-string key")
+            if writable_text(inner_key) != inner_key:
+                raise UnwritableTextError(f"fact {key!r} carries a key no surface can encode")
+            normalized[inner_key] = _normalize_json(
+                inner, key=f"{key}.{inner_key}", depth=depth + 1
+            )
+        return normalized
+    if isinstance(value, Sequence):
+        items = list(value)
+        if len(items) > _MAX_LIST_ITEMS:
+            raise ValueError(f"fact {key!r} carries more than {_MAX_LIST_ITEMS} items")
+        return [_normalize_json(item, key=f"{key}[]", depth=depth + 1) for item in items]
+    raise ValueError(f"fact {key!r} is not a JSON value: {type(value).__name__}")
+
+
+def _normalize_facts(event: str, facts: Mapping[str, Any]) -> dict[str, Any]:
+    return {key: _normalize_json(value, key=key) for key, value in facts.items()}
+
+
+def open_regular_file(
+    name: str | os.PathLike[str],
+    *,
+    dir_fd: int | None = None,
+    flags: int = os.O_RDONLY,
+    mode: int = 0o600,
+) -> int:
+    """Open ``name`` as a nonblocking regular file without following links.
+
+    ``fstat`` validates the opened descriptor. With ``dir_fd``, each path component is opened using
+    ``O_DIRECTORY | O_NOFOLLOW`` beneath the caller's trusted root. Without ``dir_fd``, only the
+    leaf is validated.
+    """
+
+    parent_fd, leaf, borrowed = _descend_to_parent(name, dir_fd)
+    try:
+        handle_fd = os.open(leaf, flags | _O_NOFOLLOW | _O_NONBLOCK, mode, dir_fd=parent_fd)
+    finally:
+        if not borrowed and parent_fd is not None:
+            os.close(parent_fd)
+    try:
+        opened = os.fstat(handle_fd)
+        if not stat.S_ISREG(opened.st_mode) or opened.st_nlink != 1:
+            raise OSError("not a regular file where a regular file should be")
+    except BaseException:
+        os.close(handle_fd)
+        raise
+    return handle_fd
+
+
+def open_directory(name: str | os.PathLike[str], *, dir_fd: int | None = None) -> int:
+    """Open ``name`` as a directory, refusing a symlink at every component ``name`` names.
+
+    The directory half of ``open_regular_file``, with the same trust rule: with ``dir_fd`` every
+    component of ``name`` is proved, without it the directory part of ``name`` is the caller's own
+    and the leaf is proved. Callers hold the returned descriptor and read relative to it, so the
+    directory measured and the directory read are the same object however the name is rebound
+    afterwards.
+    """
+
+    parent_fd, leaf, borrowed = _descend_to_parent(name, dir_fd)
+    try:
+        return _open_component_directory(leaf, parent_fd)
+    finally:
+        if not borrowed and parent_fd is not None:
+            os.close(parent_fd)
+
+
+def duplicate_directory(directory_fd: int) -> int:
+    """Return an independently owned reference to an already proved directory descriptor."""
+
+    duplicate = os.dup(directory_fd)
+    try:
+        if not stat.S_ISDIR(os.fstat(duplicate).st_mode):
+            raise OSError(errno.ENOTDIR, "not a directory where a directory should be")
+    except BaseException:
+        os.close(duplicate)
+        raise
+    return duplicate
+
+
+def _open_component_directory(name: str, dir_fd: int | None) -> int:
+    """Open ONE path component as a directory. Never follows a symlink, never blocks."""
+
+    fd = os.open(name, os.O_RDONLY | _O_DIRECTORY | _O_NOFOLLOW | _O_NONBLOCK, dir_fd=dir_fd)
+    try:
+        if not stat.S_ISDIR(os.fstat(fd).st_mode):
+            # Reachable only where `O_DIRECTORY` does not exist, in which case the flag is 0 and
+            # the open accepted a regular file. Asked of the DESCRIPTOR, as everywhere else here.
+            raise OSError(errno.ENOTDIR, "not a directory where a directory should be")
+    except BaseException:
+        os.close(fd)
+        raise
+    return fd
+
+
+def _descend_to_parent(
+    name: str | os.PathLike[str], dir_fd: int | None
+) -> tuple[int | None, str, bool]:
+    """Return ``(parent_fd, leaf, borrowed)`` for ``name``. ``borrowed`` fds are the caller's.
+
+    Below a ``dir_fd`` every component is opened on its own with ``O_NOFOLLOW``, so a symlinked
+    directory component is refused instead of followed. ``.`` and ``..`` are refused outright: a
+    descent that honoured them would walk back out of the directory the caller proved, which is
+    the whole thing the descent exists to prevent.
+    """
+
+    parts = PurePath(os.fspath(name)).parts
+    if not parts:
+        raise OSError(errno.ENOENT, "an empty name opens nothing")
+    if dir_fd is None:
+        if len(parts) == 1:
+            return None, parts[0], True
+        prefix = os.path.dirname(os.fspath(name))
+        return os.open(prefix, os.O_RDONLY | _O_DIRECTORY), parts[-1], False
+    if os.path.isabs(os.fspath(name)):
+        raise OSError(errno.EINVAL, "an absolute name is not relative to a directory")
+
+    parent_fd, borrowed = dir_fd, True
+    try:
+        for part in parts[:-1]:
+            if part in (os.curdir, os.pardir):
+                raise OSError(errno.EINVAL, f"a member path may not contain {part!r}")
+            child = _open_component_directory(part, parent_fd)
+            if not borrowed:
+                os.close(parent_fd)
+            parent_fd, borrowed = child, False
+    except BaseException:
+        if not borrowed:
+            os.close(parent_fd)
+        raise
+    return parent_fd, parts[-1], borrowed
+
+
+def _regular_file_identity(info: os.stat_result) -> tuple[int, ...]:
+    """Identity fields that must stay fixed while a mutable plain file is read."""
+
+    return (
+        info.st_dev,
+        info.st_ino,
+        info.st_mode,
+        info.st_nlink,
+        info.st_uid,
+        info.st_gid,
+        info.st_size,
+        info.st_mtime_ns,
+        info.st_ctime_ns,
+    )
+
+
+def read_regular_bytes(
+    path: str | os.PathLike[str], *, dir_fd: int | None = None, max_bytes: int
+) -> bytes:
+    """Read one regular file whole through ``open_regular_file``. Raises ``OSError``, never blocks.
+
+    The descriptor-based read rejects symlinks and non-regular files without a separate path lookup.
+    Nonblocking open prevents a FIFO from stalling the caller.
+
+    ``max_bytes`` refuses rather than allocates, and the size it tests comes off the DESCRIPTOR, not
+    off a second look at the path. The read is bounded one byte past the ceiling so a file that grew
+    between the two is refused as oversized rather than read without a limit.
+
+    ``dir_fd`` reads ``path`` relative to a directory descriptor the caller already holds, which is
+    how ``rederive_feed`` reads a candidate the verify has pinned open rather than re-walking the
+    run directory by name. It is the same argument ``watch`` passes for the same reason.
+    """
+
+    handle_fd = open_regular_file(path, dir_fd=dir_fd)
+    try:
+        before = os.fstat(handle_fd)
+        if before.st_size > max_bytes:
+            raise OSError("larger than this reader's ceiling")
+        chunks: list[bytes] = []
+        remaining = max_bytes + 1
+        while remaining > 0:
+            chunk = os.read(handle_fd, min(remaining, 1 << 16))
+            if not chunk:
+                break
+            chunks.append(chunk)
+            remaining -= len(chunk)
+        payload = b"".join(chunks)
+        after = os.fstat(handle_fd)
+    finally:
+        os.close(handle_fd)
+    if len(payload) > max_bytes:
+        raise OSError("larger than this reader's ceiling")
+    if _regular_file_identity(before) != _regular_file_identity(after):
+        raise OSError("regular file changed while it was read")
+    named = os.stat(path, dir_fd=dir_fd, follow_symlinks=False)
+    if not stat.S_ISREG(named.st_mode) or named.st_nlink != 1:
+        raise OSError("not a regular file where a regular file should be")
+    if _regular_file_identity(before) != _regular_file_identity(named):
+        raise OSError("regular file name changed while it was read")
+    return payload
+
+
+def snapshot_candidate_namespace(
+    candidate_fd: int,
+    members: Sequence[str],
+    *,
+    manifest_name: str = "manifest.json",
+) -> tuple[tuple[tuple[str, ...], tuple[int, ...], tuple[str, ...]], ...]:
+    """Return the exact descriptor-relative directory namespace for candidate members.
+
+    Every directory is opened through :func:`open_directory`, and its identity is checked before
+    and after listing.  The result is suitable as one component of a retained proof: an added,
+    removed, replaced, or permission-changed directory invalidates the proof even when all named
+    member files are otherwise unchanged.
+    """
+
+    expected: dict[tuple[str, ...], set[str]] = {(): {manifest_name}}
+    for member in members:
+        _require_member_path(member, "manifest member path")
+        parts = tuple(member.split("/"))
+        parent: tuple[str, ...] = ()
+        for component in parts[:-1]:
+            expected.setdefault(parent, set()).add(component)
+            parent = (*parent, component)
+            expected.setdefault(parent, set())
+        expected.setdefault(parent, set()).add(parts[-1])
+
+    observed: list[tuple[tuple[str, ...], tuple[int, ...], tuple[str, ...]]] = []
+    for parts, expected_children in sorted(expected.items()):
+        directory_fd = (
+            os.dup(candidate_fd)
+            if not parts
+            else open_directory("/".join(parts), dir_fd=candidate_fd)
+        )
+        try:
+            before = os.fstat(directory_fd)
+            children = tuple(sorted(os.listdir(directory_fd)))
+            after = os.fstat(directory_fd)
+        finally:
+            os.close(directory_fd)
+        before_identity = _directory_identity(before)
+        if before_identity != _directory_identity(after):
+            raise OSError("candidate directory changed while its namespace was listed")
+        if set(children) != expected_children:
+            raise OSError("candidate namespace differs from its manifest")
+        observed.append((parts, before_identity, children))
+    return tuple(observed)
+
+
+def _directory_identity(info: os.stat_result) -> tuple[int, ...]:
+    return (
+        info.st_dev,
+        info.st_ino,
+        info.st_mode,
+        info.st_nlink,
+        info.st_uid,
+        info.st_gid,
+        info.st_mtime_ns,
+        info.st_ctime_ns,
+    )
+
+
+def _create_feed_directory(feed_dir: str | os.PathLike[str]) -> int:
+    """Create a private feed directory and return its validated descriptor.
+
+    Each component is created relative to its parent descriptor, opened with
+    ``O_DIRECTORY | O_NOFOLLOW``, checked for ownership, and tightened to mode 0700. Directories
+    owned by another principal are refused.
+    """
+
+    feed_dir = Path(feed_dir)
+    feed_dir.parent.parent.mkdir(parents=True, exist_ok=True)
+    root_fd = os.open(feed_dir.parent.parent, os.O_RDONLY | _O_DIRECTORY)
+    try:
+        events_fd = _create_private_directory(feed_dir.parent.name, root_fd)
+    finally:
+        os.close(root_fd)
+    try:
+        return _create_private_directory(feed_dir.name, events_fd)
+    finally:
+        os.close(events_fd)
+
+
+def _create_private_directory(name: str, dir_fd: int) -> int:
+    """Create one component ``0o700`` under ``dir_fd`` and return a descriptor that proves it."""
+
+    try:
+        os.mkdir(name, 0o700, dir_fd=dir_fd)
+    except FileExistsError:
+        pass
+    fd = _open_component_directory(name, dir_fd)
+    try:
+        info = os.fstat(fd)
+        getuid = getattr(os, "getuid", None)
+        if getuid is not None and info.st_uid != getuid():
+            raise OSError(errno.EPERM, f"feed directory {name!r} belongs to another user")
+        if stat.S_IMODE(info.st_mode) != 0o700:
+            # Ours, so it is tightened rather than refused -- through the descriptor, so the
+            # object whose mode changes is the object that was proved.
+            os.fchmod(fd, 0o700)
+    except BaseException:
+        os.close(fd)
+        raise
+    return fd
+
+
+class EventWriter:
+    """An append-only writer over one feed file.
+
+    One descriptor per feed, opened ``O_APPEND`` and written one whole line per ``os.write`` call,
+    so a reader tailing the file never sees a torn record and two writers on the same feed cannot
+    interleave a line. ``O_NOFOLLOW`` because another local user may have swapped a symlink in.
+    """
+
+    def __init__(self, path: str | os.PathLike[str], *, run: str | None = None) -> None:
+        self._path = Path(path)
+        self._run = _require_attempt_id(run if run is not None else self._path.stem)
+        self._lock = threading.Lock()
+
+        existing = read_feed(self._path)
+        self._seq = int(existing[-1]["seq"]) if existing else 0
+        self._last_at = float(existing[-1]["at"]) if existing else 0.0
+        torn_tail = _ends_mid_record(self._path)
+
+        feed_dir_fd = _create_feed_directory(self._path.parent)
+        try:
+            # Through the same descriptor-checked open the readers use, and RELATIVE to the
+            # directory descriptor just proved. A FIFO where the feed should be blocks a WRITE open
+            # too -- until some process opens it for reading, which may be never -- so `mr-data
+            # run` hung while arming its feed, before the build had done anything at all.
+            self._fd: int | None = open_regular_file(
+                self._path.name,
+                dir_fd=feed_dir_fd,
+                flags=os.O_WRONLY | os.O_CREAT | os.O_APPEND,
+                mode=0o600,
+            )
+        finally:
+            os.close(feed_dir_fd)
+        if os.fstat(self._fd).st_size == 0:
+            header = {
+                "v": 1,
+                "kind": "header",
+                "schema_version": FEED_SCHEMA_VERSION,
+                "run": self._run,
+            }
+            os.write(self._fd, (_dumps(header) + "\n").encode("utf-8"))
+        elif torn_tail:
+            # The feed ends mid-record: a previous writer died, or the file was truncated. Close the
+            # torn line off with a newline before appending, so the next record starts on a line of
+            # its own instead of being glued onto the wreckage. The torn line stays unreadable --
+            # that is correct, it was never complete -- but every record after it is readable again.
+            os.write(self._fd, b"\n")
+
+    @property
+    def path(self) -> Path:
+        return self._path
+
+    def write(
+        self,
+        event: str,
+        facts: Mapping[str, Any],
+        evidence: Mapping[str, Any] | None = None,
+    ) -> None:
+        """Append one record. Raises ``ValueError`` on anything the vocabulary does not allow."""
+
+        if event not in _ALL_EVENT_NAMES:
+            raise ValueError(f"event name is outside the closed vocabulary: {event!r}")
+        validate_facts(event, facts)
+        normalized_facts = _normalize_facts(event, facts)
+        normalized_evidence = None if evidence is None else dict(evidence)
+
+        with self._lock:
+            if self._fd is None:
+                raise ValueError("event writer is closed")
+            now = time.time()
+            if now < self._last_at:
+                # A feed's `at` is strictly non-decreasing: a reader draws elapsed time from it and
+                # a clock that stepped backwards must not read as a stage that took negative time.
+                now = self._last_at
+            record = {
+                "seq": self._seq + 1,
+                "at": now,
+                "event": event,
+                "facts": normalized_facts,
+                "evidence": normalized_evidence,
+            }
+            _require_location_blind(record)
+            line = (_dumps(record) + "\n").encode("utf-8")
+            os.write(self._fd, line)
+            self._seq += 1
+            self._last_at = now
+
+    def close(self) -> None:
+        with self._lock:
+            if self._fd is not None:
+                os.close(self._fd)
+                self._fd = None
+
+    def __enter__(self) -> EventWriter:
+        return self
+
+    def __exit__(self, *exc_info: object) -> None:
+        self.close()
+
+
+def _ends_mid_record(path: Path) -> bool:
+    """True when the feed exists, is non-empty, and its last byte is not a newline.
+
+    The size comes off the same descriptor the seek uses, rather than off a ``stat`` of the name
+    followed by an open of the name: the second look is the one another local user gets to answer.
+    """
+
+    try:
+        with os.fdopen(open_regular_file(path), "rb") as handle:
+            size = os.fstat(handle.fileno()).st_size
+            if size == 0:
+                return False
+            handle.seek(size - 1)
+            return handle.read(1) != b"\n"
+    except OSError:
+        return False
+
+
+def _dumps(payload: Mapping[str, Any]) -> str:
+    return json.dumps(
+        payload, ensure_ascii=True, allow_nan=False, sort_keys=True, separators=(",", ":")
+    )
+
+
+def read_feed(path: str | os.PathLike[str]) -> list[dict[str, Any]]:
+    """Read a feed. This is the untrusted-input boundary: it never raises for a malformed feed.
+
+    A missing file, a directory, an oversized file, an absent or foreign header -- each reads back
+    as no feed at all. A feed is ignored WHOLE or understood; it is never half-understood. A
+    trailing line with no newline is the torn record a concurrent writer is mid-way through, and it
+    is dropped rather than parsed.
+
+    ``read_feed`` deliberately does NOT call ``validate_facts``. A reader that refused a record
+    because its keys drifted would turn a producer bug into a blank page; the reader's job is to
+    show whatever the feed safely said, and the fact spec is enforced where the record is written.
+
+    An empty result is TWO states, and a reader that must tell them apart asks ``feed_is_readable``.
+    """
+
+    return _read_feed_parts(path)[1]
+
+
+def feed_is_readable(path: str | os.PathLike[str]) -> bool:
+    """Whether these bytes read back AS one of our feeds, however little the feed says.
+
+    ``read_feed`` returns ``[]`` for two states a reader must never confuse.
+
+    BYTES THAT ARE NOT A FEED read as nothing: a missing or oversized file, a foreign or absent
+    header, a first line still being written. A reader should disbelieve them and keep whatever it
+    last understood.
+
+    AN ATTEMPT THAT NARRATED NOTHING is a perfectly good feed that has no records yet, or will never
+    have any. It is the routine product of an idempotent re-run -- ``mr-data run`` on an
+    already-built workspace returns the existing result without rebuilding, so it arms a feed and
+    writes only the header -- and it is also every armed feed for the instant before its first
+    record. Treating it as unreadable bytes made a completed, verifying run render as though nothing
+    had happened: a header-only file never changes size, so a watcher that memoised it as corrupt
+    blocked the receipts fallback -- the one that makes deleting a feed cost nothing but the show --
+    for the rest of the server's life.
+    """
+
+    return _read_feed_parts(path)[0]
+
+
+def _read_feed_parts(path: str | os.PathLike[str]) -> tuple[bool, list[dict[str, Any]]]:
+    """``(these bytes are one of our feeds, the records they carry)``. Never raises."""
+
+    # ONE open, through the descriptor-checked helper. This used to be `stat`, then
+    # `os.path.isfile`, then `Path.read_bytes` -- three separate looks at one name, the last of them
+    # a blocking open. A local user swapping a FIFO in between the check and the read parked the
+    # watcher's poll thread forever, four times a second's worth of chances to win the race, while
+    # the server kept serving a snapshot that could never change again.
+    try:
+        payload = read_regular_bytes(Path(path), max_bytes=MAX_FEED_BYTES)
+    except OSError:
+        return False, []
+
+    text = payload.decode("utf-8", "replace")
+    if not text:
+        return False, []
+    if text.endswith("\n"):
+        lines = text[:-1].split("\n")
+    else:
+        # The final line has no newline: it is torn, and the whole recovery rule is to drop it.
+        lines = text.split("\n")[:-1]
+    if not lines:
+        return False, []
+
+    if not _header_is_ours(lines[0]):
+        return False, []
+
+    records: list[dict[str, Any]] = []
+    for line in lines[1:]:
+        if len(records) >= MAX_FEED_RECORDS:
+            break
+        record = _read_record(line)
+        if record is not None:
+            records.append(record)
+    return True, records
+
+
+def select_narrated_feed(
+    feed_dir: str | os.PathLike[str],
+    *,
+    sealed_candidate_digest: str | None = None,
+) -> tuple[Path | None, int, list[dict[str, Any]]]:
+    """Select one attempt as ``(path, size, records)``.
+
+    A matching sealed digest wins. Otherwise, finished attempts that did not produce the sealed
+    Build are ignored, and the newest nonempty active attempt is selected. At most
+    ``MAX_FEED_ATTEMPTS`` nonempty files are considered. If only an unreadable or empty file exists,
+    the newest path is returned with no records so the caller can report it.
+    """
+
+    found: list[tuple[float, str, int]] = []
+    newest_empty: tuple[float, str, int] | None = None
+    try:
+        with os.scandir(feed_dir) as entries:
+            for entry in entries:
+                if not entry.name.endswith(".jsonl"):
+                    continue
+                try:
+                    # follow_symlinks=False: another local user may have pointed a name here.
+                    info = entry.stat(follow_symlinks=False)
+                except OSError:
+                    continue
+                if not stat.S_ISREG(info.st_mode):
+                    # THIS IS A SORT, NOT A GUARD. It picks which names are worth reading and
+                    # gathers the mtime they are ordered by; it says nothing about what the name
+                    # will mean when `read_feed` below opens it. Reading it as protection is how
+                    # the blocking open under it went unnoticed -- the open itself is what has to
+                    # be safe, and `open_regular_file` is what makes it so.
+                    continue
+                candidate = (info.st_mtime, entry.name, info.st_size)
+                if info.st_size == _empty_attempt_size(entry.name):
+                    # Empty no-op invocations do not use nonempty-attempt slots, so idempotent
+                    # re-runs cannot evict the attempt that sealed the candidate.
+                    if newest_empty is None or candidate > newest_empty:
+                        newest_empty = candidate
+                    continue
+                # Bound the set while scanning. A min-heap of ``MAX_FEED_ATTEMPTS`` keeps the newest
+                # files regardless of the order the directory
+                # yields its names in, so neither the list nor the reads below it grow with the
+                # number of files somebody put here. Appending first and truncating after would
+                # have bounded the reads and not the scan.
+                if len(found) < MAX_FEED_ATTEMPTS:
+                    heapq.heappush(found, candidate)
+                else:
+                    heapq.heappushpop(found, candidate)
+    except OSError:
+        return None, 0, []
+    if not found and newest_empty is None:
+        return None, 0, []
+
+    found.sort(reverse=True)
+    base = Path(feed_dir)
+    narrated: tuple[Path, int, list[dict[str, Any]]] | None = None
+    narrating: tuple[Path, int, list[dict[str, Any]]] | None = None
+    matching: tuple[Path, int, list[dict[str, Any]]] | None = None
+    narrating_precedes_match = False
+    for _mtime, name, size in found:
+        records = read_feed(base / name)
+        if not records:
+            continue
+        candidate = (base / name, size, records)
+        if (
+            matching is None
+            and sealed_candidate_digest is not None
+            and _sealed(records) == sealed_candidate_digest
+        ):
+            matching = candidate
+            narrating_precedes_match = narrating is not None
+        if narrated is None:
+            narrated = candidate
+        if narrating is None and not _finished(records):
+            narrating = candidate
+    if sealed_candidate_digest is not None:
+        # A newer unfinished attempt is a retry narrating work after the retained matching seal.
+        # Return it so the consumer can validate its own ``run_started`` and enforce monotonic
+        # attempt replacement. Otherwise the matching seal remains the candidate's narration.
+        if narrating is not None and (matching is None or narrating_precedes_match):
+            return narrating
+        return matching if matching is not None else (None, 0, [])
+    if narrated is not None:
+        return narrated
+    if found:
+        _mtime, name, size = found[0]
+    else:
+        assert newest_empty is not None
+        _mtime, name, size = newest_empty
+    return base / name, size, []
+
+
+def _finished(records: Sequence[Mapping[str, Any]]) -> bool:
+    """Return whether this attempt sealed, stopped, or closed a sidecar-only invocation."""
+
+    if _sealed(records) is not None:
+        return True
+    return records[-1].get("event") in (TERMINAL_EVENT_NAMES | NOTEBOOK_SIDECAR_OUTCOME_EVENT_NAMES)
+
+
+def _sealed(records: Sequence[Mapping[str, Any]]) -> str | None:
+    """The candidate digest this attempt sealed, or ``None`` if it sealed nothing."""
+
+    for record in reversed(records):
+        if record.get("event") != "build_sealed":
+            continue
+        facts = record.get("facts")
+        digest = facts.get("candidate_digest") if isinstance(facts, Mapping) else None
+        return digest if isinstance(digest, str) else None
+    return None
+
+
+def _header_is_ours(line: str) -> bool:
+    try:
+        header = json.loads(line)
+    except (ValueError, RecursionError):
+        return False
+    return (
+        isinstance(header, dict)
+        and header.get("kind") == "header"
+        and header.get("schema_version") == FEED_SCHEMA_VERSION
+    )
+
+
+def _read_record(line: str) -> dict[str, Any] | None:
+    if not line:
+        return None
+    try:
+        parsed = json.loads(line)
+    except (ValueError, RecursionError):
+        return None
+    if not isinstance(parsed, dict) or set(parsed) != set(_RECORD_KEYS):
+        return None
+
+    seq = parsed["seq"]
+    at = parsed["at"]
+    event = parsed["event"]
+    facts = parsed["facts"]
+    evidence = parsed["evidence"]
+    if isinstance(seq, bool) or not isinstance(seq, int):
+        return None
+    if isinstance(at, bool) or not isinstance(at, (int, float)):
+        return None
+    try:
+        moment = float(at)
+    except (OverflowError, ValueError):
+        # Convert once and drop values that cannot be represented as floats.
+        return None
+    if not _EARLIEST_MOMENT <= moment <= _LATEST_MOMENT:
+        # A MOMENT ON A CLOCK, not merely a finite float, and the difference between those two
+        # questions is a permanent stall. `json.loads` accepts the bare tokens `Infinity`,
+        # `-Infinity` and `NaN`, and it accepts `1.7e308` -- which is finite, is genuinely a float,
+        # and is not a time. Every reader of this record subtracts one moment from another and
+        # converts the difference to an integer: `watch._render_header` does it against the wall
+        # clock, and `watch._render_log` does it against the FIRST record's moment, which is the
+        # one that matters here. Two admitted records at opposite ends of the float range make
+        # that subtraction overflow to `inf`, and `int(inf)` raises. A finiteness test cannot see
+        # it, because both operands are finite; only a bound on the value can.
+        #
+        # However it arrives -- a token that is not a number, an integer no float can hold, or a
+        # float no clock can name -- the cost used to be the whole view for the life of the
+        # server: the watcher counted a failed poll, spliced the stall note onto the last good page
+        # and never rendered another record, and no `except` downstream could give the page back
+        # because the poisoned record was still in the feed on every subsequent read. `mr-data
+        # fleet` had it worse: `scan_fleet` reads every child's feed through this same boundary and
+        # catches only `OSError`, so one poisoned line in one run's feed ended the whole scan with a
+        # traceback and no rows at all, for every other run in the directory.
+        #
+        # This is the boundary that exists to stop that. A record whose `at` is not a moment this
+        # reader can carry is dropped here, the same way a record whose `at` is a string is dropped,
+        # and the rest of the feed is read normally -- one bad line costs that line and never the
+        # view. A guard in the renderers would have been a second place that has to know this rule,
+        # and each renderer would have had to know it about PAIRS of records rather than about one.
+        return None
+    if not isinstance(event, str) or not isinstance(facts, dict):
+        return None
+    if evidence is not None:
+        if not isinstance(evidence, dict) or set(evidence) != set(_EVIDENCE_KEYS):
+            return None
+        if not isinstance(evidence["member"], str) or not isinstance(evidence["sha256"], str):
+            return None
+
+    clamped_facts = {
+        # The KEY crosses the same boundary as the value. `json.loads` puts a lone surrogate in a
+        # key as readily as in a string, and every surface that re-encodes the record encodes both.
+        _clamp_text(key): _clamp(value)
+        for key, value in list(facts.items())[:MAX_FACT_KEYS]
+        if isinstance(key, str)
+    }
+    clamped_evidence = None if evidence is None else {k: _clamp(v) for k, v in evidence.items()}
+    return {
+        "seq": seq,
+        "at": moment,
+        "event": _clamp_text(event),
+        "facts": clamped_facts,
+        "evidence": clamped_evidence,
+    }
+
+
+def writable_text(value: str) -> str:
+    """Return UTF-8-encodable text, escaping lone surrogates as ASCII byte sequences.
+
+    Escaping occurs before length clamping so the result remains within the text ceiling.
+    """
+
+    try:
+        value.encode("utf-8")
+    except UnicodeEncodeError:
+        return value.encode("utf-8", "backslashreplace").decode("ascii")
+    return value
+
+
+def _clamp_text(value: str) -> str:
+    value = writable_text(value)
+    if len(value) <= MAX_TEXT_CHARS:
+        return value
+    return value[: MAX_TEXT_CHARS - len(_TRUNCATION_MARKER)] + _TRUNCATION_MARKER
+
+
+def _clamp(value: Any, depth: int = 0) -> Any:
+    if isinstance(value, str):
+        return _clamp_text(value)
+    if depth >= _MAX_FACT_DEPTH:
+        return None
+    if isinstance(value, dict):
+        return {
+            _clamp_text(key): _clamp(inner, depth + 1)
+            for key, inner in list(value.items())[:MAX_FACT_KEYS]
+            if isinstance(key, str)
+        }
+    if isinstance(value, list):
+        return [_clamp(item, depth + 1) for item in value[:_MAX_LIST_ITEMS]]
+    if isinstance(value, float) and not math.isfinite(value):
+        # A FACT VALUE THAT CANNOT BE WRITTEN DOWN AGAIN. `json.loads` accepts the bare tokens
+        # `Infinity`, `-Infinity` and `NaN` anywhere a number may appear, and every surface that
+        # hands a record on re-serializes it with `allow_nan=False`: `_dumps` here, and
+        # `cli._emit`. `mr-data status --events` therefore died with an uncaught
+        # `ValueError: Out of range float values are not JSON compliant: inf` -- `_main`'s except
+        # tuple lists `json.JSONDecodeError` and not bare `ValueError`, so it left a traceback,
+        # no output, and no records for ANY event. The record stays in the feed, so every later
+        # invocation died the same way: one appended line cost that surface for good.
+        #
+        # The bound belongs here for the same reason the bound on `at` does. This is the one
+        # boundary that decides what a record may carry, the writer already refuses these values
+        # at the matching boundary (`_normalize_json` raises on a non-finite fact), and a
+        # `try/except` at the CLI would have been a second place that has to know the rule --
+        # one per surface, each of them a chance to miss it, as `fleet` and `render_page`
+        # surviving this same line while `status --events` did not already showed.
+        #
+        # Nulled rather than dropping the whole record, because that is what every other bound in
+        # this function does to a value it cannot carry: text over `MAX_TEXT_CHARS` is truncated,
+        # keys past `MAX_FACT_KEYS` are left out, and a value nested past `_MAX_FACT_DEPTH`
+        # already becomes exactly this `None`. `at` is structural -- every consumer subtracts it,
+        # so a record without a moment is not a record -- while a fact is payload, and the seq,
+        # moment and event name beside it are still true.
+        return None
+    return value
+
+
+# --------------------------------------------------------------------------------------------
+# The byte-neutral instrumentation sink
+# --------------------------------------------------------------------------------------------
+
+EventSink = Callable[[str, Mapping[str, Any], Mapping[str, Any] | None], None]
+
+# Why a ContextVar and not a parameter: threading a sink through `build_candidate` ->
+# `_replay_candidate_derivations` -> `_create_and_seal_candidate` -> `verify_candidate` ->
+# `_read_sealed_candidate_tree` would change five signatures on the most security-sensitive path in
+# the tree, for a feature that emits no bytes into anything those functions produce. A context also
+# gives the isolation the hosted case needs: a thread starts from an empty or explicitly copied
+# context, so one worker's build can never write another worker's feed.
+_EVENTS: ContextVar[EventSink | None] = ContextVar("mostlyright_run_events", default=None)
+
+
+def emit(
+    event: str,
+    facts: Mapping[str, Any],
+    evidence: Mapping[str, Any] | None = None,
+) -> None:
+    """Emit one derived event. Reads nothing, hashes nothing, and returns nothing.
+
+    With no sink armed this is a ContextVar read and a return -- the build path pays nothing. The
+    result of an ``emit`` reaches no member, no manifest and no digest (G1); a call site is a
+    statement, never an expression whose value is used.
+
+    On ANY exception from the sink the sink is DISARMED for the rest of the arming context rather
+    than retried. A failed event sink must not affect the Build.
+
+    A consequence worth knowing before debugging one: a producer whose facts drift from
+    ``EVENT_FACTS`` raises inside ``EventWriter.write``, which this function catches, which
+    therefore disarms the feed for the rest of the run. That is deliberate -- a feed missing its
+    tail is a loud failure, while a feed carrying a wrong fact set would be a quiet one -- but it
+    means a drifted producer shows up as a TRUNCATED feed. Look for a ``validate_facts``
+    ``ValueError`` first.
+    """
+
+    sink = _EVENTS.get()
+    if sink is None:
+        return None
+    try:
+        sink(event, facts, evidence)
+    except Exception:
+        _EVENTS.set(None)
+    return None
+
+
+@contextlib.contextmanager
+def sink_disabled() -> Iterator[None]:
+    """Suppress events inside the block and restore the previous sink on exit.
+
+    This exists for the candidate verify path: it re-derives every member from the sealed bytes,
+    and a re-derivation is not the build. Emitting it would double every parse, clean, join and
+    check event in the feed -- the viewer would show the run happening twice.
+    """
+
+    token = _EVENTS.set(None)
+    try:
+        yield
+    finally:
+        _EVENTS.reset(token)
+
+
+@contextlib.contextmanager
+def observer(watcher: EventSink) -> Iterator[None]:
+    """Arm ``watcher`` alongside whatever sink is already armed, for the duration of the block.
+
+    This is a SEAM, not a vocabulary change. It adds no name, no fact key and no record shape, and
+    it cannot make an unsealed fact reach the feed: a watcher is only ever CALLED with records the
+    build already emitted, and its return value is discarded. The seam exists so a second, avowedly
+    unsealed consumer -- `progress_events`, whose module docstring states the boundary -- can watch
+    a build in flight without either vocabulary learning about the other.
+
+    Composition, not replacement. The previous sink stays armed and is called FIRST, so a watcher
+    can never cost the feed a record; a watcher that raises is caught here and disarms nothing,
+    because ``emit`` disarms the whole sink on an exception and one broken watcher must not silence
+    the feed. The pairing with ``sink_disabled`` is the one that matters on the verify path: a
+    re-derivation suppresses the sink, so a watcher installed through this seam sees the build once,
+    exactly like the feed does.
+    """
+
+    previous = _EVENTS.get()
+
+    def _both(
+        event: str, facts: Mapping[str, Any], evidence: Mapping[str, Any] | None = None
+    ) -> None:
+        if previous is not None:
+            previous(event, facts, evidence)
+        try:
+            watcher(event, facts, evidence)
+        except Exception:
+            return None
+        return None
+
+    token = _EVENTS.set(_both)
+    try:
+        yield
+    finally:
+        _EVENTS.reset(token)
+
+
+@contextlib.contextmanager
+def event_sink(path: str | os.PathLike[str], *, producer_attempt: str) -> Iterator[EventWriter]:
+    """Arm the feed for the duration of one build attempt and close it with a terminal record.
+
+    Terminal-record rules -- this is the answer to "watching a failed build shows nothing":
+
+    * a clean exit writes nothing extra, because the build already emitted ``build_sealed``;
+    * ``KeyboardInterrupt`` or ``SystemExit`` writes one ``run_interrupted``;
+    * any other exception writes one ``build_failed`` carrying the exception's ``finding_id`` and
+      ``severity`` when it has them.
+
+    Those key sets are the ``EVENT_FACTS`` entries for the two terminal events, so the exit path is
+    validated by the same spec as every other record. The context manager NEVER suppresses the
+    exception, and every write on the exit path is wrapped so a failing feed cannot mask the real
+    error.
+    """
+
+    writer = EventWriter(path, run=producer_attempt)
+
+    def _sink(
+        event: str, facts: Mapping[str, Any], evidence: Mapping[str, Any] | None = None
+    ) -> None:
+        """Write one record; a record that named a place costs that record and nothing more.
+
+        ``emit`` disarms the sink on any exception, which is right for a producer whose fact keys
+        drifted and wrong for a fact that merely carried a path: one such string must not drop
+        later records or the terminal record. The
+        location refusal is handled HERE, before it can reach ``emit``: the record is rewritten
+        with its offending tokens redacted, and if even that is refused the record alone is
+        dropped. The sink stays armed either way.
+
+        Unwritable text takes the same route for the same reason. A filename carrying invalid
+        UTF-8 reaches a fact through ``surrogateescape`` with no attacker anywhere -- the producer
+        writes it itself -- so the value is repaired through ``writable_text`` and the record is
+        kept. Only the string changes; the fact it states is unchanged.
+        """
+
+        try:
+            writer.write(event, facts, evidence)
+        except (PlaceNamedError, UnwritableTextError):
+            # ONE retry carrying BOTH repairs, in the order that composes: text is made writable
+            # first, then places are redacted out of it. Two separate retries would have dropped a
+            # record that needed both -- and a message built from an undecodable filename is
+            # exactly a message that also carries a path.
+            try:
+                writer.write(event, _redact_places(_repair_text(facts)), evidence)
+            except ValueError:
+                return None
+        return None
+
+    token = _EVENTS.set(_sink)
+    try:
+        yield writer
+    except (KeyboardInterrupt, SystemExit):
+        _write_terminal(writer, "run_interrupted", {})
+        raise
+    except BaseException as exc:
+        finding_id = getattr(exc, "finding_id", None)
+        _write_terminal(
+            writer,
+            "build_failed",
+            {
+                "finding_id": None if finding_id is None else _clamp_text(str(finding_id)),
+                "severity": _clamp_text(str(getattr(exc, "severity", "blocker"))),
+                "message": _clamp_text(str(exc)),
+            },
+        )
+        raise
+    finally:
+        _EVENTS.reset(token)
+        try:
+            writer.close()
+        except Exception:  # pragma: no cover - closing a descriptor twice is the only shape here
+            pass
+
+
+_WITHHELD = "withheld: it named a location"
+# What one refused token becomes. A whole message replaced by `_WITHHELD` reads as a hole; the
+# sentence around the path is the half a reader needs -- "output already exists: (a location on
+# this machine)" says what went wrong, and says it identically from every machine.
+_PLACE_PLACEHOLDER = "(a location on this machine)"
+
+
+def _redact_place_text(key: str, text: str) -> str:
+    """Return ``text`` with every token the location guard refuses replaced, or ``_WITHHELD``.
+
+    Token-wise, so the prose survives and only the place is lost. If what remains still names a
+    place -- this host's name spelled inside a word, for instance -- the whole string is withheld
+    rather than half-cleaned: a partial redaction that still leaks is worse than a blank.
+    """
+
+    rebuilt: list[str] = []
+    for chunk in re.split(r"(\s+)", text):
+        if not chunk or chunk.isspace():
+            rebuilt.append(chunk)
+            continue
+        try:
+            _require_placeless(key, chunk)
+        except PlaceNamedError:
+            rebuilt.append(_PLACE_PLACEHOLDER)
+        else:
+            rebuilt.append(chunk)
+    result = "".join(rebuilt)
+    try:
+        _require_placeless(key, result)
+    except PlaceNamedError:
+        return _WITHHELD
+    return _clamp_text(result)
+
+
+def _repair_text(value: Any) -> Any:
+    """Recursively make every string reachable in a fact value one a surface can encode.
+
+    The mirror of ``_redact_places``, over the other refusal the writer owns. Keys are repaired
+    too: a fact KEY carrying a lone surrogate poisons ``json.dumps`` exactly as a value does.
+    """
+
+    if isinstance(value, str):
+        return writable_text(value)
+    if isinstance(value, Mapping):
+        return {
+            (writable_text(k) if isinstance(k, str) else k): _repair_text(inner)
+            for k, inner in value.items()
+        }
+    if isinstance(value, (list, tuple)):
+        return [_repair_text(item) for item in value]
+    return value
+
+
+def _redact_places(value: Any, *, key: str = "facts") -> Any:
+    """Recursively redact every place-naming string reachable in a fact value."""
+
+    if isinstance(value, str):
+        return _redact_place_text(key, value)
+    if isinstance(value, Mapping):
+        return {
+            inner_key: _redact_places(inner, key=f"{key}.{inner_key}")
+            for inner_key, inner in value.items()
+        }
+    if isinstance(value, (list, tuple)):
+        return [_redact_places(item, key=f"{key}[]") for item in value]
+    return value
+
+
+def _write_terminal(writer: EventWriter, event: str, facts: Mapping[str, Any]) -> None:
+    """Write the one terminal record, redacting rather than losing it if the guard refuses.
+
+    An exception message routinely carries a path, and a build that failed is exactly the run a
+    watcher most wants to see end. So the first attempt writes the message as it stands; if the
+    location-blind guard refuses it, the second attempt writes the same record with the offending
+    tokens replaced. Either way the feed ends with exactly one terminal record, and neither attempt
+    can raise into the real exception on its way out.
+    """
+
+    attempts: tuple[Mapping[str, Any], ...] = (facts, _redact_places(facts))
+    for attempt in attempts:
+        try:
+            writer.write(event, attempt)
+            return
+        except ValueError:
+            continue
+        except Exception:
+            return
+
+
+# --------------------------------------------------------------------------------------------
+# The post-hoc projection over a sealed run
+# --------------------------------------------------------------------------------------------
+#
+# `emit` writes records during a build. `project_sealed_run` derives the same ordered records from
+# sealed bytes. Both use `EVENT_FACTS` and `validate_facts`; derived records may differ only in
+# `at`.
+# A manifest and its evidence members are sufficient when no event feed exists.
+
+
+def project_sealed_run(
+    manifest: Mapping[str, Any],
+    member_bytes: Mapping[str, bytes],
+) -> list[dict[str, Any]]:
+    """Derive the ordered event feed for one finished run from its sealed bytes alone.
+
+    PURE. It takes the parsed ``manifest.json`` mapping and a mapping of candidate-relative member
+    path to that member's bytes, both already in memory, and it imports nothing from ``pipeline``.
+    A caller that has already done the verified read must be able to project without the candidate
+    being read a second time, and a projector that opened files itself would become exactly the
+    second reader this design refuses to grow.
+
+    Every evidence pointer resolves through ``manifest["members"]``, so a projected event physically
+    cannot cite a member the manifest does not carry. Every record passes
+    ``validate_facts`` and the location-blind guard before it is returned.
+
+    ``at`` is ``0.0`` on every record. A projection has no clock, and a clock it invented would be a
+    timestamp claiming to be an observation.
+
+    ``build_failed`` and ``run_interrupted`` are NEVER projected, and no branch here should ever add
+    them: a sealed run did not fail, and a run that was interrupted never sealed a manifest to
+    project from. Those two events exist only on the live path.
+
+    Raises ``ValueError`` when the manifest's member list is malformed, when a member the projection
+    needs was not supplied, or when a supplied member is not the JSON this projector was written
+    against. It refuses rather than returning a partial feed: a half-projection reads to a viewer
+    exactly like a run that stopped half way.
+    """
+
+    members_by_path = _manifest_members_by_path(manifest)
+    records: list[dict[str, Any]] = []
+
+    def add(
+        event: str,
+        facts: Mapping[str, Any],
+        evidence: Mapping[str, Any] | None,
+    ) -> None:
+        records.append(_projected_record(len(records) + 1, event, facts, evidence))
+
+    def pointer(member: str) -> dict[str, Any]:
+        return _pointer(members_by_path, member)
+
+    plan = _member_json(member_bytes, "plan.json")
+    source_ids = [source["id"] for source in plan["sources"]]
+
+    add(
+        "run_started",
+        {
+            "sources": list(source_ids),
+            "output_intent": plan["output_intent"],
+            "grain": list(plan["grain"]),
+            "columns": list(plan["select"]),
+            "evidence_member": EVIDENCE_MEMBER["run_started"],
+        },
+        pointer(EVIDENCE_MEMBER["run_started"]),
+    )
+
+    source_records = _member_json(member_bytes, EVIDENCE_MEMBER["rights_checked"])
+    add(
+        "rights_checked",
+        {
+            "sources": [
+                {
+                    "source_id": record["source_id"],
+                    "status": record["rights"]["status"],
+                    "permissions": list(record["rights"]["permissions"]),
+                }
+                for record in source_records
+            ],
+            "evidence_member": EVIDENCE_MEMBER["rights_checked"],
+        },
+        pointer(EVIDENCE_MEMBER["rights_checked"]),
+    )
+
+    add(
+        "sources_read_started",
+        {"total": len(plan["sources"]), "evidence_member": EVIDENCE_MEMBER["sources_read_started"]},
+        pointer(EVIDENCE_MEMBER["sources_read_started"]),
+    )
+
+    for source_id in source_ids:
+        member = source_member(source_id)
+        add(
+            "source_read",
+            {
+                "source_id": source_id,
+                # From the MANIFEST, not from the bytes in hand: the manifest entry's `bytes` is
+                # `len(member_bytes[...])` by construction at seal time, so this is the identical
+                # integer the live emitter reports, and taking it from the receipt keeps this
+                # function honest even when a caller supplied bytes it derived some other way.
+                "bytes": _manifest_entry(members_by_path, member)["bytes"],
+                "evidence_member": member,
+            },
+            pointer(member),
+        )
+
+    add(
+        "sources_parsed_started",
+        {
+            "total": len(plan["sources"]),
+            "evidence_member": EVIDENCE_MEMBER["sources_parsed_started"],
+        },
+        pointer(EVIDENCE_MEMBER["sources_parsed_started"]),
+    )
+
+    profiles = _member_json(member_bytes, EVIDENCE_MEMBER["source_parsed"])
+    for source_id in source_ids:
+        raw = profiles[source_id]["raw"]
+        add(
+            "source_parsed",
+            {
+                "source_id": source_id,
+                "rows": raw["row_count"],
+                "columns": len(raw["columns"]),
+                "evidence_member": EVIDENCE_MEMBER["source_parsed"],
+            },
+            pointer(EVIDENCE_MEMBER["source_parsed"]),
+        )
+
+    # THE ONE CONDITIONAL RECORD. Live it fires only when
+    # `package_context is not None and not allow_versioned_acquisition` -- offline runs, never
+    # recipe runs and never plain builds. The sealed equivalent of that condition is BOTH halves
+    # below: a recipe candidate seals `evidence/package.json` too, so the member's presence alone
+    # would make the projection narrate a match the live feed never claimed, and the agreement test
+    # would fail on precisely this branch.
+    #
+    # Both sides count over the PLAN's sources rather than over the proposal list, so a package
+    # whose proposals are a superset of the plan cannot make the two disagree. The sealed key is
+    # `evidence_sha256s`; `content_sha256` is the in-memory `SourceProposal` spelling of the same
+    # values -- the same situation as `source`/`source_id` on `cleaning_applied`.
+    matched_member = EVIDENCE_MEMBER["evidence_matched"]
+    if (
+        matched_member in members_by_path
+        and manifest.get("manifest_version") != _RECIPE_MANIFEST_VERSION
+    ):
+        package = _member_json(member_bytes, matched_member)
+        cited_by_source = {
+            proposal["source_id"]: set(proposal["evidence_sha256s"])
+            for proposal in package["source_proposals"]
+        }
+        matched = sum(
+            1
+            for source_id in source_ids
+            if _manifest_entry(members_by_path, source_member(source_id))["sha256"]
+            in cited_by_source.get(source_id, frozenset())
+        )
+        add(
+            "evidence_matched",
+            {
+                "matched": matched,
+                "total": len(plan["sources"]),
+                "evidence_member": matched_member,
+            },
+            pointer(matched_member),
+        )
+
+    cleaning = plan["cleaning"]
+    add(
+        "cleaning_started",
+        {"total": len(cleaning), "evidence_member": EVIDENCE_MEMBER["cleaning_started"]},
+        pointer(EVIDENCE_MEMBER["cleaning_started"]),
+    )
+    for index, step in enumerate(cleaning, start=1):
+        add(
+            "cleaning_applied",
+            {
+                "step_index": index,
+                "step_total": len(cleaning),
+                # The sealed key is `source`; the parsed dataclass attribute the live emitter reads
+                # is `source_id`. Same value, two spellings, and this is the sealed side.
+                "source_id": step["source"],
+                "operation": step["operation"],
+                "evidence_member": EVIDENCE_MEMBER["cleaning_applied"],
+            },
+            pointer(EVIDENCE_MEMBER["cleaning_applied"]),
+        )
+
+    # The `cleaned` stage of the same member `source_parsed` read the `raw` stage of. Cleaning may
+    # add or drop columns, so this is the count AFTER the steps above, not before them.
+    add(
+        "sources_profiled",
+        {
+            "sources": len(plan["sources"]),
+            "columns": sum(
+                len(profiles[source_id]["cleaned"]["columns"]) for source_id in source_ids
+            ),
+            "evidence_member": EVIDENCE_MEMBER["sources_profiled"],
+        },
+        pointer(EVIDENCE_MEMBER["sources_profiled"]),
+    )
+
+    join = _member_json(member_bytes, EVIDENCE_MEMBER["join_completed"])
+    join_facts = {
+        key: join[key] for key in EVENT_FACTS["join_completed"] if key != "evidence_member"
+    }
+    join_facts["evidence_member"] = EVIDENCE_MEMBER["join_completed"]
+    add("join_completed", join_facts, pointer(EVIDENCE_MEMBER["join_completed"]))
+
+    profile = _member_json(member_bytes, EVIDENCE_MEMBER["rows_selected"])
+    add(
+        "rows_selected",
+        {
+            "rows": profile["row_count"],
+            "columns": len(plan["select"]),
+            "evidence_member": EVIDENCE_MEMBER["rows_selected"],
+        },
+        pointer(EVIDENCE_MEMBER["rows_selected"]),
+    )
+
+    quality = _member_json(member_bytes, EVIDENCE_MEMBER["checks_completed"])
+    checks = quality["checks"]
+    # The live emitter cannot count this member -- it does not exist yet -- so it computes the same
+    # total from the plan: `2 + len(grain) + len(quality.not_null)`. The identity of those two
+    # numbers is pinned by its own test, because a drift there fails the agreement test with a
+    # message about a count rather than about the formula that produced it.
+    add(
+        "checks_started",
+        {"total": len(checks), "evidence_member": EVIDENCE_MEMBER["checks_started"]},
+        pointer(EVIDENCE_MEMBER["checks_started"]),
+    )
+    for index, check in enumerate(checks, start=1):
+        add(
+            "check_completed",
+            {
+                "check_id": check["check_id"],
+                "index": index,
+                "total": len(checks),
+                "evidence_member": EVIDENCE_MEMBER["check_completed"],
+            },
+            pointer(EVIDENCE_MEMBER["check_completed"]),
+        )
+    add(
+        "checks_completed",
+        {
+            # `passed` equals `total` on every sealed run, because `_validate_output` raises on the
+            # first failed check. Counting rather than asserting is deliberate: the count is what
+            # the member says, and a projector that hardcoded the equality would be asserting a
+            # pipeline invariant instead of reading evidence.
+            "passed": sum(1 for check in checks if check["passed"] is True),
+            "total": len(checks),
+            "evidence_member": EVIDENCE_MEMBER["checks_completed"],
+        },
+        pointer(EVIDENCE_MEMBER["checks_completed"]),
+    )
+
+    # `profile` was read above for `rows_selected`; both records state numbers out of the one member
+    # that carries them.
+    add(
+        "table_written",
+        {
+            "rows": profile["row_count"],
+            "columns": len(profile["columns"]),
+            "evidence_member": EVIDENCE_MEMBER["table_written"],
+        },
+        pointer(EVIDENCE_MEMBER["table_written"]),
+    )
+
+    add(
+        "members_sealed_started",
+        {
+            "total": len(members_by_path),
+            "evidence_member": EVIDENCE_MEMBER["members_sealed_started"],
+        },
+        pointer(EVIDENCE_MEMBER["members_sealed_started"]),
+    )
+    for member in sorted(members_by_path):
+        entry = members_by_path[member]
+        add(
+            "member_sealed",
+            {"bytes": entry["bytes"]},
+            {"member": member, "sha256": entry["sha256"]},
+        )
+
+    # A pure sum over the member table. Nothing here is hashed and nothing is opened: a fact is a
+    # read of a value the seal already computed, which is what keeps the feed digest-neutral (G1).
+    add(
+        "candidate_installed",
+        {
+            "members": len(members_by_path),
+            "bytes": sum(entry["bytes"] for entry in members_by_path.values()),
+            "evidence_member": EVIDENCE_MEMBER["candidate_installed"],
+        },
+        pointer(EVIDENCE_MEMBER["candidate_installed"]),
+    )
+
+    add(
+        "snapshot_verify_started",
+        {
+            "total": len(members_by_path),
+            "evidence_member": EVIDENCE_MEMBER["snapshot_verify_started"],
+        },
+        pointer(EVIDENCE_MEMBER["snapshot_verify_started"]),
+    )
+    # Sorted by member path, exactly as `member_sealed` is, so the two halves of the receipt read in
+    # the same order on both producers.
+    for member in sorted(members_by_path):
+        entry = members_by_path[member]
+        add(
+            "member_verified",
+            {"bytes": entry["bytes"]},
+            {"member": member, "sha256": entry["sha256"]},
+        )
+    add(
+        "snapshot_verified",
+        {
+            "members": len(members_by_path),
+            "table_sha256": manifest["table_sha256"],
+            "evidence_member": EVIDENCE_MEMBER["snapshot_verified"],
+        },
+        pointer(EVIDENCE_MEMBER["snapshot_verified"]),
+    )
+
+    add(
+        "build_sealed",
+        {
+            "candidate_digest": manifest["candidate_digest"],
+            "table_sha256": manifest["table_sha256"],
+            "manifest_version": manifest["manifest_version"],
+            "row_count": profile["row_count"],
+        },
+        # The one record with no pointer: a candidate digest is not a member of anything.
+        None,
+    )
+
+    return records
+
+
+def rederive_feed(
+    run_dir: str | os.PathLike[str],
+    *,
+    pinned_candidate_fd: int | None = None,
+) -> list[dict[str, Any]]:
+    """Return a feed projected from a retained, verified sealed-run snapshot.
+
+    Three controls bind the projection to verified bytes:
+
+    * ``verify_candidate`` is called with ``_retained_leases``, so the descriptors it proved the
+      run through stay OPEN across this whole function instead of closing at its return. Every
+      member below is read relative to that retained candidate descriptor -- ``run_dir`` is never
+      walked again, so the candidate directory cannot be replaced underneath the read.
+    * The manifest is NOT re-read. ``VerifiedCandidate.manifest`` is the mapping the verify proved,
+      so the byte counts and digests every member is checked against come from the proof rather
+      than from a file an attacker may have rewritten since.
+    * Each member's bytes are hashed and compared to that proved digest before anything is
+      projected. A descriptor-relative open still resolves a NAME inside the pinned directory, so
+      retention alone proves where the read went, not what it found; the digest is what proves the
+      content. A single mismatch refuses the complete projection.
+
+    ``lease.validate()`` then re-checks the retained roots at the linearization point the pipeline
+    designed it for, and the lease is closed on every path out.
+
+    Retention pins the read but not the caller's expected subject. It starts at the
+    ``candidate`` name this call resolves, so the answer is about whichever directory sat at that
+    name at that instant -- internally consistent, and not necessarily the run a long-lived reader
+    thinks it is watching. A watcher that holds its own descriptor on the candidate and measures
+    anything against it is therefore asking about one directory and being answered about another,
+    ``pinned_candidate_fd`` binds that subject: pass the expected descriptor, and verification of
+    any other directory raises. Identity is
+    compared through ``fstat`` on two OPEN descriptors, so neither can be renamed out from under
+    the comparison, and an inode cannot be reused while a descriptor holds it -- equal ``(st_dev,
+    st_ino)`` is the same directory, not a directory with the same name.
+
+    Raises whatever ``verify_candidate`` raises for a run that is missing, malformed or tampered,
+    ``ValueError`` for a member whose bytes are not the ones the manifest records or for a
+    candidate that is not the pinned one, and ``OSError`` for a member that is absent or is not a
+    regular file. It never returns an empty list for a run it could not read: a viewer renders an
+    empty feed as "nothing happened", and "I could not verify this" is not "nothing happened".
+    """
+
+    # Deferred on purpose. `pipeline` imports this module for the emission seam, so a module-level
+    # import here would close a cycle; it also keeps `events` loadable with zero harness
+    # dependencies for the writer and reader paths, which is asserted by a test.
+    from mostlyright.data_harness.pipeline import verify_candidate
+
+    run = Path(run_dir)
+    leases: list[Any] = []
+    verified = verify_candidate(run, _retained_leases=leases)
+    if not leases:  # pragma: no cover - developer invariant
+        raise ValueError("the verify returned no retained candidate snapshot to project from")
+    lease = leases[0]
+    try:
+        if pinned_candidate_fd is not None:
+            _require_pinned_candidate(pinned_candidate_fd, lease.candidate_fd)
+        manifest = verified.manifest
+        member_bytes = _read_proved_members(lease.candidate_fd, manifest)
+        lease.validate()
+    finally:
+        lease.close()
+    return project_sealed_run(manifest, member_bytes)
+
+
+def _require_pinned_candidate(pinned_fd: int, proved_fd: int) -> None:
+    """Refuse a projection that is about a directory other than the caller's pinned candidate.
+
+    Checked BEFORE a single member is read, so a decoy's bytes are never loaded, let alone
+    projected. Both arguments are open descriptors: ``fstat`` on an open descriptor answers about
+    the object itself rather than about a name, so nothing here can be raced by a rename.
+    """
+
+    pinned = os.fstat(pinned_fd)
+    proved = os.fstat(proved_fd)
+    if (pinned.st_dev, pinned.st_ino) != (proved.st_dev, proved.st_ino):
+        raise ValueError(
+            "the candidate this run verified is not the candidate directory this reader pinned"
+        )
+
+
+def _read_proved_members(candidate_fd: int, manifest: Mapping[str, Any]) -> dict[str, bytes]:
+    """Read every member under the verify's own candidate descriptor, pinned to its proved digest.
+
+    ``candidate_fd`` is the descriptor ``verify_candidate`` retained, so nothing here resolves a
+    path from the run directory. The byte count and digest come from the manifest the verify
+    proved. Any member that does not hash to it raises, and the caller has nothing to project.
+    """
+
+    members_by_path = _manifest_members_by_path(manifest)
+    member_bytes: dict[str, bytes] = {}
+    for member, entry in members_by_path.items():
+        # The member paths were just verified, but they are still strings out of a file: resolving
+        # one into a name without re-checking its shape is how a traversal gets a second chance.
+        _require_member_path(member, "manifest member path")
+        recorded_bytes = entry["bytes"]
+        recorded_digest = entry["sha256"]
+        if type(recorded_bytes) is not int or recorded_bytes < 0:
+            raise ValueError(f"manifest member {member!r} records no byte count")
+        if not isinstance(recorded_digest, str) or not _SHA256_RE.match(recorded_digest):
+            raise ValueError(f"manifest member {member!r} records no sha256 digest")
+        raw = read_regular_bytes(member, dir_fd=candidate_fd, max_bytes=recorded_bytes)
+        if len(raw) != recorded_bytes or hashlib.sha256(raw).hexdigest() != recorded_digest:
+            raise ValueError(f"member {member!r} is not the bytes this run's manifest records")
+        member_bytes[member] = raw
+    return member_bytes
+
+
+def _manifest_members_by_path(manifest: Mapping[str, Any]) -> dict[str, dict[str, Any]]:
+    """Return the manifest's member table keyed by path, or raise ``ValueError``."""
+
+    if not isinstance(manifest, Mapping):
+        raise ValueError("manifest is not a mapping")
+    members = manifest.get("members")
+    if not isinstance(members, list):
+        raise ValueError("manifest carries no members list")
+    by_path: dict[str, dict[str, Any]] = {}
+    for entry in members:
+        if not isinstance(entry, Mapping):
+            raise ValueError(f"manifest member entry is not a mapping: {type(entry).__name__}")
+        missing = [key for key in ("path", "bytes", "sha256") if key not in entry]
+        if missing:
+            raise ValueError(f"manifest member entry is missing {missing}")
+        path = entry["path"]
+        if not isinstance(path, str):
+            raise ValueError(f"manifest member path is not a string: {path!r}")
+        by_path[path] = dict(entry)
+    if not by_path:
+        raise ValueError("manifest carries no members")
+    return by_path
+
+
+def _manifest_entry(
+    members_by_path: Mapping[str, Mapping[str, Any]], member: str
+) -> Mapping[str, Any]:
+    entry = members_by_path.get(member)
+    if entry is None:
+        raise ValueError(f"the manifest carries no member {member!r} for this event's evidence")
+    return entry
+
+
+def _pointer(members_by_path: Mapping[str, Mapping[str, Any]], member: str) -> dict[str, Any]:
+    """Resolve one evidence pointer through the manifest, or raise.
+
+    The projection discharges its evidence-binding and portability invariants by construction: a
+    projected event cannot name a member the manifest does not carry, and the digest it reports is
+    the one the seal recorded, never one this function computed.
+    """
+
+    return {"member": member, "sha256": _manifest_entry(members_by_path, member)["sha256"]}
+
+
+def _projected_record(
+    seq: int,
+    event: str,
+    facts: Mapping[str, Any],
+    evidence: Mapping[str, Any] | None,
+) -> dict[str, Any]:
+    """Build one record through the same two gates the writer applies. One helper, one gate.
+
+    Nothing in ``project_sealed_run`` hand-checks a key set. A projector that checked its own keys
+    inline would be a second opinion about the fact spec, and the point of `EVENT_FACTS` is that
+    there is exactly one.
+    """
+
+    validate_facts(event, facts)
+    record = {
+        "seq": seq,
+        "at": 0.0,
+        "event": event,
+        "facts": dict(facts),
+        "evidence": None if evidence is None else dict(evidence),
+    }
+    _require_location_blind(record)
+    return record
+
+
+def _member_json(member_bytes: Mapping[str, bytes], member: str) -> Any:
+    """Return one sealed member parsed as JSON, or raise ``ValueError`` naming the member."""
+
+    if not isinstance(member_bytes, Mapping):
+        raise ValueError("member bytes is not a mapping")
+    raw = member_bytes.get(member)
+    if raw is None:
+        raise ValueError(f"the projection needs member {member!r}, which was not supplied")
+    if not isinstance(raw, (bytes, bytearray)):
+        raise ValueError(f"member {member!r} was not supplied as bytes")
+    return _decode_json(bytes(raw), member)
+
+
+def _decode_json(raw: bytes, member: str) -> Any:
+    try:
+        return json.loads(raw.decode("utf-8"))
+    except (ValueError, RecursionError) as exc:
+        raise ValueError(f"member {member!r} is not the JSON this projection expects") from exc