cctally 1.116.0 → 1.117.0

package/bin/_cctally_dashboard.py

@@ -278,6 +278,7 @@ import secrets
 import shutil
 import signal as _signal
 import socket
+import socketserver
 import select
 import sqlite3
 import sys
@@ -338,6 +339,21 @@ class _QuietThreadingHTTPServer(ThreadingHTTPServer):
         self._reject_workers: list[threading.Thread] = []
         super().__init__(*args, **kwargs)
 
+    def server_bind(self) -> None:
+        """Bind and record the bound address without a reverse-DNS lookup.
+
+        Replaces `http.server.HTTPServer.server_bind`, which sets `server_name`
+        to `socket.getfqdn(host)`: a PTR lookup that blocks for the resolver's
+        whole timeout where the resolver never answers it (35s measured on a
+        LAN runner), before the dashboard can print its URL or serve (#1021).
+        Nothing here reads `server_name` as a hostname, so it records the bound
+        address as `getsockname()` reports it.
+        """
+        socketserver.TCPServer.server_bind(self)
+        host, port = self.server_address[:2]
+        self.server_name = host
+        self.server_port = port
+
     def _reject_request(self, request: socket.socket) -> None:
         try:
             # Read only the bounded request headers so a close with unread
@@ -741,7 +757,7 @@ from _cctally_cache import (
     get_entries, iter_entries, iter_entries_with_id,
     open_cache_db as _raw_open_cache_db,
     open_conversations_db, sync_cache, sync_claude_conversations,
-    sync_codex_conversations,
+    sync_codex_conversations, read_codex_startup_deferral_facts,
     # #780 read-route admission. Imported here so the conversation route module
     # reaches them the same way it reaches `open_conversations_db` — through
     # `sys.modules["_cctally_dashboard"]`, which is the seam its tests patch.
@@ -2615,7 +2631,9 @@ def _conversation_frontier_context():
     frontier_mod = _cctally()._load_sibling("_lib_ingest_frontier")
     claude_roots = tuple(_cctally_core._resolve_claude_projects_dirs())
     codex_homes = tuple(_cctally()._codex_home_roots())
-    codex_roots = tuple(root / "sessions" for root in codex_homes)
+    # #970: native-home recognition, never a hard-coded `<home>/sessions`, so
+    # an archive directory is certified evidence and a permitted location.
+    codex_roots = frontier_mod.codex_frontier_roots(codex_homes)
     claude_guards = (_cctally_core.CLAUDE_SETTINGS_PATH,)
 
     try:
@@ -2689,15 +2707,121 @@ def _conversation_frontier_plans(conn):
 
 
 class _ConversationPassStatus(str):
-    """Validated status string carrying fixed-size pass diagnostics."""
+    """Validated status string carrying fixed-size pass diagnostics.
+
+    ``drain`` is the pass's evidence for writeIo's startup admission hold
+    (#939 D5, `_conversation_drain_info`), or ``None``."""
 
-    def __new__(cls, status, *, modes=None, files=None):
+    def __new__(cls, status, *, modes=None, files=None, drain=None):
         obj = str.__new__(cls, status)
         obj.modes = dict(modes or {})
         obj.files = dict(files or {})
+        obj.drain = drain
         return obj
 
 
+def _conversation_drain_info(conn, status, modes, plans, results,
+                             certifiable) -> dict:
+    """What one ``ok`` pass tells writeIo's admission hold (#939 D5).
+
+    Per provider: its census and residual (``None`` for ``caught_up``, which
+    carries the previous one forward), plus an empty ``"pass"`` status entry
+    (an error pass's is non-empty: `_conversation_failed_drain`). For Codex,
+    its unpublished deferrals and, while the hold is placed, the stored facts
+    of every deferral the evaluator tracks, read at the pass's end. The pass
+    is census-complete only when its status is ``ok``, both censuses are
+    complete, the facts could be read and no detached Codex worker is in
+    progress at its end.
+    """
+    import _lib_ingest_frontier as frontier_lib
+    providers = {"pass": {"mode": "full", "residual": ()}}
+    census = status == "ok"
+    for provider in ("claude", "codex"):
+        mode = modes.get(provider, "not_observed")
+        stats = results.get(provider)
+        plan = plans.get(provider) if plans else None
+        expected = len(plan.paths) if plan is not None else 0
+        census = census and frontier_lib.conversation_census_complete(
+            mode, stats, expected_paths=expected)
+        providers[provider] = {
+            "mode": mode,
+            "residual": (None if mode == "caught_up"
+                         else _lib_write_io.conversation_residual(stats)),
+        }
+    codex_mode = modes.get("codex")
+    deferrals = (None if codex_mode == "caught_up" or "codex" not in results
+                 else _lib_write_io.unpublished_deferrals(results.get("codex")))
+    facts = {}
+    if conn is not None and _lib_write_io.admission_held():
+        entries = dict(_lib_write_io.startup_watch())
+        for path, (identity, _covered, keys) in (deferrals or {}).items():
+            prior = entries.get(path)
+            entries[path] = (identity,
+                             frozenset(keys) | (prior[1] if prior else frozenset()))
+        entries = {path: entry for path, entry in entries.items()
+                   if entry[0] is not None}
+        if entries:
+            try:
+                facts = read_codex_startup_deferral_facts(conn, entries)
+            except Exception as exc:  # noqa: BLE001 — missing facts keep the hold
+                eprint(f"[conversations] startup facts unavailable: {exc}")
+                census = False
+    if census:
+        census = not _codex_worker_in_progress()
+    return {"census_complete": bool(census), "certifiable": bool(certifiable),
+            "providers": providers, "deferrals": deferrals, "facts": facts}
+
+
+def _codex_worker_in_progress() -> bool:
+    """Whether a detached Codex worker is requested or running (#939 D5); an
+    unknown worker state counts as one (it keeps the hold)."""
+    import _lib_codex_worker_lifecycle as lifecycle
+    try:
+        return bool(lifecycle.any_in_progress(
+            _cctally_core.APP_DIR, now=time.time()))
+    except Exception:  # noqa: BLE001 — unknown worker state: keep the hold
+        return True
+
+
+def _connection_changes(conn) -> "int | None":
+    """``conn.total_changes``: rows changed on the connection since it was
+    created, including the store open's own migrations, imports and replays
+    (#939 R9-01) and changes later rolled back; None when it cannot be read
+    (unknown reads as changed). A double without the attribute changes
+    nothing."""
+    try:
+        return int(getattr(conn, "total_changes", 0) or 0)
+    except Exception:  # noqa: BLE001
+        return None
+
+
+def _conversation_failed_drain(status: str, error_name: str, *,
+                               changed_rows: bool) -> dict:
+    """What a pass that ended in ``error`` or ``store_unavailable`` tells
+    writeIo's admission hold (#939 D5).
+
+    A failure can commit work before it propagates (D1's prepared prefix, a
+    Codex publication unit), and no residual can prove that work was not
+    catch-up progress (#939 R7-01, R8-01). So a failing pass that changed any
+    row on its own connection since its creation, the open's migrations
+    included (``changed_rows``, R9-01), and a failed open, which leaves no
+    connection to ask (R10-01), are incomplete censuses: they never anchor a
+    settle. A pass that opened and changed nothing can repeat for the dashboard's whole life, so it is
+    census-complete (unless a detached Codex worker is in progress) with its
+    status and exception class as its residual: an identical failure settles,
+    and a later ``ok`` pass, whose status entry is empty, changes the digest.
+    It is never certifiable, so it never releases as drained. The provider
+    residuals and deferrals carry forward."""
+    return {"census_complete": (not changed_rows
+                                and not _codex_worker_in_progress()),
+            "certifiable": False,
+            "providers": {"pass": {
+                "mode": "full",
+                "residual": (("status", status),
+                             ("exception", error_name))}},
+            "deferrals": None, "facts": {}}
+
+
 def _conversation_sync_pass() -> str:
     """One WHOLE transcript-ingest pass (#583 S4 / F5).
 
@@ -2742,17 +2866,37 @@ def _conversation_sync_pass() -> str:
         conn = open_conversations_db()
     except (OSError, sqlite3.DatabaseError) as exc:
         eprint(f"[conversations] background sync unavailable: {exc}")
-        return _ConversationPassStatus("store_unavailable")
+        # The open can commit work before it fails (a resumable migration's
+        # chunks), and with no connection to ask nothing proves it did not:
+        # file metadata cannot (a reused WAL keeps its size, mtimes are
+        # coarse), so a failed open is inconclusive, read as changed
+        # (#939 R9-01, R10-01).
+        return _ConversationPassStatus(
+            "store_unavailable",
+            drain=_conversation_failed_drain(
+                "store_unavailable", type(exc).__name__, changed_rows=True))
     status = "ok"
+    error_name = None
+    # Rows changed on this pass's connection, from its creation (#939 R8-01,
+    # R9-01): the open's migrations and imports run on it too.
+    changed_rows = True
     modes = {"claude": "not_observed", "codex": "not_observed"}
     files = {"claude": 0, "codex": 0}
+    results = {}
+    plans = None
+    certifiable = False
+    drain = None
     try:
         planned = _conversation_frontier_plans(conn)
-        results = {}
         if planned is None:
             modes = {"claude": "full", "codex": "full"}
             results["claude"] = sync_claude_conversations(conn)
             results["codex"] = sync_codex_conversations(conn)
+            import _lib_ingest_frontier as frontier_lib
+            certifiable = all(
+                frontier_lib.conversation_sync_certifiable(
+                    "full", results.get(provider))
+                for provider in ("claude", "codex"))
         else:
             frontier_mod, frontier, cutoff, context, plans = planned
             modes = {
@@ -2801,9 +2945,18 @@ def _conversation_sync_pass() -> str:
                         frontier.commit_provider(
                             plan, conn, roots=roots, guard_paths=guards,
                             trusted=trusted, cutoff=cutoff)
+        try:
+            drain = _conversation_drain_info(
+                conn, status, modes, plans, results, certifiable)
+        except Exception as exc:  # noqa: BLE001 — the hold's evidence is
+            # diagnostic: it must never fail a pass that ingested. A missing
+            # record is read as a pass that did not cover its census.
+            eprint(f"[conversations] startup drain evidence unavailable: {exc}")
+            drain = None
     except (OSError, sqlite3.DatabaseError) as exc:
         eprint(f"[conversations] background sync unavailable: {exc}")
         status = "store_unavailable"
+        error_name = type(exc).__name__
     except Exception as exc:  # noqa: BLE001
         # Transcript parsing/normalization is deliberately outside the core
         # freshness loop. Keep this worker alive so a later clean tick can
@@ -2814,7 +2967,10 @@ def _conversation_sync_pass() -> str:
             f"{type(exc).__name__}: {exc}"
         )
         status = "error"
+        error_name = type(exc).__name__
     finally:
+        changes = _connection_changes(conn)
+        changed_rows = changes is None or changes > 0
         try:
             conn.close()
         except Exception:  # noqa: BLE001
@@ -2824,7 +2980,18 @@ def _conversation_sync_pass() -> str:
         if provider in results:
             files[provider] = int(
                 getattr(results.get(provider), "files_total", 0) or 0)
-    return _ConversationPassStatus(status, modes=modes, files=files)
+    if status != "ok":
+        # An error or an unavailable store ended the pass: its status is its
+        # residual, so a failure that repeats identically settles (#939 D5).
+        # An error pass is never drained.
+        drain = _conversation_failed_drain(status, error_name or "Exception",
+                                           changed_rows=changed_rows)
+    elif drain is None:
+        # An ok pass whose evidence could not be built: not census-complete.
+        drain = {"census_complete": False, "certifiable": False,
+                 "providers": {}, "deferrals": None, "facts": {}}
+    return _ConversationPassStatus(status, modes=modes, files=files,
+                                   drain=drain)
 
 
 def _conversation_sync_loop(
@@ -2847,12 +3014,31 @@ def _conversation_sync_loop(
     The previous fixed `wait(interval)` prevented literal 100% duty for finite
     work but provided no scale-independent ceiling below it: a 30 s pass ran
     30-on/5-off, about 86% duty, and nothing bounded that as the store grew.
+
+    #939 D5: every completed pass is fed to writeIo's startup admission hold,
+    whose verdict ("drained" or "settled") releases it; the loop's end
+    releases it in a ``finally`` ("loopExit"), so a dead loop never holds
+    admission. An exception from the evaluator is logged once and read as no
+    verdict (the hold stays), never as the end of ingest.
     """
+    try:
+        _conversation_sync_loop_body(
+            stop=stop, interval=interval, run_iteration=run_iteration,
+            monotonic=monotonic, thread_time_ns=thread_time_ns, wait=wait,
+            record=record)
+    finally:
+        _lib_write_io.release_admission("loopExit")
+
+
+def _conversation_sync_loop_body(
+    *, stop, interval, run_iteration, monotonic, thread_time_ns, wait, record,
+) -> None:
     if thread_time_ns is None:
         thread_time_ns = time.thread_time_ns
     if wait is None:
         wait = stop.wait
     seq = 0
+    evaluator_failed = False
     while not stop.is_set():
         t0 = monotonic()
         cpu0 = thread_time_ns()
@@ -2866,6 +3052,20 @@ def _conversation_sync_loop(
         work = max(0.0, monotonic() - t0)
         cpu_ns = max(0, thread_time_ns() - cpu0)
         seq += 1
+        try:
+            verdict = _lib_write_io.observe_conversation_pass(
+                getattr(status, "drain", None), started_ns=int(t0 * 1e9),
+                seq=seq)
+            if verdict is not None:
+                _lib_write_io.release_admission(verdict)
+        except Exception as exc:  # noqa: BLE001 — an evaluator bug must not
+            # stop ingest: the verdict is read as None (the hold stays, fail
+            # closed like every other missing-evidence path) and the loop
+            # keeps running. Logged once per loop.
+            if not evaluator_failed:
+                evaluator_failed = True
+                eprint("[conversations] writeIo startup evaluator failed: "
+                       f"{type(exc).__name__}: {exc}")
         if record is not None:
             record(
                 seq=seq,
@@ -9236,6 +9436,15 @@ class DashboardHTTPHandler(BaseHTTPRequestHandler):
                 "conversation_sync": [
                     r.as_wire() for r in tick_state.conversation_records
                 ],
+                # #939 D5: the records' `started_ns`/`ended_ns` clock (the
+                # process monotonic clock) anchored to wall time in this
+                # response, so a harness can place its own judgements before
+                # or after a pass. One pair, not a field per record: the ring
+                # sits at the frozen 65,536-byte state budget.
+                "conversation_sync_clock": {
+                    "monotonic_ns": time.monotonic_ns(),
+                    "unix_ns": time.time_ns(),
+                },
                 # #780: the maintenance phases, published beside the sync ring
                 # rather than inside it. A reclaim that ran for its whole budget
                 # used to be indistinguishable from a fast one, because both
@@ -12539,6 +12748,11 @@ def cmd_dashboard(args: argparse.Namespace) -> int:
     _lib_write_io.register_local_instance(
         instance_id=write_instance_id, host=args.host,
         port=_resolve_dashboard_port(args.port))
+    # #939 D5: hold warm admission through the startup catch-up. Placed before
+    # the main sync thread can publish a non-cold snapshot, and only when the
+    # conversation loop (which releases it) will run.
+    if not args.no_sync:
+        _lib_write_io.hold_admission()
     sync_thread = (
         None if args.no_sync
         else _DashboardSyncThread(
@@ -12689,6 +12903,9 @@ def cmd_dashboard(args: argparse.Namespace) -> int:
         conversation_sync_stop.set()
         if conversation_sync_thread is not None:
             conversation_sync_thread.join(timeout=2)
+        # #939 D5: the loop's own `finally` releases the hold; a loop still
+        # finishing a pass after the bounded join must not leave it placed.
+        _lib_write_io.release_admission("loopExit")
         update_check_stop.set()
         memory_shutdown_errors = []
         try:

package/bin/_cctally_dashboard_conversation.py

@@ -46,6 +46,8 @@ import base64
 import collections
 import dataclasses
 import hashlib
+import os
+import pathlib
 import secrets
 import select
 import threading
@@ -444,17 +446,86 @@ def _cached_file_sigs(conn, paths):
     return out
 
 
-#: The cursor columns a Codex live-tail signature is computed from (#968 5.9).
+#: The cursor columns a Codex live-tail signature is computed from (#968 5.9;
+#: #970 appends ``container_path``, the accepted location).
 _CODEX_WATCH_SIG_COLUMNS = (
     "path, size_bytes, container_kind, container_size_bytes, mtime_ns, "
-    "device_id, inode, pending_container_fingerprint")
+    "device_id, inode, pending_container_fingerprint, container_path")
 
 
 def _codex_watch_kernel():
     return sys.modules["cctally"]._load_sibling("_lib_codex_conversation_watch")
 
 
-def _codex_acknowledged_sig(row):
+def _codex_watch_locations():
+    """The configured Codex container locations (#970), for one batch."""
+    return tuple(_rc.CodexLocations(root.walk_root, root.archive_root)
+                 for root in _codex_provider_roots())
+
+
+def _codex_lazy_locations():
+    """A memoized locations getter: resolved on first need, at most once.
+
+    A home without archived containers never needs it, so its signatures
+    cost exactly what they cost before #970.
+    """
+    memo: list = []
+
+    def get():
+        if not memo:
+            memo.append(_codex_watch_locations())
+        return memo[0]
+
+    return get
+
+
+def _codex_sig_location(container_path, logical, locations) -> str:
+    """The location a stored container path names (#970 A8).
+
+    NULL is the logical path (dated). A container whose directory is the
+    rollout's archive directory — canonically, when the spellings differ —
+    is ``"archive"``; anything else (the dated twin, an uncontained stored
+    path) is ``"dated"``. This is exactly how selection names a location, so
+    a committed signature equals the observation of the same container.
+    """
+    if not container_path:
+        return _rc.DATED
+    parent = pathlib.Path(container_path).parent
+    if parent == pathlib.Path(logical).parent:
+        return _rc.DATED
+    archive_dir = _rc.archive_dir_for(logical, locations())
+    if archive_dir is None:
+        return _rc.DATED
+    if parent == archive_dir:
+        return _rc.ARCHIVE
+    try:
+        same = os.path.realpath(parent) == os.path.realpath(archive_dir)
+    except (OSError, ValueError):
+        return _rc.DATED
+    return _rc.ARCHIVE if same else _rc.DATED
+
+
+def _codex_observe_watch_sig(path, locations=None):
+    """The live probe: the selected container's signature, archive included.
+
+    The dated containers are tried first through the leaf alone, so a dated
+    rollout costs exactly today's probe; only when neither exists, and the
+    path is a dated rollout of a native home, are its archive candidates
+    observed (#970 A8), the signature then carrying ``"archive"``.
+    """
+    sig = _rc.observe_watch_sig(path)
+    if sig is not None:
+        return sig
+    if _rc.archive_name_date(pathlib.Path(str(path)).name) is None:
+        return None
+    archive_dir = _rc.archive_dir_for(
+        path, (locations or _codex_watch_locations)())
+    if archive_dir is None:
+        return None
+    return _rc.observe_watch_sig(path, archive_dir=archive_dir)
+
+
+def _codex_acknowledged_sig(row, locations=None):
     """The live-tail signature one ``codex_conversation_source_files`` row
     acknowledges (#968 spec 5.9).
 
@@ -463,15 +534,20 @@ def _codex_acknowledged_sig(row):
     it, and rescheduling it on every poll is the non-convergence I9 forbids.
     Otherwise the accepted container's signature: ``("plain", size)`` for
     plain, which is today's committed size, or the container identity for a
-    zstd container.
+    zstd container. #970: either carries the container's location exactly as
+    the observation does (``"archive"`` appended only outside the dated
+    location), derived from the recorded container path.
     """
-    _path, size, kind, csize, mtime_ns, device, inode, pending = row
+    path, size, kind, csize, mtime_ns, device, inode, pending, stored = row
+    locations = locations or _codex_lazy_locations()
     if pending:
         fingerprint = _rc.ContainerFingerprint.from_json(pending)
         if fingerprint is not None:
-            return fingerprint.watch_sig()
+            return fingerprint.watch_sig(
+                _codex_sig_location(fingerprint.path, path, locations))
     return _codex_watch_kernel().committed_watch_sig(
-        kind, size, csize, mtime_ns, device, inode)
+        kind, size, csize, mtime_ns, device, inode,
+        location=_codex_sig_location(stored, path, locations))
 
 
 def _codex_cached_file_sigs(conn, paths):
@@ -494,8 +570,9 @@ def _codex_cached_file_sigs(conn, paths):
             f"WHERE path IN ({placeholders})", list(paths)).fetchall()
     except sqlite3.OperationalError:
         return out
+    locations = _codex_lazy_locations()
     for row in rows:
-        out[row[0]] = _codex_acknowledged_sig(row)
+        out[row[0]] = _codex_acknowledged_sig(row, locations)
     return out
 
 
@@ -511,7 +588,8 @@ def _codex_all_committed_sizes(conn):
             "FROM codex_conversation_source_files").fetchall()
     except sqlite3.OperationalError:
         return {}
-    return {row[0]: _codex_acknowledged_sig(row) for row in rows}
+    locations = _codex_lazy_locations()
+    return {row[0]: _codex_acknowledged_sig(row, locations) for row in rows}
 
 
 def _codex_seal_token(conn):
@@ -586,6 +664,9 @@ def _codex_watch_probes(conn):
     deferred: dict = {}     # path -> (pre-ingest signature, seal token)
     accounting_wait: dict = {}  # path -> observed container awaiting accounting
     rearmed: set = set()
+    # #970: resolved once per stream, and only when an archived container
+    # is actually met.
+    locations = _codex_lazy_locations()
 
     def accounting_accepted(path, sig):
         try:
@@ -595,7 +676,8 @@ def _codex_watch_probes(conn):
                 "WHERE path=? AND container_state='accepted'", (path,)).fetchone()
         except sqlite3.Error:
             return False
