cctally 1.115.0 → 1.116.0

package/bin/_lib_doctor.py

@@ -479,6 +479,11 @@ class DoctorState:
     # descriptor discovery plus one bounded loopback probe per live
     # instance elsewhere. {"mode", "instances": [...]}; None = not gathered.
     dashboard_disk_writes: Optional[dict] = None
+    # #997 D10: per detached rebuild worker ("epoch", "heal"), the read-only
+    # snapshot `_cctally_store.rebuild_worker_snapshot` gathered (run state,
+    # launch ledger, process identities probed before a re-read, pending
+    # marker). None = not gathered; the check then reads both as never run.
+    rebuild_workers: Optional[dict] = None
 
 
 @dataclasses.dataclass(frozen=True)
@@ -1049,7 +1054,7 @@ def _check_db_version_ahead(s: DoctorState) -> CheckResult:
             # current index as a mismatch; keep this in lockstep with core
             # (#496 S5b §6.1). It stays a literal because this kernel is pure and
             # must not import `_cctally_core`.
-            epoch = 1018
+            epoch = 1019
         mismatch = uv > legacy_head and uv != epoch
         return {"user_version": uv, "legacy_head": legacy_head, "epoch": epoch,
                 "mismatch": mismatch}
@@ -1105,6 +1110,267 @@ def _check_db_version_ahead(s: DoctorState) -> CheckResult:
     )
 
 
