cctally 1.113.0 → 1.115.0

package/bin/_lib_codex_conversation_watch.py

@@ -43,15 +43,16 @@ All six §5.4 bullets are contract:
    its first ingest attempt (so a discovered file is never lost even if its
    first ingest is dirty/lock-contended and leaves no cursor row). A path is
    retried while unclassified: with no committed cursor it is surfaced every
-   time it is visited; with a committed cursor it is surfaced only when its size
-   exceeds that cursor (an incomplete-``session_meta`` tail completing without
-   any directory-mtime change). A path leaves the set when the driver ``reap``s
+   time it is visited; with a committed cursor it is surfaced only when its
+   signature advances beyond that cursor (an incomplete-``session_meta`` tail
+   completing without any directory-mtime change). A path leaves the set when the driver ``reap``s
    it (it gained a thread row — child or non-child), when it vanishes, or on a
    bounded per-candidate expiry (handed to the next full sync).
 """
 from __future__ import annotations
 
 import os
+import _lib_codex_rollout_container as _rc
 
 
 # ── production-default injected callables ─────────────────────────────────────
@@ -101,6 +102,48 @@ def default_file_size(filepath):
     return st.st_size
 
 
+def default_file_sig(filepath):
+    """The selected container's live-tail signature (#968 spec 5.9).
+
+    Plain keeps today's size (as ``("plain", size)``); a compressed-only
+    rollout reports its container fingerprint instead of vanishing.
+    """
+    return _rc.observe_watch_sig(filepath)
+
+
+def _as_sig(value):
+    if value is None or isinstance(value, tuple):
+        return value
+    return (_rc.PLAIN, int(value))
+
+
+def codex_sig_advanced(observed, committed) -> bool:
+    """Whether an observed signature is ahead of the committed one.
+
+    Plain grows (append-only, size decides); any other change of a compressed
+    container, or of the container kind, is a change. A bare int on either
+    side is a legacy plain size.
+    """
+    obs, com = _as_sig(observed), _as_sig(committed)
+    if obs is None:
+        return False
+    if com is None:
+        return True
+    if obs[0] == com[0] == _rc.PLAIN:
+        return obs[1] > com[1]
+    return obs != com
+
+
+def committed_watch_sig(kind, size_bytes, container_size_bytes, mtime_ns,
+                        device, inode):
+    """The signature a cursor row's ACCEPTED container would observe: the
+    leaf's ``ContainerFingerprint.watch_sig`` shape, device included."""
+    if kind in (None, _rc.PLAIN):
+        return (_rc.PLAIN, int(size_bytes or 0))
+    return (_rc.ZSTD, int(container_size_bytes or 0), int(mtime_ns or 0),
+            int(device or 0), int(inode or 0))
+
+
 _SENTINEL = object()
 
 
@@ -118,7 +161,7 @@ class CodexChildFrontier:
         pending_expiry_cycles: int = 50,
         scandir_fn=default_scandir,
         dir_mtime_fn=default_dir_mtime,
-        file_size_fn=default_file_size,
+        file_size_fn=default_file_sig,
         clock_fn=None,
     ):
         self._walk_root = str(walk_root)
@@ -175,7 +218,7 @@ class CodexChildFrontier:
 
         ``known_paths`` — every path already tracked in ``codex_session_files``,
         so a newly enumerated file already known to some table is not
-        re-registered. ``committed_sizes`` — ``{path: size_bytes}`` committed
+        re-registered. ``committed_sizes`` — ``{path: signature}`` committed
         cursors, for the pending-growth check.
 
         Returns the set of candidate paths to targeted-ingest this cycle (new
@@ -251,8 +294,8 @@ class CodexChildFrontier:
         mtime as the dir's baseline (so a create landing during the enumeration
         is re-examined next rotation), skips symlinked descendants (the
         ``follow_symlinks=False`` boundary), adds real subdirectories to the