-        return row is not None and _codex_acknowledged_sig(row) == sig
+        return (row is not None
+                and _codex_acknowledged_sig(row, locations) == sig)
 
     def executor_owns_observations(paths):
         # Publication-unit planning can encounter the same pending container
@@ -620,12 +702,13 @@ def _codex_watch_probes(conn):
             before = observed.get(path)
             if (fingerprint is None or before is None
                     or before[0] != _rc.ZSTD
-                    or fingerprint.watch_sig() != before):
+                    or fingerprint.watch_sig(_codex_sig_location(
+                        fingerprint.path, path, locations)) != before):
                 return False
         return True
 
     def stat_fn(path):
-        sig = _rc.observe_watch_sig(path)
+        sig = _codex_observe_watch_sig(path, locations)
         observed[path] = sig
         waiting = accounting_wait.get(path)
         if waiting is not None:
@@ -741,11 +824,13 @@ def _codex_classified_paths(conn, paths):
 
 
 def _codex_walk_root_for_conversation(conn, conversation_key):
-    """The configured ``walk_root`` of the conversation's OWN provider root (the
-    frontier's scope — §5.4). Resolves the conversation's ``source_root_key`` via
-    its thread facts, then matches it to a currently-configured provider root.
-    ``None`` when the conversation has no thread row or its root is no longer
-    configured (the frontier is then skipped — DB re-resolve alone still runs)."""
+    """The container locations of the conversation's OWN provider root (the
+    frontier's scope — §5.4): its configured ``walk_root`` and, for a native
+    home, its ``archive_root`` (#970), as ``_rc.CodexLocations``. Resolves the
+    conversation's ``source_root_key`` via its thread facts, then matches it to
+    a currently-configured provider root. ``None`` when the conversation has no
+    thread row or its root is no longer configured (the frontier is then
+    skipped — DB re-resolve alone still runs)."""
     cq = _conversation_query_impl_codex()
     thread = cq._thread_facts(conn, conversation_key)
     if thread is None:
@@ -753,7 +838,7 @@ def _codex_walk_root_for_conversation(conn, conversation_key):
     source_root_key = thread[3]
     for root in _codex_provider_roots():
         if root.source_root_key == source_root_key:
-            return str(root.walk_root)
+            return _rc.CodexLocations(root.walk_root, root.archive_root)
     return None
 
 
@@ -1748,11 +1833,12 @@ def _make_codex_discovery_step(handler, conn, conversation_key, cq_codex):
     frontier is then skipped — the DB re-resolve of layer 1 still runs). The
     frontier is constructed ONCE per SSE connection so its directory index,
     pending-candidate set, and rotation cursors accumulate across cycles."""
-    walk_root = _codex_walk_root_for_conversation(conn, conversation_key)
-    if walk_root is None:
+    locations = _codex_walk_root_for_conversation(conn, conversation_key)
+    if locations is None:
         return None
     fw = sys.modules["cctally"]._load_sibling("_lib_codex_conversation_watch")
-    frontier = fw.CodexChildFrontier(walk_root)
+    frontier = fw.CodexChildFrontier(
+        str(locations.walk_root), archive_root=locations.archive_root)
 
     def _discovery(files, seen):
         # Diff brand-new *.jsonl against every tracked Codex file; the same

package/bin/_cctally_dashboard_envelope.py

@@ -987,6 +987,34 @@ def _source_bundle_to_envelope(bundle: object | None) -> dict:
 METER_RATE_CHANGE_LIMIT = 20
 
 
+def _rate_change_supersessions(conn: sqlite3.Connection) -> dict:
+    """Wire `supersession` objects by transition identity (#1015 spec 5.7).
+
+    Read through `read_rate_change_supersessions` on the build's own stats
+    connection, so both the explicit `meter_rate_change_supersessions` rows
+    and the supersessions derived from a transition's lineage before any
+    sweep journals one are covered. `superseded_at` is the explicit event's
+    sweep clock, or null for a derived-only state. Unreadable facts publish
+    no supersession — the pre-#1015 row — rather than emptying the array: the
+    marker and delivery paths refuse on their own when the facts cannot be
+    verified.
+    """
+    try:
+        qcal = sys.modules["cctally"]._load_sibling(
+            "_cctally_quota_calibration")
+        state = qcal.read_rate_change_supersessions(conn)
+    except Exception:                                  # noqa: BLE001
+        return {}
+    return {
+        tuple(identity): {
+            "reason": record.reason,
+            "superseded_at": record.superseded_at,
+            "corrections": list(record.corrections),
+        }
+        for identity, record in state.by_identity.items()
+    }
+
+
 def _build_meter_rate_change_array(
     conn: sqlite3.Connection, limit: int = METER_RATE_CHANGE_LIMIT,
 ) -> list:
@@ -1046,6 +1074,7 @@ def _build_meter_rate_change_array(
         # background worker. An empty array renders as "no change recorded",
         # which is the truth on that store, rather than emptying the envelope.
         return []
+    supersessions = _rate_change_supersessions(conn) if rows else {}
     out: list[dict] = []
     for (provider, account_key, effective_from, previous, new, severity,
          detected_at, created_at, status, causes, provenance,
@@ -1082,6 +1111,11 @@ def _build_meter_rate_change_array(
             "composition_provenance": _decode_evidence_array(provenance),
             "baseline_withheld_days": (
                 None if baseline_days is None else int(baseline_days)),
+            # #1015 spec 5.7 (U2): published always and nulled, so the client
+            # can tell an ordinary row (null) from one an older server sent
+            # (absent). The row and its historical values are kept.
+            "supersession": supersessions.get(
+                (str(provider), str(account_key), str(effective_from))),
         }
         entry.update(account_fields(str(provider), account_key))
         out.append(entry)