+# --- #997 D10: the detached rebuild workers -------------------------------
+#
+# `rebuild_workers` is gathered read-only by `doctor_gather_state` through
+# `_cctally_store.rebuild_worker_snapshot` (no worker or admission flock is
+# ever taken): per worker the run state, the launch ledger, the process
+# identities probed BEFORE a re-read of both files, and the pending marker.
+# The kernel classifies it with `_lib_worker_launches` (read-only) — a death is
+# never inferred from elapsed time.
+
+#: No progress write for this long reads as "no progress" (spec D10).
+REBUILD_STALL_SECONDS = 600
+#: A marker pending this long with no worker running warns.
+REBUILD_PENDING_SECONDS = 600
+#: Recovered deaths this recent are listed in `details`.
+REBUILD_RECENT_DEATH_SECONDS = 7 * 86400
+#: §5.2's resident-memory bound.
+REBUILD_MEMORY_BOUND_BYTES = 2 * 1024 ** 3
+
+_REBUILD_NOUN = {"epoch": "stats.db upgrade rebuild",
+                 "heal": "stats.db auto-heal"}
+_REBUILD_CLEAN = {
+    "epoch": frozenset({"success", "current"}),
+    "heal": frozenset({"success", "no-request", "declined-readable"}),
+}
+_REBUILD_RETRYABLE = {
+    "epoch": frozenset(),
+    "heal": frozenset({"maintenance-busy", "ingest-busy"}),
+}
+
+
+def rebuild_outcome_class(worker: str, outcome, *, decline_reason=None,
+                          finalization=None) -> str:
+    """``clean`` | ``retryable`` | ``failing`` (spec D10 outcome classes).
+
+    ``declined-unconfirmed`` is clean only when the store re-probed healthy
+    (``integrity_check_ok``). A pending finalization never lowers the primary
+    class: it turns a clean outcome retryable and leaves a failing one
+    failing. Any outcome not listed is failing until it is added.
+    """
+    if worker == "heal" and outcome == "declined-unconfirmed":
+        primary = ("clean" if decline_reason == "integrity_check_ok"
+                   else "failing")
+    elif outcome in _REBUILD_CLEAN.get(worker, ()):
+        primary = "clean"
+    elif outcome in _REBUILD_RETRYABLE.get(worker, ()):
+        primary = "retryable"
+    else:
+        primary = "failing"
+    if primary == "clean" and finalization == "pending":
+        return "retryable"
+    return primary
+
+
+def _rebuild_parse_iso(value) -> "dt.datetime | None":
+    if not isinstance(value, str) or not value:
+        return None
+    try:
+        parsed = dt.datetime.fromisoformat(value.replace("Z", "+00:00"))
+    except ValueError:
+        return None
+    if parsed.tzinfo is None:
+        parsed = parsed.replace(tzinfo=dt.timezone.utc)
+    return parsed
+
+
+def _rebuild_age_seconds(now: dt.datetime, value) -> "float | None":
+    parsed = _rebuild_parse_iso(value)
+    if parsed is None:
+        return None
+    if now.tzinfo is None:
+        now = now.replace(tzinfo=dt.timezone.utc)
+    return max(0.0, (now - parsed).total_seconds())
+
+
+def _rebuild_minutes(seconds) -> int:
+    return int((seconds or 0) // 60)
+
+
+def _rebuild_ledger_summary(ledger: dict) -> dict:
+    import _lib_worker_launches as wl
+    return {
+        "unresolved": [dict(e) for e in wl.unresolved(ledger)],
+        "counts": dict(ledger.get("counts") or {}),
+        "lastDeathAt": ledger.get("lastDeathAt"),
+        "newest": dict(wl.newest(ledger) or {}) or None,
+    }
+
+
+def assess_rebuild_worker(worker: str, snapshot, now_utc) -> dict:
+    """One worker's D10 classification from its read-only snapshot.
+
+    Returns ``{"severity", "warnings": [sentence, ...], "summary", "row",
+    "details"}``: ``warnings`` holds every warn sentence in table order and
+    ``summary`` the single sentence that describes the worker.
+    """
+    import _lib_worker_launches as wl
+
+    noun = _REBUILD_NOUN[worker]
+    snapshot = snapshot or {}
+    state = snapshot.get("state")
+    run = state.get("run") if isinstance(state, dict) else None
+    run = run if isinstance(run, dict) else None
+    identities = snapshot.get("identities") or {}
+    ledger = snapshot.get("ledger") or wl.empty_ledger()
+    # Read-only: settlements the evidence supports, never written back.
+    classified = wl.classify(ledger, state, identities)["ledger"]
+    pending = snapshot.get("pending") or {}
+    warnings: list = []
+    rows: list = []
+    details: dict = {
+        "state": state,
+        "stateUnreadable": bool(snapshot.get("stateUnreadable")),
+        "ledgerUnreadable": bool(snapshot.get("ledgerUnreadable")),
+        "ledger": _rebuild_ledger_summary(classified),
+        "liveness": None,
+        "pending": pending,
+        "recoveredDeaths": [],
+    }
+    if snapshot.get("gatherError"):
+        details["gatherError"] = snapshot["gatherError"]
+
+    if snapshot.get("stateUnreadable"):
+        rows.append("unreadable")
+        warnings.append(f"the {noun} state is unreadable")
+
+    running = run is not None and run.get("status") == "running"
+    running_alive = False
+    if running:
+        live = wl.liveness(run, identities)
+        details["liveness"] = live
+        if live != "gone":
+            running_alive = True
+            n = _rebuild_minutes(_rebuild_age_seconds(now_utc,
+                                                      run.get("startedAt")))
+            idle = _rebuild_age_seconds(
+                now_utc, run.get("progressAt") or run.get("startedAt"))
+            if idle is not None and idle >= REBUILD_STALL_SECONDS:
+                rows.append("stalled")
+                warnings.append(
+                    f"a {noun} has been running for {n} minutes with no "
+                    f"progress for {_rebuild_minutes(idle)} minutes")
+            else:
+                rows.append("running")
+                warnings.append(f"a {noun} has been running for {n} minutes")
+
+    # The last decisive launch, in ledger (launch) order: a launch not yet
+    # started (unacknowledged, unresolved) and a `busy` loser decide nothing.
+    decisive = None
+    for entry in reversed(classified.get("entries") or []):
+        outcome = entry.get("outcome")
+        if outcome == "busy":
+            continue
+        if not outcome and not (isinstance(entry.get("ack"), dict)
+                                and entry["ack"].get("kind") == "started"):
+            continue
+        decisive = entry
+        break
+    finished_run = run if run is not None and run.get("status") == "finished" \
+        else None
+    ok_summary = None
+    if not running_alive:
+        # A state still `running` whose process is confirmed gone is a death:
+        # any newer run would have replaced the slot when it started.
+        died = bool(decisive and decisive.get("outcome") in wl.DEATHS) \
+            or running
+        if died:
+            rows.append("died")
+            warnings.append(f"the last {noun} died without finishing")
+            details["preStart"] = bool(
+                decisive and decisive.get("outcome") == "died-pre-start")
+            details["launchId"] = (decisive or run or {}).get("launchId")
+        elif decisive is not None and decisive.get("outcome") == "spawn-failed":
+            rows.append("spawn-failed")
+            warnings.append(f"the last {noun} failed (spawn-failed)")
+        else:
+            outcome = decline = finalization = peak = None
+            if finished_run is not None and (
+                    decisive is None
+                    or decisive.get("launchId") == finished_run.get("launchId")):
+                outcome = finished_run.get("outcome")
+                decline = finished_run.get("declineReason")
+                finalization = finished_run.get("finalization")
+                peak = finished_run.get("peakResidentBytes")
+            elif decisive is not None and str(
+                    decisive.get("outcome") or "").startswith("finished:"):
+                outcome = decisive["outcome"][len("finished:"):]
+            if outcome is not None:
+                cls = rebuild_outcome_class(
+                    worker, outcome, decline_reason=decline,
+                    finalization=finalization)
+                details["outcomeClass"] = cls
+                if cls == "failing":
+                    rows.append("failed")
+                    warnings.append(f"the last {noun} failed ({outcome})")
+                if isinstance(peak, (int, float)) and \
+                        peak > REBUILD_MEMORY_BOUND_BYTES:
+                    rows.append("memory")
+                    warnings.append(
+                        f"the last {noun} used {peak / 1024 ** 3:.1f} GiB of "
+                        f"memory, above its 2 GiB bound")
+                ok_summary = f"the last {noun} finished ({outcome})"
+        if (pending.get("present") and pending.get("indexPending") is not False):
+            age = _rebuild_age_seconds(now_utc, pending.get("since"))
+            if age is not None and age >= REBUILD_PENDING_SECONDS:
+                rows.append("pending")
+                warnings.append(
+                    f"a {noun} has been pending for {_rebuild_minutes(age)} "
+                    f"minutes with no worker running")
+                if not wl.has_launch_capacity(classified):
+                    # The spawner withholds launches at capacity; the
+                    # pending row says why, with no new sentence.
+                    details["admission"] = "launch-capacity"
+                    details["unresolvedCount"] = len(
+                        wl.unresolved(classified))
+    for death in (state or {}).get("deaths") or []:
+        age = _rebuild_age_seconds(now_utc, death.get("detectedAt"))
+        if age is not None and age <= REBUILD_RECENT_DEATH_SECONDS:
+            details["recoveredDeaths"].append(dict(death))
+    if ok_summary is None:
+        ok_summary = f"no {noun} has run"
+    severity = "warn" if warnings else "ok"
+    details["rows"] = rows
+    return {
+        "severity": severity,
+        "warnings": warnings,
+        "summary": warnings[0] if warnings else ok_summary,
+        "row": rows[0] if rows else ("idle" if state is None else "ok"),
+        "details": details,
+    }
+
+
+def _check_db_rebuild_worker(s: DoctorState) -> CheckResult:
+    """`db.rebuild_worker` (#997 D10): running, stalled, dead, failed or
+    pending stats.db upgrade rebuilds and auto-heals."""
+    return rebuild_worker_check(s.rebuild_workers, s.now_utc)
+
+
+def rebuild_worker_check(rebuild_workers, now_utc) -> CheckResult:
+    """The `db.rebuild_worker` result from the gathered worker snapshots
+    alone. The doctor check and the dashboard's deferred frames
+    (`rebuild_worker_envelope_value`) both build it here, so their wording
+    and precedence cannot drift apart."""
+    snapshots = rebuild_workers or {}
+    assessed = {
+        worker: assess_rebuild_worker(worker, snapshots.get(worker),
+                                      now_utc)
+        for worker in ("epoch", "heal")
+    }
+    warnings = [w for worker in ("epoch", "heal")
+                for w in assessed[worker]["warnings"]]
+    severity = _max_severity([a["severity"] for a in assessed.values()])
+    summary = "; ".join(warnings) if warnings else "; ".join(
+        assessed[worker]["summary"] for worker in ("epoch", "heal"))
+    return CheckResult(
+        id="db.rebuild_worker", title="Rebuild worker", severity=severity,
+        summary=summary, remediation=None,
+        details={worker: assessed[worker]["details"]
+                 for worker in ("epoch", "heal")},
+    )
+
+
 def _check_data_latest_snapshot_age(s: DoctorState) -> CheckResult:
     if s.latest_snapshot_at is None:
         return CheckResult(
@@ -4547,6 +4813,7 @@ _CATEGORY_DEFINITIONS: tuple[tuple[str, str, tuple[tuple[str, str], ...]], ...]
         ("db.cache.file", "_check_db_cache_file"),
         ("db.integrity", "_check_db_integrity"),
         ("db.version_ahead", "_check_db_version_ahead"),
+        ("db.rebuild_worker", "_check_db_rebuild_worker"),
         ("db.migrations.applied", "_check_db_migrations_applied"),
         ("db.migrations.pending", "_check_db_migrations_pending"),
         ("db.lock_state", "_check_db_lock_state"),
@@ -5111,6 +5378,40 @@ def fingerprint(report: DoctorReport) -> str:
     return f"sha1:{h}"
 
 
+def rebuild_worker_aggregate(checks) -> "dict | None":
+    """#997 D10: the dashboard aggregate's ``rebuild_worker`` value —
+    ``{severity, summary}`` from the ``db.rebuild_worker`` result when it is
+    not ok, else ``None`` (also when the check is absent)."""
+    for c in checks:
+        if c.id == "db.rebuild_worker":
+            if c.severity == "ok":
+                return None
+            return {"severity": c.severity, "summary": c.summary}
+    return None
+
+
+def rebuild_worker_envelope_value(rebuild_workers, now_utc) -> "dict | None":
+    """#997 D10: exactly the ``rebuild_worker`` value `envelope_block` would
+    carry for these worker snapshots, without the rest of doctor. The
+    dashboard's deferred frames use it while every stats open defers."""
+    return rebuild_worker_aggregate(
+        (rebuild_worker_check(rebuild_workers, now_utc),))
+
+
+def envelope_block(report: DoctorReport) -> dict:
+    """The dashboard envelope's small doctor block for ``report``; the TUI
+    precompute and the envelope's inline path both build it here, so the
+    two producers stay byte-identical."""
+    return {
+        "severity": report.overall_severity,
+        "counts": dict(report.counts),
+        "generated_at": _iso_z(report.generated_at),
+        "fingerprint": fingerprint(report),
+        "rebuild_worker": rebuild_worker_aggregate(
+            c for cat in report.categories for c in cat.checks),
+    }
+
+
 _GLYPH = {"ok": "✓", "warn": "⚠", "fail": "✗"}
 
 

package/bin/_lib_journal.py

@@ -30,6 +30,7 @@ from __future__ import annotations
 import datetime as dt
 import hashlib
 import json
+import sys
 from dataclasses import dataclass
 
 import _lib_account_protocol
@@ -222,6 +223,47 @@ def decode_line(raw: bytes) -> dict | None:
     return obj
 
 
+#: Strings up to this many characters are interned by `compact_retained`.
+#: Keys, kinds, sources, account keys, ids and timestamps fall under it; a
+#: long free-text value is rare enough that sharing it would buy nothing.
+COMPACT_INTERN_MAX_CHARS = 64
+
+
+def compact_retained(value):
+    """An equal copy of a decoded record whose keys and string values of at
+    most `COMPACT_INTERN_MAX_CHARS` characters are ``sys.intern``ed (#997 D15).
+
+    CPython's JSON decoder shares keys only within one ``loads`` call, so
+    every record a pass retains carries its own copy of every key and every
+    repeated short value: 381 k retained records took 0.83 GB decoded and
+    0.375 GB compacted on the maintainer's copy. Recursive through ``dict``
+    and ``list``; every other value (numbers, booleans, ``None``, long
+    strings) is shared unchanged. The result is a NEW record with new
+    containers, so equality, hashing, canonical encoding and mutation behave
+    exactly as on the plain record; only the object identity of equal strings
+    changes, and no consumer compares strings by identity.
+
+    Apply it immediately after decoding, before any consumer holds a
+    reference, so an identity check such as the rederive reader's
+    ``records[index] is record`` only ever sees the compacted object.
+    """
+    return _compact(value)
+
+
+def _compact(value, _intern=sys.intern):
+    kind = type(value)
+    if kind is dict:
+        return {
+            (_intern(key) if type(key) is str else key): _compact(item)
+            for key, item in value.items()
+        }
+    if kind is list:
+        return [_compact(item) for item in value]
+    if kind is str and len(value) <= COMPACT_INTERN_MAX_CHARS:
+        return _intern(value)
+    return value
+
+
 # --------------------------------------------------------------------------
 # identity
 # --------------------------------------------------------------------------
@@ -383,11 +425,29 @@ def effects_payload_digest(payload: dict, refs: dict | None = None) -> str:
 
 _WRITER_GENERATION = _lib_account_protocol.PROTOCOL_GENERATION
 _WPG = _lib_account_protocol.WRITER_GENERATION_KEY
+#: #797/#823/#840 (spec 4.6 B1): the protocol revision stamp, transport
+#: metadata exactly like ``wpg``.
+_WRITER_REVISION = _lib_account_protocol.PROTOCOL_REVISION
+_WPR = _lib_account_protocol.REVISION_KEY
+#: ``writer_revision`` default: the current revision when the record carries
+#: the current writer generation, none for a previous release's shape.
+_REVISION_DEFAULT = object()
+
+
+def _writer_core(core: dict, writer_generation, writer_revision) -> None:
+    if writer_generation is not None:
+        core[_WPG] = writer_generation
+    if writer_revision is _REVISION_DEFAULT:
+        writer_revision = (None if writer_generation is None
+                           else _WRITER_REVISION)
+    if writer_revision is not None:
+        core[_WPR] = writer_revision
 
 
 def make_obs(at: str, src: str, provider: str, payload: dict,
              account: str | None = None, *,
-             writer_generation: str | None = _WRITER_GENERATION) -> dict:
+             writer_generation: str | None = _WRITER_GENERATION,
+             writer_revision=_REVISION_DEFAULT) -> dict:
     """Build a complete ``obs`` line record (raw capture; canonicalization is
     derivation-time, never baked into the stored line — spec §4.2).
 
@@ -401,35 +461,44 @@ def make_obs(at: str, src: str, provider: str, payload: dict,
     writing protocol. It is part of the content-id core, so a current record and
     a previous-release record of the same capture are distinct lines. ``None``
     builds the previous release's exact shape (a validator re-deriving a
-    retained pre-stamp record, or a test simulating an old writer)."""
+    retained pre-stamp record, or a test simulating an old writer).
+
+    ``writer_revision`` (#797/#823/#840 spec 4.6 B1) is the top-level ``wpr``
+    protocol revision, also part of the content-id core. It defaults to the
+    current revision for a current-generation record and to none for a
+    previous release's shape; ``None`` with the current generation builds
+    the revision-1 (#825) shape."""
     core = {"t": "obs", "at": at, "src": src, "provider": provider, "payload": payload}
     if account is not None:
         core["account"] = account
-    if writer_generation is not None:
-        core[_WPG] = writer_generation
+    _writer_core(core, writer_generation, writer_revision)
     return {"v": LINE_VERSION, **core, "id": content_id(core)}
 
 
 def make_op(at: str, src: str, payload: dict, *,
-            writer_generation: str | None = _WRITER_GENERATION) -> dict:
+            writer_generation: str | None = _WRITER_GENERATION,
+            writer_revision=_REVISION_DEFAULT) -> dict:
     """Build a complete ``op`` (operator record) line — no ``provider``.
-    ``writer_generation`` as in ``make_obs``."""
+    ``writer_generation`` and ``writer_revision`` as in ``make_obs``."""
     core = {"t": "op", "at": at, "src": src, "payload": payload}
-    if writer_generation is not None:
-        core[_WPG] = writer_generation
+    _writer_core(core, writer_generation, writer_revision)
     return {"v": LINE_VERSION, **core, "id": content_id(core)}
 
 
 def prepare_record(record: dict) -> dict:
     """The single shared preparation step both append APIs apply (#825/#832
-    spec 5.1): return ``record`` carrying the current writer generation.
-
-    A content-id record (``id`` starting ``o:``) that is not yet stamped and
-    whose id verifies over its unstamped core is re-identified over the stamped
-    core, exactly as the builders compute it. Every other id — semantic event
-    ids, bootstrap ids, correction batch ids, a content id that does not verify
-    — is preserved. Idempotent: a stamped record is returned unchanged."""
-    if _lib_account_protocol.is_stamped(record):
+    spec 5.1): return ``record`` carrying the current writer generation and,
+    since #797/#823/#840 (spec 4.6 B1), the current protocol revision.
+
+    A content-id record (``id`` starting ``o:``) that is not yet fully
+    stamped and whose id verifies over its current core is re-identified over
+    the stamped core, exactly as the builders compute it. Every other id —
+    semantic event ids, bootstrap ids, correction batch ids, a content id
+    that does not verify — is preserved. Idempotent: a record carrying both
+    stamps is returned unchanged. Only records about to be appended pass
+    through here, so a retained record is never restamped."""
+    if (_lib_account_protocol.is_stamped(record)
+            and _lib_account_protocol.has_current_revision(record)):
         return record
     stamped = _lib_account_protocol.stamp(record)
     rid = record.get("id")
@@ -448,10 +517,30 @@ def unstamped_record(record: dict) -> dict:
     ``prepare_record``. Drops the writer-generation stamp and, for a content-id
     record whose id verifies over its stamped core, re-identifies it over the
     unstamped core. Any other id is preserved. For fixtures and tests that
-    simulate a pre-stamp writer; never used on a production write path."""
-    if not isinstance(record, dict) or _WPG not in record:
+    simulate a pre-stamp writer; never used on a production write path.
+    The protocol revision (``wpr``) goes with the stamp."""
+    if not isinstance(record, dict) or (
+            _WPG not in record and _WPR not in record):
+        return record
+    out = {k: v for k, v in record.items() if k not in (_WPG, _WPR)}
+    rid = record.get("id")
+    if (record.get("t") in ("obs", "op") and isinstance(rid, str)
+            and rid.startswith("o:")):
+        core = {k: v for k, v in record.items() if k not in ("v", "id")}
+        if content_id(core) == rid:
+            out["id"] = content_id(
+                {k: v for k, v in out.items() if k not in ("v", "id")})
+    return out
+
+
+def prerevision_record(record: dict) -> dict:
+    """The revision-1 (#825 release) shape of ``record``: the current writer
+    generation without the protocol revision, re-identified like
+    ``unstamped_record``. For fixtures and tests that simulate the previous
+    release; never used on a production write path."""
+    if not isinstance(record, dict) or _WPR not in record:
         return record
-    out = {k: v for k, v in record.items() if k != _WPG}
+    out = {k: v for k, v in record.items() if k != _WPR}
     rid = record.get("id")
     if (record.get("t") in ("obs", "op") and isinstance(rid, str)
             and rid.startswith("o:")):
@@ -510,11 +599,15 @@ def event_content_hash(record: dict) -> str:
 #: The previous release's exact-key repair acknowledgement. The current binary
 #: never emits it: its validator would reject the writer-generation stamp, so
 #: current acknowledgements use the versioned kind the previous release ignores
-#: as an unknown op (#825/#832 spec 5.1). Current readers accept both.
+#: as an unknown op (#825/#832 spec 5.1). Current readers accept every kind.
 _PROTOCOL_RESOLUTION_KIND = "journal_protocol_resolution"
 _PROTOCOL_RESOLUTION_V2_KIND = _lib_account_protocol.PROTOCOL_RESOLUTION_V2_KIND
+#: #797/#823/#840 (spec 4.6 B5): the previous release's v2 validator rejects
+#: the protocol revision stamp, so the current binary emits this successor.
+PROTOCOL_RESOLUTION_V3_KIND = _lib_account_protocol.PROTOCOL_RESOLUTION_V3_KIND
 PROTOCOL_RESOLUTION_KINDS = frozenset((
-    _PROTOCOL_RESOLUTION_KIND, _PROTOCOL_RESOLUTION_V2_KIND))
+    _PROTOCOL_RESOLUTION_KIND, _PROTOCOL_RESOLUTION_V2_KIND,
+    PROTOCOL_RESOLUTION_V3_KIND))
 _PROTOCOL_RESOLUTION_SRC = "journal-repair"
 
 
