cctally 1.115.0 → 1.116.1

package/bin/_cctally_dashboard_envelope.py

@@ -217,9 +217,11 @@ def _select_current_block_for_envelope(
     Delta semantics:
       - Non-crossed block: ``current_used_pct - seven_day_pct_at_block_start``
         (the natural "how much 7d% has changed during this 5h block" read), where
-        that axis is the CREDIT-AWARE read of the column rather than the stored
-        number (#834 S1, #835) — so a value an in-place weekly credit retired makes
-        both the published axis and the delta ``None``.
+        that axis is the block's stored ``seven_day_pct_at_block_start``. #835's
+        retirement band, which published ``None`` for a value within a point of
+        one an in-place weekly credit retired, is removed (#840): stale
+        contributors are refused before publication, and a stored value that is
+        already wrong is corrected by ``db rederive``'s reviewed ``retract``.
       - Crossed block (``crossed_seven_day_reset == 1``): the block straddles
         a weekly reset, so the natural delta would be dominated by the
         reset itself (e.g. −94pp) rather than the user's actual burn-rate.
@@ -281,21 +283,17 @@ def _select_current_block_for_envelope(
     # Account-qualified selection binds the block and its downstream milestone
     # read to the displayed weekly account; the unqualified order remains the
     # historical <=1-real-account fallback for published byte stability.
-    # #834 S1 (#835) Gate A R8: `first_observed_at_utc` and `five_hour_resets_at`
-    # are selected because the credit-aware read below needs them — they are the
-    # START axis's capture instant and its fallback. `seven_day_pct_at_block_end`
-    # is deliberately NOT selected, and round three's comment claiming the
-    # credit-aware read needs it was wrong: this route publishes the start axis
-    # alone, the helper's second return value is discarded, and the helper tests
-    # each axis's stored value before resolving anything, so an absent end value
-    # skips a second week resolution and a second band set for a number nobody
-    # reads. `last_observed_at_utc` stays, and NOT because the helper needs it:
-    # every column the helper reads goes through `block.get(...)`, so dropping
-    # this one would raise nothing and change no published field — the end
-    # instant it feeds is discarded with the end axis. It stays because the
-    # helper's contract is a block ROW, and pruning this SELECT to the subset the
-    # helper happens to read today would couple this route to the helper's
-    # internals. Round four's comment implied necessity instead.
+    # #834 S1 (#835) Gate A R8 selected `first_observed_at_utc`,
+    # `five_hour_resets_at` and `last_observed_at_utc` for the retirement band's
+    # week resolution. Since the band's removal (#840) the axes helper below
+    # reads only the stored `seven_day_pct_at_block_start` /
+    # `seven_day_pct_at_block_end` through `block.get(...)`, so none of the three
+    # is needed by it; they stay because the helper's contract is a block ROW,
+    # and pruning this SELECT to the subset the helper happens to read today
+    # would couple this route to the helper's internals.
+    # `seven_day_pct_at_block_end` is not selected: this route publishes the
+    # start axis alone and discards the helper's second return value, which is
+    # then `None`.
     block = conn.execute(
         """
         SELECT id, account_key,
@@ -319,14 +317,14 @@ def _select_current_block_for_envelope(
 
     crossed = bool(block["crossed_seven_day_reset"])
     # #834 S1 (#835) Gate A R8: THE THIRD CONSUMER of the two derived weekly axes
-    # goes through the one read-time filter, the same one `cmd_five_hour_blocks` and
-    # `cmd_five_hour_breakdown` use. Reading the column raw published the value an
-    # in-place weekly credit retired, and `seven_day_pct_delta_pp` then published
-    # the difference between the live post-credit percentage and that retired
-    # number, which is a burn nobody observed. Measured on a store credited at 63.0
-    # with `current_used_pct` at 20.0: `seven_day_pct_at_block_start: 63.0` and
-    # `seven_day_pct_delta_pp: -43.0`, while the helper answered `(None, None)` for
-    # the same row. `sqlite3.Row` has no `.get()`, so the row is converted.
+    # goes through the one shared axes helper, the same one `cmd_five_hour_blocks`
+    # and `cmd_five_hour_breakdown` use. #835 made that helper a read-time filter
+    # that withheld a value within a point of one an in-place weekly credit
+    # retired; #840 removed that retirement band, so the helper now returns the
+    # block's stored axes. A stale contributor is refused before it is
+    # published, and a stored value that is already wrong is corrected by
+    # `db rederive`'s reviewed `retract`, never by a percentage heuristic here.
+    # `sqlite3.Row` has no `.get()`, so the row is converted.
     #
     # Neither field is rendered by any client today: both are declared in
     # `dashboard/web/src/types/envelope.ts` and used in one vitest module,
@@ -2193,18 +2191,14 @@ def snapshot_to_envelope(snap: "DataSnapshot", *,
             _ld = sys.modules["cctally"]._load_sibling("_lib_doctor")
             _doc_state = sys.modules["cctally"].doctor_gather_state(now_utc=now_utc, runtime_bind=runtime_bind)
             _doc_report = _ld.run_checks(_doc_state)
-            doctor_envelope = {
-                "severity":     _doc_report.overall_severity,
-                "counts":       dict(_doc_report.counts),
-                "generated_at": _ld._iso_z(_doc_report.generated_at),
-                "fingerprint":  _ld.fingerprint(_doc_report),
-            }
+            doctor_envelope = _ld.envelope_block(_doc_report)
         except Exception as exc:  # noqa: BLE001 — never crash SSE on doctor failure
             doctor_envelope = {
                 "severity":     "fail",
                 "counts":       {"ok": 0, "warn": 0, "fail": 1},
                 "generated_at": _iso_z(now_utc),
                 "fingerprint":  "sha1:" + ("0" * 40),
+                "rebuild_worker": None,
                 "_error":       f"{type(exc).__name__}: {exc}",
             }
 

package/bin/_cctally_db.py

@@ -9154,6 +9154,13 @@ def _027_codex_fork_preamble_rebuild(conn: sqlite3.Connection) -> None:
         _release_cache_db_writer_flocks(held)
 
 
+#: Pages 028 returns per committed transaction when it reclaims the dropped
+#: transcript store. The chunk bounds each transaction's WAL growth at roughly,
+#: but more than, one SQLite WAL auto-checkpoint (1000 frames): each moved page
+#: also writes its pointer-map page, its parent and the header page.
+_028_VACUUM_CHUNK_PAGES = 1000
+
+
 @cache_migration("028_split_conversation_store")
 def _028_split_conversation_store(conn: sqlite3.Connection) -> None:
     """Move the re-derivable transcript corpus out of cache.db (#320).
@@ -9263,11 +9270,45 @@ def _028_split_conversation_store(conn: sqlite3.Connection) -> None:
             raise
         try:
             if conn.execute("PRAGMA auto_vacuum").fetchone()[0] == 2:
-                # Python 3.11/Linux may defer this zero-column PRAGMA until the
-                # cursor is exhausted; fetchall drives it to completion.
-                conn.execute("PRAGMA incremental_vacuum").fetchall()
+                # Return the dropped tables' pages one page per statement. A
+                # bare `PRAGMA incremental_vacuum` returns no columns, and
+                # CPython 3.11's cursor steps such a statement exactly once,
+                # fetchall() or not, so it frees ONE page (#998). A statement
+                # capped at one page is complete after that first step on every
+                # Python (the `_run_incremental_vacuum_chunk` pattern). Each
+                # chunk commits so WAL auto-checkpoints run between chunks, and
+                # the loop stops when a chunk frees nothing, so it is bounded.
+                remaining = conn.execute("PRAGMA freelist_count").fetchone()[0]
+                while remaining:
+                    # Any failure inside a chunk, including a non-database
+                    # error or an interrupt, rolls that chunk back before it
+                    # propagates, so no write transaction outlives the
+                    # conversation locks released below.
+                    try:
+                        conn.execute("BEGIN IMMEDIATE")
+                        for _ in range(min(remaining, _028_VACUUM_CHUNK_PAGES)):
+                            conn.execute("PRAGMA incremental_vacuum(1)").fetchall()
+                        conn.commit()
+                    except BaseException:
+                        try:
+                            conn.rollback()
+                        except sqlite3.Error:
+                            pass
+                        raise
+                    left = conn.execute("PRAGMA freelist_count").fetchone()[0]
+                    if left >= remaining:
+                        break
+                    remaining = left
         except sqlite3.DatabaseError:
-            pass
+            # Intentional: the reclaim is best effort. Raising here would leave
+            # 028 unapplied, and its next run would re-arm both conversation
+            # store rebuild-from-scratch flags; free pages left behind are
+            # harmless and `db vacuum` returns them. The guarded rollback keeps
+            # a failing rollback from turning that into a handler failure.
+            try:
+                conn.rollback()
+            except sqlite3.Error:
+                pass
     finally:
         for fh in reversed(held):
             try:
@@ -11312,6 +11353,9 @@ def cmd_db_status(args: argparse.Namespace) -> int:
             ),
         },
     }
+    # #997 D10: additive — each detached rebuild worker's state and its
+    # read-only classification (the doctor `db.rebuild_worker` kernel).
+    payload["rebuildWorkers"] = _db_status_rebuild_workers()
     if getattr(args, "json", False):
         print(json.dumps(payload, indent=2, sort_keys=True))
         return 0
@@ -11329,9 +11373,46 @@ def cmd_db_status(args: argparse.Namespace) -> int:
             line = _db_status_format_row(m)
             print(line)
         print()  # blank line between DBs
+    for worker in ("epoch", "heal"):
+        info = payload["rebuildWorkers"][worker]
+        if info["classification"]["row"] != "idle":
+            print(info["classification"]["summary"])
     return 0
 
 
+def _db_status_rebuild_workers() -> dict:
+    """``{"epoch": {...}, "heal": {...}}``: each worker's run state and its
+    classification, gathered without any lock (#997 D8/D10)."""
+    import _cctally_store
+    import _lib_doctor
+
+    now_utc = _cctally_core._command_as_of()
+    out: dict = {}
+    for worker in ("epoch", "heal"):
+        try:
+            snapshot = _cctally_store.rebuild_worker_snapshot(worker)
+        except Exception:  # noqa: BLE001 — a diagnostic never fails status
+            snapshot = None
+        assessed = _lib_doctor.assess_rebuild_worker(worker, snapshot,
+                                                     now_utc)
+        details = assessed["details"]
+        out[worker] = {
+            "state": details["state"],
+            "stateUnreadable": details["stateUnreadable"],
+            "ledger": details["ledger"],
+            "liveness": details["liveness"],
+            "pending": details["pending"],
+            "recoveredDeaths": details["recoveredDeaths"],
+            "classification": {
+                "severity": assessed["severity"],
+                "row": assessed["row"],
+                "summary": assessed["summary"],
+                "warnings": assessed["warnings"],
+            },
+        }
+    return out
+
+
 def _db_status_for(
     db_path: pathlib.Path,
     registry: list[Migration],

package/bin/_cctally_doctor.py

@@ -507,6 +507,31 @@ def _fetch_dashboard_write_io(descriptor: dict, *, timeout_s: float) -> dict:
     return {**base, "probe": "ok", "reason": None, "write_io": write_io}
 
 
+_REBUILD_WORKERS = ("epoch", "heal")
+
+
+def _rebuild_worker_gather_failed(worker: str, exc: BaseException) -> dict:
+    """A snapshot that could not be gathered reads as an unreadable state
+    (the existing row), with the error in `details`, never as "has run"."""
+    return {"worker": worker, "state": None, "stateUnreadable": True,
+            "ledger": None, "ledgerUnreadable": False, "identities": {},
+            "pending": {}, "reread": False,
+            "gatherError": f"{type(exc).__name__}: {exc}"}
+
+
+def _gather_rebuild_workers() -> dict:
+    """#997 D10: each detached rebuild worker's read-only snapshot; a worker
+    whose snapshot fails is reported unreadable, the other still gathered."""
+    out: dict = {}
+    for worker in _REBUILD_WORKERS:
+        try:
+            import _cctally_store
+            out[worker] = _cctally_store.rebuild_worker_snapshot(worker)
+        except Exception as exc:  # noqa: BLE001 — reported, never fatal
+            out[worker] = _rebuild_worker_gather_failed(worker, exc)
+    return out
+
+
 def _gather_dashboard_disk_writes(
     *, fetch=None, timeout_s: float = DASHBOARD_WRITE_IO_TIMEOUT_SECONDS,
     discover: bool = True,
@@ -559,6 +584,7 @@ def _gather_legacy_writer(deep_excluded, deep_boundary,
     says the detection pause exists only when the validated index holds the
     durable `inventory-incomplete` marker. Read-only: the sidecar is never
     written here, the spool is only read, and nothing is journaled."""
+    import _cctally_journal
     import _cctally_store
     import _lib_account_protocol
 
@@ -579,11 +605,9 @@ def _gather_legacy_writer(deep_excluded, deep_boundary,
                 pc.close()
     except Exception:  # noqa: BLE001 — a diagnostic read degrades to unavailable
         row = None
-    try:
-        evidence = json.loads(
-            _cctally_core.LEGACY_WRITER_EVIDENCE_PATH.read_bytes())
-    except (OSError, ValueError):
-        evidence = None
+    # #797/#823/#840 review RV-5: the v2 sidecar, else the previous
+    # release's v1 one (read only) as its seed.
+    evidence, _seeded = _cctally_journal.read_legacy_writer_evidence_document()
     inventory = _legacy_spool_inventory_probe(inventory_marker)
     if inventory is not None:
         out["legacySpoolInventory"] = inventory
@@ -3208,6 +3232,14 @@ def _doctor_gather_state_impl(
                 discover=_discover_dashboards)
     except Exception:  # noqa: BLE001 — a probe failure must not fail doctor
         dashboard_disk_writes = {"mode": "error", "instances": []}
+    # #997 D10: the detached rebuild workers, read-only (no worker or
+    # admission flock is taken; a probe would make a starting worker `busy`).
+    try:
+        with _lib_perf.phase("doctor.rebuild_workers"):
+            rebuild_workers = _gather_rebuild_workers()
+    except Exception as exc:  # noqa: BLE001 — a gather failure must not fail doctor
+        rebuild_workers = {worker: _rebuild_worker_gather_failed(worker, exc)
+                           for worker in _REBUILD_WORKERS}
     return _lib_doctor.DoctorState(
         symlink_state=symlink_state,
         path_includes_local_bin=path_includes,
@@ -3318,6 +3350,7 @@ def _doctor_gather_state_impl(
         conversations_db_freelist_count=conversations_db_freelist_count,
         conversations_db_page_size=conversations_db_page_size,
         dashboard_disk_writes=dashboard_disk_writes,
+        rebuild_workers=rebuild_workers,
         conversations_reclaim_pending=conversations_reclaim_pending,
         codex_quota_windows=codex_quota_windows,
         codex_hook_roots=codex_hook_roots,