-        frontier, and registers brand-new ``*.jsonl`` files in ``pending`` BEFORE
-        their first ingest — surfacing each for that first ingest attempt in the
+        frontier, and registers brand-new logical rollout files in ``pending``
+        BEFORE their first ingest — surfacing each for that first ingest attempt in the
         SAME cycle it is discovered (the pending sweep then owns the retries).
         Returns True iff it consumed a filesystem op."""
         if not self._enum_queue:
@@ -267,10 +310,12 @@ class CodexChildFrontier:
                 if path not in self._dir_set:
                     self._dir_set.add(path)
                     self._dirs.append(path)           # new subdir joins frontier
-            elif path.endswith(".jsonl"):
-                if path not in self._known and path not in self._pending:
-                    self._pending[path] = 0           # register BEFORE first ingest
-                    ingest.add(path)                  # first ingest attempt now
+            elif _rc.is_container_name(name):
+                # Both spellings enumerate one logical identity.
+                logical = os.fspath(_rc.logical_path(path))
+                if logical not in self._known and logical not in self._pending:
+                    self._pending[logical] = 0        # register BEFORE first ingest
+                    ingest.add(logical)               # first ingest attempt now
         return True
 
     def _op_pending(self, ingest: set) -> bool:
@@ -286,12 +331,12 @@ class CodexChildFrontier:
             p = keys[idx]
             if p not in self._pending:                # reaped/dropped mid-cycle
                 continue
-            size = self._file_size(p)                 # 1 fs op
-            if size is None:
+            sig = self._file_size(p)                  # 1 signature probe
+            if sig is None:
                 self._pending.pop(p, None)            # vanished → drop
             else:
                 committed = self._committed.get(p)
-                if committed is None or size > committed:
+                if codex_sig_advanced(sig, committed):
                     ingest.add(p)
             return True
         return False

package/bin/_lib_codex_drain_admission.py

@@ -0,0 +1,214 @@
+"""Waiting requests and the drain-admission gate (#968 spec 5.7, 5.12).
+
+A Codex hook never waits for a lock. When it meets cache contention it
+publishes a uniquely named, immutable request record under the data
+directory (outside every SQLite store, because a contended hook cannot write
+cache.db). Drain workers — the prune executor and the container-verification
+executor — admit one identity at a time through ONE global gate and yield
+while any request is fresh:
+
+1. check for fresh requests;
+2. acquire the drain gate (non-blocking), then check again;
+3. try the store's complete lock domain without blocking, then check again;
+4. a fresh request at any check releases everything acquired and yields;
+5. otherwise the caller executes one identity, commits, releases every store
+   lock and the gate (``finish``), and starts again at step 1.
+
+Requests end only by expiry: 60 s after publication on a cross-process
+monotonic clock. A worker observing a request, or restarting, never renews it;
+a wall-clock jump cannot extend it (the wall age only shortens freshness, and
+a NEGATIVE wall age — an mtime ahead of the wall clock after a backward step —
+counts as fresh, bounded by the monotonic lifetime); a malformed record or one
+from an incompatible clock is expired and removed. Stdlib only; no cctally
+imports.
+"""
+from __future__ import annotations
+
+import fcntl
+import json
+import os
+import pathlib
+import time
+import uuid
+from typing import Callable, NamedTuple, Optional
+
+REQUEST_DIR_NAME = "codex-drain-requests"
+REQUEST_TTL_NS = 60_000_000_000
+WALL_GUARD_SECONDS = 120.0
+GATE_FILE_NAME = "codex-drain-admission.lock"
+POLL_SECONDS = 5.0
+_RECORD_VERSION = 1
+
+# Module attributes so tests can drive a deterministic schedule.
+_monotonic_ns: Callable[[], int] = time.monotonic_ns
+_sleep: Callable[[float], None] = time.sleep
+#: Post-release seam: called by ``finish`` after the store locks AND the gate
+#: are released. Production leaves it None; the fairness test synchronizes on
+#: it instead of sleeping (review P2-7).
+_after_finish: Optional[Callable[[], None]] = None
+
+
+def _request_dir(app_dir) -> pathlib.Path:
+    return pathlib.Path(app_dir) / REQUEST_DIR_NAME
+
+
+def publish_waiting_request(app_dir, *, root_keys) -> "str | None":
+    """Atomically publish one immutable request; return its id or None.
+
+    ``None`` is a protocol failure the hook records; it is never fairness
+    evidence and never raises.
+    """
+    try:
+        directory = _request_dir(app_dir)
+        directory.mkdir(parents=True, exist_ok=True)
+        mono = int(_monotonic_ns())
+        request_id = f"{mono}-{os.getpid()}-{uuid.uuid4().hex}"
+        final = directory / f"req-{request_id}.json"
+        tmp = directory / f".tmp-{request_id}"
+        payload = json.dumps({
+            "v": _RECORD_VERSION, "id": request_id,
+            "roots": sorted(str(k) for k in root_keys), "mono_ns": mono,
+        }, separators=(",", ":"))
+        with open(tmp, "x", encoding="utf-8") as fh:
+            fh.write(payload)
+            fh.flush()
+            os.fsync(fh.fileno())
+        os.rename(tmp, final)
+        return request_id
+    except OSError:
+        return None
+
+
+def _is_fresh(path: pathlib.Path, now_mono: int, now_wall: float) -> bool:
+    try:
+        record = json.loads(path.read_text(encoding="utf-8"))
+        mono = int(record["mono_ns"])
+        if record.get("v") != _RECORD_VERSION:
+            return False
+        wall_age = now_wall - path.stat().st_mtime
+    except (OSError, ValueError, TypeError, KeyError):
+        return False
+    age = now_mono - mono
+    # A negative monotonic age is an incompatible clock: expired. A negative
+    # WALL age is only an mtime ahead of the wall clock, which is not evidence
+    # of staleness: it stays fresh, and the monotonic bound still ends it
+    # within the single 60 s lifetime (review P3-5).
+    return 0 <= age < REQUEST_TTL_NS and wall_age < WALL_GUARD_SECONDS
+
+
+def fresh_requests(app_dir) -> "list[str]":
+    """Ids of fresh requests; expired or malformed records are removed one by one."""
+    directory = _request_dir(app_dir)
+    try:
+        entries = sorted(directory.iterdir())
+    except OSError:
+        return []
+    now_mono = int(_monotonic_ns())
+    now_wall = time.time()
+    fresh: list[str] = []
+    for path in entries:
+        name = path.name
+        if name.startswith(".tmp-"):
+            try:
+                if now_wall - path.stat().st_mtime >= WALL_GUARD_SECONDS:
+                    path.unlink()
+            except OSError:
+                pass
+            continue
+        if not (name.startswith("req-") and name.endswith(".json")):
+            continue
+        if _is_fresh(path, now_mono, now_wall):
+            fresh.append(name[len("req-"):-len(".json")])
+        else:
+            try:
+                path.unlink()
+            except OSError:
+                pass
+    return fresh
+
+
+class DrainGate:
+    """The one global, non-blocking drain-admission flock."""
+
+    def __init__(self, app_dir):
+        self._path = pathlib.Path(app_dir) / GATE_FILE_NAME
+        self._fd: "int | None" = None
+
+    def try_acquire(self) -> bool:
+        if self._fd is not None:
+            return True
+        self._path.parent.mkdir(parents=True, exist_ok=True)
+        fd = os.open(self._path, os.O_RDWR | os.O_CREAT, 0o600)
+        try:
+            fcntl.flock(fd, fcntl.LOCK_EX | fcntl.LOCK_NB)
+        except OSError:
+            os.close(fd)
+            return False
+        self._fd = fd
+        return True
+
+    def release(self) -> None:
+        if self._fd is None:
+            return
+        try:
+            fcntl.flock(self._fd, fcntl.LOCK_UN)
+        finally:
+            os.close(self._fd)
+            self._fd = None
+
+
+class Admission(NamedTuple):
+    admitted: bool
+    store_locks: object
+    gate: "DrainGate | None"
+
+
+def admit(app_dir, try_store_locks: Callable[[], object],
+          release_store_locks: Callable[[object], None], *,
+          on_check: Optional[Callable[[str], None]] = None) -> Admission:
+    """Steps 1-4 of the protocol. ``try_store_locks`` must never block and
+    returns a token, or None on contention."""
+    def check(stage: str) -> bool:
+        if on_check is not None:
+            on_check(stage)
+        return bool(fresh_requests(app_dir))
+
+    if check("before-gate"):
+        return Admission(False, None, None)
+    gate = DrainGate(app_dir)
+    if not gate.try_acquire():
+        return Admission(False, None, None)
+    if check("after-gate"):
+        gate.release()
+        return Admission(False, None, None)
+    token = try_store_locks()
+    if token is None:
+        gate.release()
+        return Admission(False, None, None)
+    if check("after-store-locks"):
+        release_store_locks(token)
+        gate.release()
+        return Admission(False, None, None)
+    return Admission(True, token, gate)
+
+
+def finish(admission: Admission,
+           release_store_locks: Callable[[object], None]) -> None:
+    """Step 5: release every store lock, then the gate."""
+    try:
+        if admission.store_locks is not None:
+            release_store_locks(admission.store_locks)
+    finally:
+        if admission.gate is not None:
+            admission.gate.release()
+    if _after_finish is not None:
+        _after_finish()
+
+
+def wait_until_no_fresh_requests(
+        app_dir, *, should_continue: Optional[Callable[[], bool]] = None) -> None:
+    """Sleep in bounded steps until no request is fresh (requests expire)."""
+    while fresh_requests(app_dir):
+        if should_continue is not None and not should_continue():
+            return
+        _sleep(POLL_SECONDS)

package/bin/_lib_codex_metadata.py

@@ -26,6 +26,8 @@ import sqlite3
 import threading
 from collections import OrderedDict
 
+from _lib_codex_publication_barrier import LAST_GOOD_THREADS_VIEW
+
 
 #: The physical name of the raw threads table. ``resolve_codex_threads_table``
 #: returns it qualified by whichever schema actually holds it.
@@ -185,6 +187,8 @@ def _schema_holds_threads_table(conn: sqlite3.Connection, schema: str) -> bool:
 def resolve_codex_threads_table(conn: sqlite3.Connection) -> str:
     """The RAW threads table reference for this connection.
 
+    A conversations connection carrying the #968 last-good view resolves to it.
+
     A bare cache connection (``open_cache_db()``) holds the table in its own
     ``main`` schema; a conversations connection
     (``open_conversations_db``/``open_conversations_db_readonly``) reaches it
@@ -222,8 +226,21 @@ def resolve_codex_threads_table(conn: sqlite3.Connection) -> str:
             _threads_table_resolution_cache.move_to_end(conn)
             return cached
 
+    # One metadata SELECT preserves last-good priority without adding a
+    # fifth query to the bounded accounting/metadata-health read contracts.
+    schema = conn.execute(
+        "SELECT CASE "
+        "WHEN EXISTS (SELECT 1 FROM sqlite_temp_master "
+        "WHERE type='view' AND name=?) THEN 'temp' "
+        "WHEN EXISTS (SELECT 1 FROM main.sqlite_master "
+        "WHERE type='table' AND name=?) THEN 'main' END",
+        (LAST_GOOD_THREADS_VIEW, CODEX_THREADS_TABLE),
+    ).fetchone()[0]
     resolved = None
-    if _schema_holds_threads_table(conn, "main"):
+    if schema == "temp":
+        # #968 spec 5.11: unpublished metadata never overrides last-good.
+        resolved = f"temp.{LAST_GOOD_THREADS_VIEW}"
+    elif schema == "main":
         resolved = f"main.{CODEX_THREADS_TABLE}"
     else:
         attached = tuple(conn.execute("PRAGMA database_list"))

package/bin/_lib_codex_publication_barrier.py

@@ -0,0 +1,277 @@
+"""Pure decisions of the #968 conversation publication barrier (spec 5.11).
+
+No I/O and no SQLite. `_cctally_cache` owns the durable cache.db state (the
+membership index, readiness targets, population, certificates and repair
+queue) and the conversation pass owns the publication records; both call these
+functions with plain values, so the readiness rule, the thread-metadata rule
+and the certificate format are stated exactly once.
+"""
+from __future__ import annotations
+
+import json
+from typing import Iterable, NamedTuple, Optional
+
+CERTIFICATE_VERSION = 1
+
+READY = "ready"
+REQUIRED = "required"
+SUSPENDED = "suspended"
+
+#: The pending hold (5.11 U6 table, first row): the candidate stays a
+#: dependency of the next revision; pending work is never an exclusion.
+PENDING_HOLD = "verification-pending"
+#: Holds that suspend the contributor's current-generation readiness
+#: obligation (U6 table, second row). Retained accepted membership is kept;
+#: "excluded" never means deleting rows or forgetting membership.
+#: `container-absent` is an accounted identity whose container is gone (an
+#: orphan awaiting the off-hook prune, or one #485 refuses to prune).
+SUSPENSION_HOLDS = frozenset({
+    "decoder-unavailable", "decode-error", "verification-unverified",
+    "container-absent",
+})
+
+#: The twelve source columns of a `codex_conversation_threads` row, in column
+#: order. The two timestamp columns are bookkeeping, carried separately.
+THREAD_FIELDS = (
+    "conversation_key", "source_root_key", "native_thread_id",
+    "root_thread_id", "parent_thread_id", "source_path", "cwd", "git_json",
+    "source_kind", "thread_source_json", "model_provider", "context_window",
+)
+
+#: The generation token of a membership row that records a key a suspended
+#: contributor of unknown membership (no watermark) is KNOWN to feed, from its
+#: retained rows (review N2). Never equal to a real generation token, so it
+#: never feeds a READY contributor; it is such an exclusion's effective
+#: generation, and the row carries the key's retained thread as metadata when
+#: that row names this contributor (5.11 U6 "using retained accepted facts
+#: where they exist"). The rows are deleted when the membership is proven.
+RETAINED_GENERATION = "retained"
+
+
+class Target(NamedTuple):
+    """One contributor's readiness target (a `codex_barrier_targets` row)."""
+    identity: str
+    source_path: str
+    generation: str
+    #: Offset after the last newline-terminated line of the captured target,
+    #: set once accounting reached that target; None while it has not.
+    complete_line_end: Optional[int]
+    hold: Optional[str]
+    #: Generation and decoded offset through which the production parser has
+    #: recorded this identity's membership from offset 0.
+    watermark_generation: Optional[str]
+    watermark_offset: Optional[int]
+
+
+class TargetVerdict(NamedTuple):
+    state: str
+    reason: Optional[str]
+
+
+def classify_target(target: Target) -> TargetVerdict:
+    """Readiness of one contributor (5.11 "The readiness target", U6).
+
+    A watermark of another generation proves nothing, whatever its offset
+    (968-SR-012: a G0 cursor never satisfies G1's target). A suspension is
+    SUSPENDED whether or not its membership was ever proven (U6: "degraded
+    contributors degrade; they do not freeze", review N2): one of unknown
+    membership is an exclusion that blocks no key, and its keys keep the
+    thread its retained facts supply (``decide_seal``).
+    """
+    if target.hold in SUSPENSION_HOLDS:
+        return TargetVerdict(SUSPENDED, target.hold)
+    if target.hold == PENDING_HOLD:
+        return TargetVerdict(REQUIRED, PENDING_HOLD)
+    if target.hold is not None:
+        raise ValueError(f"unknown barrier hold {target.hold!r}")
+    if (target.watermark_generation != target.generation
+            or target.watermark_offset is None):
+        return TargetVerdict(REQUIRED, "membership-unproven")
+    if target.complete_line_end is None:
+        return TargetVerdict(REQUIRED, "accounting-incomplete")
+    if target.watermark_offset < target.complete_line_end:
+        return TargetVerdict(REQUIRED, "membership-unproven")
+    return TargetVerdict(READY, None)
+
+
+class MemberFact(NamedTuple):
+    """One `codex_barrier_membership` row."""
+    identity: str
+    generation: str
+    source_path: str
+    metadata_json: Optional[str]
+    metadata_offset: Optional[int]
+
+
+def metadata_from_thread(thread) -> str:
+    """The generation-bound metadata one `session_meta` supplies (JSON).
+
+    ``ensure_ascii`` escapes a lone surrogate (#845's undecodable cwd), and
+    ``json.loads`` restores the identical string.
+    """
+    return json.dumps({name: getattr(thread, name) for name in THREAD_FIELDS},
+                      sort_keys=True, separators=(",", ":"), ensure_ascii=True)
+
+
+def metadata_from_row(row: dict) -> str:
+    """``metadata_from_thread``'s JSON for a retained thread row (a dict)."""
+    return json.dumps({name: row.get(name) for name in THREAD_FIELDS},
+                      sort_keys=True, separators=(",", ":"), ensure_ascii=True)
+
+
+def select_thread(candidates: Iterable[MemberFact], *,
+                  retained: Optional[dict] = None) -> Optional[dict]:
+    """The conversation's thread metadata.
+
+    Review P2-2: when the retained thread row (the entry snapshot, else the
+    current accounting row) equals the metadata some candidate supplies, it
+    is kept, so certifying a legacy conversation changes nothing visible.
+    Measured on the frozen 2026-10-14 baseline: of 243 multi-file keys the
+    stored row equals the maximum-path choice for 236 and another
+    contributor's metadata for 7. Otherwise (a new publication, or a retained
+    row no contributor supplies) the rule is what a complete walk writes
+    LAST: a full walk visits a root's rollouts in logical-path order and a
+    file's records in offset order, so the last writer is the maximum of
+    ``(source_path, metadata_offset)``, independent of the order in which
+    healing reads the files.
+    """
+    facts = [f for f in candidates
+             if f.metadata_json is not None and f.metadata_offset is not None]
+    if retained is not None:
+        want = {name: retained.get(name) for name in THREAD_FIELDS}
+        for fact in facts:
+            meta = json.loads(fact.metadata_json)
+            if {name: meta.get(name) for name in THREAD_FIELDS} == want:
+                return meta
+    best = None
+    for fact in facts:
+        rank = (fact.source_path, int(fact.metadata_offset))
+        if best is None or rank > best[0]:
+            best = (rank, fact.metadata_json)
+    return None if best is None else json.loads(best[1])
+
+
+class SealDecision(NamedTuple):
+    sealable: bool
+    blocking: tuple
+    certificate: Optional[dict]
+
+
+def decide_seal(conversation_key: str, revision: int,
+                targets: Iterable[Target], members: Iterable[MemberFact], *,
+                timestamps: "tuple[str | None, str | None] | None" = None,
+                retained_thread: Optional[dict] = None,
+                ) -> SealDecision:
+    """Seal a certificate for one conversation, or name what blocks it.
+
+    ``targets`` holds every identity with any membership row for the key
+    (``RETAINED_GENERATION`` rows included); ``members`` those rows. A
+    REQUIRED contributor blocks (the transient pending hold included); a
+    SUSPENDED one is an explicit exclusion whose retained accepted facts
+    still supply metadata (U6): its watermark generation's rows when its
+    membership was proven, else its ``RETAINED_GENERATION`` rows (review N2).
+    ``retained_thread`` is the key's retained thread row: preferred when a
+    candidate supplies it (P2-2), and kept when an exclusion leaves no
+    metadata, so a seal never retracts a published thread to None because of
+    an excluded contributor (P1-1, N2).
+    """
+    by_identity = {t.identity: t for t in targets}
+    verdicts = {i: classify_target(t) for i, t in by_identity.items()}
+    blocking = tuple(sorted((i, v.reason) for i, v in verdicts.items()
+                            if v.state == REQUIRED))
+    if blocking:
+        return SealDecision(False, blocking, None)
+    facts = list(members)
+    contributors, exclusions, candidates = [], [], []
+    for identity in sorted(by_identity):
+        target, verdict = by_identity[identity], verdicts[identity]
+        if verdict.state == READY:
+            contributors.append({
+                "identity": identity, "path": target.source_path,
+                "generation": target.generation,
+                "completeLineEnd": int(target.complete_line_end)})
+            effective = target.generation
+        else:
+            exclusions.append({
+                "identity": identity, "path": target.source_path,
+                "reason": verdict.reason,
+                "acceptedGeneration": target.watermark_generation})
+            effective = (target.watermark_generation
+                         if target.watermark_generation is not None
+                         else RETAINED_GENERATION)
+        candidates.extend(f for f in facts if f.identity == identity
+                          and f.generation == effective)
+    thread = select_thread(candidates, retained=retained_thread)
+    if thread is None and retained_thread is not None and exclusions:
+        # U6 / reviews P1-1, N2: an unreadable contributor never changes an
+        # existing publication on its own, and it never freezes the key.
+        # When no readable contributor and no retained fact supplies a
+        # thread, the retained one is kept. Thread None is sealed only when
+        # every contributor is readable and none supplies metadata, or when
+        # there is no retained thread to retract.
+        thread = {name: retained_thread.get(name) for name in THREAD_FIELDS}
+    if thread is not None and timestamps is not None:
+        thread = dict(thread, firstSeenUtc=timestamps[0],
+                      lastSeenUtc=timestamps[1])
+    return SealDecision(True, (), {
+        "version": CERTIFICATE_VERSION,
+        "conversationKey": conversation_key,
+        "revision": int(revision),
+        "contributors": contributors,
+        "exclusions": exclusions,
+        "thread": thread,
+    })
+
+
+def certificate_json(cert: dict) -> str:
+    return json.dumps(cert, sort_keys=True, separators=(",", ":"),
+                      ensure_ascii=True)
+
+
+def parse_certificate(text) -> Optional[dict]:
+    try:
+        cert = json.loads(text)
+    except (TypeError, ValueError):
+        return None
+    if not isinstance(cert, dict) or cert.get("version") != CERTIFICATE_VERSION:
+        return None
+    return cert
+
+
+def certificate_covers(cert: dict, source_path: str,
+                       generation: str) -> Optional[int]:
+    """The certified complete-line end for this file at this generation."""
+    for contributor in cert.get("contributors", ()):
+        if (contributor.get("path") == source_path
+                and contributor.get("generation") == generation):
+            return int(contributor["completeLineEnd"])
+    return None
+
+
+def certificate_excludes(cert: dict, source_path: str) -> bool:
+    return any(e.get("path") == source_path for e in cert.get("exclusions", ()))
+
+
+def publication_advances(published_revision, candidate_revision) -> bool:
+    """Monotonic publication: only a strictly newer revision may publish."""
+    return int(candidate_revision) > int(published_revision or 0)
+
+
+#: cache.db ``cache_meta``: a fresh token written by every seal batch that
+#: sealed anything (a token, not a counter: a deleted cache.db must never
+#: repeat a value a conversations store has already acknowledged).
+SEAL_SEQ_KEY = "codex_barrier_seal_seq"
+#: conversations.db ``cache_meta``: the seal token whose certificates a
+#: complete publication phase has considered.
+PUBLISHED_SEQ_KEY = "codex_publication_seal_seq"
+#: The TEMP view every conversations connection carries (5.11 "Reader
+#: admission: last-good"); ``codex_conversation_threads`` shadows to it.
+LAST_GOOD_THREADS_VIEW = "codex_last_good_threads"
+#: Certificates newer than their publication, or never published. Run on a
+#: conversations connection with cache.db attached as ``cache_db``.
+BACKLOG_CERTIFICATES_SQL = (
+    "SELECT c.conversation_key, c.revision, c.certificate_json "
+    "FROM cache_db.codex_barrier_certificates c "
+    "LEFT JOIN main.codex_conversation_publications p "
+    "ON p.conversation_key = c.conversation_key "
+    "WHERE p.conversation_key IS NULL OR c.revision > p.published_revision")