@@ -554,7 +647,7 @@ def make_protocol_resolution(
         at=at,
         src=_PROTOCOL_RESOLUTION_SRC,
         payload={
-            "kind": _PROTOCOL_RESOLUTION_V2_KIND,
+            "kind": PROTOCOL_RESOLUTION_V3_KIND,
             "violations": refs,
             "journal_high_water": {
                 "segment": segment,
@@ -588,7 +681,7 @@ def make_evt(kind: str, id: str, at: str, payload: dict, rev: int = 0) -> dict:
     body["kind"] = kind
     return {"v": LINE_VERSION, "t": "evt", "id": id, "rev": rev,
             "at": at, "src": "ingest", "payload": body,
-            _WPG: _WRITER_GENERATION}
+            _WPG: _WRITER_GENERATION, _WPR: _WRITER_REVISION}
 
 
 # --------------------------------------------------------------------------
@@ -627,8 +720,10 @@ def _protocol_violation(
 def _validate_protocol_resolution(record: dict) -> dict:
     required = {"v", "t", "id", "at", "src", "payload"}
     # #825/#832: a current record also carries the writer-generation stamp,
-    # which is part of its content-id core.
-    if set(record) not in (required, required | {_WPG}):
+    # which is part of its content-id core; #797/#823/#840 adds the protocol
+    # revision (spec 4.6 B5).
+    if set(record) not in (required, required | {_WPG},
+                           required | {_WPG, _WPR}):
         raise JournalProtocolError(
             "journal protocol resolution record shape is invalid"
         )
@@ -650,6 +745,8 @@ def _validate_protocol_resolution(record: dict) -> dict:
     }
     if _WPG in record:
         core[_WPG] = record[_WPG]
+    if _WPR in record:
+        core[_WPR] = record[_WPR]
     if record.get("id") != content_id(core):
         raise JournalProtocolError(
             "journal protocol resolution record id does not match its content"
@@ -802,6 +899,7 @@ def make_correction_batch(
         "action_count": len(cores),
         "actions_hash": actions_hash,
         _WPG: _WRITER_GENERATION,
+        _WPR: _WRITER_REVISION,
     }
     records = [{**marker, "phase": "begin"}]
     for seq, core in enumerate(cores):
@@ -813,12 +911,34 @@ def make_correction_batch(
                 "batch": batch_id,
                 "seq": seq,
                 _WPG: _WRITER_GENERATION,
+                _WPR: _WRITER_REVISION,
             }
         )
     records.append({**marker, "phase": "commit"})
     return records
 
 
+def revision_batch_id(batch_id: str, begins) -> str:
+    """The batch id a retry of ``batch_id`` appends under (#797/#823/#840
+    spec 4.6 B1).
+
+    ``begins`` are the retained begin markers already journalled under
+    ``batch_id``. A retry reuses the id only when no begin exists or one
+    carries the current revision stamp. An interrupted batch an earlier
+    writer began without that stamp is never restamped: a revision-2 copy of
+    its lines would be a marker conflict under the original id (the fold
+    hashes markers byte-exactly), and a copy without the stamp would land
+    after the revision boundary, where admission excludes it. Its plan is
+    therefore authored afresh under a derived id, and the original begin
+    stays the inert, incomplete batch it was."""
+    begins = list(begins)
+    if not begins or any(
+            _lib_account_protocol.has_current_revision(begin)
+            for begin in begins):
+        return batch_id
+    return f"{batch_id}:wpr{_lib_account_protocol.PROTOCOL_REVISION}"
+
+
 def _validate_batch_marker(record: dict) -> dict:
     batch_id = record.get("id")
     if not isinstance(batch_id, str) or not batch_id: