cctally 1.93.0 → 1.94.0

package/bin/_cctally_doctor.py

@@ -144,7 +144,179 @@ def _journal_heal_incident(kind: str, name: str, now_utc: dt.datetime) -> dict:
             break
         except ValueError:
             continue
-    return {"kind": kind, "name": name, "age_s": age_s}
+    return {"kind": kind, "name": name, "age_s": age_s, "shape": None}
+
+
+def _incident_shape_token(incident) -> "str | None":
+    """One incident's `damage.preserved.shapeToken` (#496 S6 §7.2 / §3.4).
+
+    Read here rather than in the kernel, which takes no filesystem. A manifest
+    that cannot be read contributes no shape, which is the safe direction: a
+    missing shape cannot manufacture a recurrence.
+    """
+    try:
+        manifest = json.loads(
+            (incident / "manifest.json").read_text(encoding="utf-8")
+        )
+    except (OSError, ValueError):
+        return None
+    if not isinstance(manifest, dict):
+        return None
+    damage = manifest.get("damage")
+    preserved = damage.get("preserved") if isinstance(damage, dict) else None
+    token = preserved.get("shapeToken") if isinstance(preserved, dict) else None
+    return token if isinstance(token, str) and token else None
+
+
+def _gather_heal_detections(now_utc: dt.datetime) -> "list | None":
+    """The durable heal ring, as `{heal_id, age_s}` per entry (§7.2).
+
+    A DETECTION is a ring entry keyed by `healId`, which is a different thing
+    from an incident: a declined or coalesced detection produces a ring entry
+    and no quarantine directory at all, and only the ring can report the RATE.
+    """
+    try:
+        import _cctally_store
+
+        events = _cctally_store.read_stats_heal_events()
+    except Exception:
+        return None
+    found = []
+    for event in events:
+        if not isinstance(event, dict):
+            continue
+        age_s = None
+        stamp = event.get("detectedAtUtc")
+        if isinstance(stamp, str) and stamp:
+            try:
+                parsed = dt.datetime.fromisoformat(stamp.replace("Z", "+00:00"))
+                age_s = int((now_utc - parsed).total_seconds())
+            except ValueError:
+                age_s = None
+        found.append({
+            "heal_id": str(event.get("healId") or ""),
+            "age_s": age_s,
+            "outcome": event.get("outcome"),
+        })
+    return found
+
+
+def _gather_retained_artifacts(
+    now_utc: dt.datetime, *, deep: bool = False,
+) -> "dict | None":
+    """The read-only retention scan and plan behind `db.retained_artifacts`.
+
+    Takes NO lock and writes nothing — it is the same walk and the same kernel
+    plan `cctally db prune`'s preview runs. A malformed policy is reported
+    rather than repaired, because §6.5 makes an unreadable policy a FAIL and
+    not a fallback to the defaults.
+
+    **The walk and the planner are `deep`-gated, like the `quick_check` legs.**
+    This gather is reached from the TUI and the dashboard snapshot precompute
+    on every rebuild, not only from `GET /api/doctor`, and the pair costs tens
+    of milliseconds at the maintainer's corpus size and grows with it. What
+    stays in the shallow path is what an operator must act on and what costs
+    one file read and one glob: the policy resolution and the stuck reclaim
+    records.
+
+    `now_utc` is the gather's clock, which honours `CCTALLY_AS_OF`. Letting the
+    planner read the wall clock instead would make the age bound — and every
+    golden that depends on it — drift with the calendar.
+
+    The failure path names the exception CLASS rather than returning a bare
+    None. Doctor must not crash, but a degrade that says only "unavailable" is
+    indistinguishable from a healthy install with nothing retained, and a
+    programming error here reached four golden fixtures and made all four of
+    them vacuous before anything reported it.
+    """
+    now_epoch = now_utc.timestamp()
+    try:
+        import _cctally_retention
+
+        resolution = _cctally_retention.read_retention_policy()
+        stuck = [
+            {
+                "planId": record["planId"],
+                "memberIds": sorted(record["entries"]),
+                "stuck": bool(record.get("stuck")),
+                "ageSeconds": record.get("ageSeconds"),
+            }
+            for record in _cctally_retention.list_stuck_reclaim_records(
+                now_epoch=now_epoch,
+            )
+        ]
+        if resolution.status == "malformed":
+            # No byte figures are reported, rather than zeros: the scan never
+            # ran, and a zero here is a false measurement a consumer would
+            # render as "nothing retained".
+            return {
+                "policy_status": "malformed",
+                "policy_reason": resolution.reason,
+                "stuck_records": stuck,
+            }
+        bounds = {
+            "max_age_seconds": resolution.policy.max_age_seconds,
+            "max_count_per_family": resolution.policy.max_count_per_family,
+            "max_total_bytes": resolution.policy.max_total_bytes,
+            "min_free_bytes": resolution.policy.min_free_bytes,
+        }
+        if not deep:
+            return {
+                "policy_status": "not-scanned",
+                "policy_reason": None,
+                "stuck_records": stuck,
+                **bounds,
+            }
+        scan, plan, graph = _cctally_retention.plan_retention(
+            policy=resolution.policy, now_epoch=now_epoch, with_graph=True,
+        )
+        return {
+            "policy_status": resolution.status,
+            "policy_reason": None,
+            "retained_bytes": plan.before_bytes,
+            "reclaimable_bytes": plan.reclaimable_bytes,
+            "protected_bytes": _retention_protected_bytes(scan, plan, graph),
+            "protected_roots": len(plan.protected_ids),
+            "roots": len(plan.delete_ids) + len(plan.keep_ids)
+            + len(plan.protected_ids),
+            "free_disk_bytes": scan.free_disk_bytes,
+            "partial_scan": bool(scan.partial),
+            "unsatisfied_rules": list(plan.unsatisfied_rules),
+            # Which bounds actually SELECTED something. The WARN summary used
+            # to name the byte budget whatever drove the reclamation, the same
+            # false sentence the FAIL summary printed.
+            "driving_rules": [
+                rule for rule in _cctally_retention._kernel.BOUND_ORDER
+                if rule in set(plan.reasons.values())
+            ],
+            "floor_retained_roots": len(plan.floor_retained_ids),
+            "floor_retained_bytes": plan.floor_retained_bytes,
+            "stuck_records": stuck,
+            **bounds,
+        }
+    except Exception as exc:  # noqa: BLE001 — doctor never crashes
+        # Read-only diagnostics never fail the gather; the leg degrades. The
+        # class is carried so the degrade is STATED rather than silent.
+        return {"policy_status": "unavailable", "scan_error": type(exc).__name__}
+
+
+def _retention_protected_bytes(scan, plan, graph=None) -> int:
+    """Bytes held by protected roots, counted once across shared members.
+
+    The graph is handed in. Letting `summarize_prune` build its own made the
+    doctor leg construct the reference graph TWICE per gather, once inside
+    `plan_retention` and once here, for a structure neither call mutates.
+    """
+    try:
+        import _cctally_retention
+
+        return int(
+            _cctally_retention.summarize_prune(
+                scan, plan, graph=graph,
+            )["protectedBytes"]
+        )
+    except Exception:
+        return 0
 
 
 def _read_guard_log_tail(path) -> list[str]:
@@ -1770,8 +1942,13 @@ def _doctor_gather_state_impl(
             _incident_read_ok = True
             for entry in qroot.iterdir():
                 if entry.is_dir():
-                    _incidents.append(
-                        _journal_heal_incident("quarantine", entry.name, now_utc))
+                    record = _journal_heal_incident(
+                        "quarantine", entry.name, now_utc)
+                    # §7.2 escalates on a REPEATED damage shape, so the shape
+                    # has to travel with the incident it belongs to — counted
+                    # once per incident, never once per manifest read.
+                    record["shape"] = _incident_shape_token(entry)
+                    _incidents.append(record)
     except OSError:
         pass
     try:
@@ -1791,6 +1968,12 @@ def _doctor_gather_state_impl(
                                        d["age_s"] if d["age_s"] is not None else 0))
         journal_heal_incidents = _incidents
 
+    # #496 S6 §7.2 / §7.3. Both are read-only and take no lock; both degrade to
+    # None rather than failing the gather, because `doctor` is reached from the
+    # TUI and the dashboard snapshot precompute as well as from the CLI.
+    journal_heal_detections = _gather_heal_detections(now_utc)
+    retained_artifacts = _gather_retained_artifacts(now_utc, deep=deep)
+
     # #386/#389 stats sole-writer guard log (spec §6.4). Read-only, fail-soft: an
     # absent log is the NORMAL state and must read as INFO, never as a gather
     # failure. Read only the bounded tail; rotation and cross-process throttling
@@ -1910,6 +2093,8 @@ def _doctor_gather_state_impl(
         journal_hw_segment=journal_hw_segment,
         journal_cursor_segment=journal_cursor_segment,
         journal_heal_incidents=journal_heal_incidents,
+        journal_heal_detections=journal_heal_detections,
+        retained_artifacts=retained_artifacts,
         journal_writer_guard=journal_writer_guard,
         # Multi-account attribution legs (#341).
         accounts_state=accounts_state,

package/bin/_cctally_five_hour.py

@@ -995,6 +995,27 @@ def _load_breakdown(
     return [dict(r) for r in rows]
 
 
+def _blocks_period_instant(raw: object) -> "dt.datetime":
+    """A block boundary as a real INSTANT for the artifact's period.
+
+    `block_start_at` and `five_hour_resets_at` are timestamps, not
+    calendar labels, so they convert into the display zone (#503 S2 D7).
+    Keeping only the UTC date part — which is what this site used to do —
+    named the wrong civil day west of UTC and disagreed with the block's
+    own row cell, which `format_display_dt` renders in the display zone.
+
+    It takes no zone argument. The conversion into the display zone
+    happens in `period_civil_dates`, from the zone the `PeriodSpec` is
+    labelled with, so a zone passed here would be a second authority that
+    could disagree with the first (#503 S2 second review N8).
+    """
+    _c = _cctally()
+    try:
+        return parse_iso_datetime(str(raw), "five_hour_blocks.block_start_at")
+    except (TypeError, ValueError):
+        return _c._share_now_utc()
+
+
 def cmd_five_hour_blocks(args: argparse.Namespace) -> int:
     """List API-anchored 5h blocks with rollup totals + 7d-drift columns."""
     _c = _cctally()
@@ -1172,11 +1193,13 @@ def cmd_five_hour_blocks(args: argparse.Namespace) -> int:
                     since_iso, args._resolved_tz,
                 )
             elif block_dicts:
-                tail = block_dicts[-1].get("block_start_at")
-                period_start = _c._share_parse_date_to_dt(
-                    (tail or "").split("T")[0] or None,
-                    args._resolved_tz,
-                )
+                # A block start is a real INSTANT, so it converts into the
+                # display zone rather than being grounded (#503 S2 D7).
+                # This used to keep only the UTC date part, which named
+                # the wrong civil day west of UTC and disagreed with the
+                # block's own row cell, rendered in the display zone.
+                period_start = _blocks_period_instant(
+                    block_dicts[-1].get("block_start_at"))
             else:
                 period_start = _c._share_now_utc()
             if until_iso:
@@ -1184,11 +1207,17 @@ def cmd_five_hour_blocks(args: argparse.Namespace) -> int:
                     until_iso, args._resolved_tz,
                 )
             elif block_dicts:
-                head = block_dicts[0].get("block_start_at")
-                period_end = _c._share_parse_date_to_dt(
-                    (head or "").split("T")[0] or None,
-                    args._resolved_tz,
-                )
+                # The newest block's END, not its start. A block runs for
+                # five hours and the artifact's rows describe all of it,
+                # so ending the stated period at 13:00 for a block that
+                # runs to 18:00 understated what the artifact covers —
+                # invisible while the period was rendered as a date and
+                # visible the moment the frontmatter carried the full
+                # timestamp (#503 S2 second review N5).
+                newest = block_dicts[0]
+                period_end = _blocks_period_instant(
+                    newest.get("five_hour_resets_at")
+                    or newest.get("block_start_at"))
             else:
                 period_end = _c._share_now_utc()
             # Build a BlocksView from the API-anchored table rows
@@ -1208,8 +1237,6 @@ def cmd_five_hour_blocks(args: argparse.Namespace) -> int:
                 period_end=period_end,
                 display_tz=display_tz_str,
                 version=_c._share_resolve_version(),
-                theme=args.theme,
-                reveal_projects=args.reveal_projects,
                 tz=args._resolved_tz,
             )
             _c._share_render_and_emit(snap, args)

package/bin/_cctally_forecast.py

@@ -1039,22 +1039,21 @@ def cmd_report(args: argparse.Namespace) -> int:
                 # fixture goldens don't drift when the harness host's
                 # wall-clock day rolls past CCTALLY_AS_OF.
                 now_local = _command_as_of().astimezone(tz)
-                local_tz = now_local.tzinfo
                 ws_d, we_d = compute_week_bounds(now_local, week_start_name)
-                ws_dt = dt.datetime.combine(
-                    ws_d, dt.time.min, tzinfo=local_tz
-                )
-                we_dt = dt.datetime.combine(
-                    we_d + dt.timedelta(days=1), dt.time.min, tzinfo=local_tz
-                )
+                # Grounded in the zone the period is LABELLED with, not in
+                # `now_local.tzinfo` (#503 S2 D7). That attribute is the
+                # fixed offset in force right now, so a week that began
+                # under a different DST offset was anchored an hour away
+                # from its own midnight and could state the previous day.
+                ws_dt = c._share_ground_civil_date(ws_d, tz)
+                we_dt = c._share_ground_civil_date(
+                    we_d + dt.timedelta(days=1), tz)
                 snap = c._build_report_snapshot(
                     c.TrendView(),
                     period_start=ws_dt,
                     period_end=we_dt,
                     display_tz=display_tz_str,
                     version=c._share_resolve_version(),
-                    theme=args.theme,
-                    reveal_projects=args.reveal_projects,
                 )
                 c._share_render_and_emit(snap, args)
                 return 0
@@ -1253,8 +1252,6 @@ def cmd_report(args: argparse.Namespace) -> int:
                 period_end=period_end,
                 display_tz=display_tz_str,
                 version=c._share_resolve_version(),
-                theme=args.theme,
-                reveal_projects=args.reveal_projects,
             )
             c._share_render_and_emit(snap, args)
             return 0
@@ -1442,14 +1439,13 @@ def cmd_forecast(args: argparse.Namespace) -> int:
                 config, getattr(args, "week_start_name", None)
             )
             ws_date, we_date = compute_week_bounds(now_utc, week_start_name)
-            # internal fallback: host-local intentional
-            local_tz = dt.datetime.now().astimezone().tzinfo
-            week_start_dt = dt.datetime.combine(
-                ws_date, dt.time.min, tzinfo=local_tz
-            )
-            week_end_dt = dt.datetime.combine(
-                we_date + dt.timedelta(days=1), dt.time.min, tzinfo=local_tz
-            )
+            # Grounded in the zone `display_tz_str` names (#503 S2 D7). It
+            # used to be host-local, which disagrees with the label
+            # whenever `display.tz` names another zone.
+            _res_tz = getattr(args, "_resolved_tz", None)
+            week_start_dt = c._share_ground_civil_date(ws_date, _res_tz)
+            week_end_dt = c._share_ground_civil_date(
+                we_date + dt.timedelta(days=1), _res_tz)
             # Pass `low_conf=False` + explicit notes: the issue is "no data
             # recorded yet," not "thin data." LOW CONF would mislead the
             # reader into thinking a projection ran with sparse samples.
@@ -1458,8 +1454,6 @@ def cmd_forecast(args: argparse.Namespace) -> int:
                 week_end=week_end_dt,
                 display_tz=display_tz_str,
                 version=c._share_resolve_version(),
-                theme=args.theme,
-                reveal_projects=args.reveal_projects,
                 actual_series=[],
                 projected_series=[],
                 current_pct=0.0,
@@ -1564,8 +1558,6 @@ def cmd_forecast(args: argparse.Namespace) -> int:
             week_end=i.week_end_at,
             display_tz=display_tz_str,
             version=c._share_resolve_version(),
-            theme=args.theme,
-            reveal_projects=args.reveal_projects,
             actual_series=actual_series,
             projected_series=projected_series,
             current_pct=float(i.p_now),
@@ -3057,7 +3049,7 @@ def _build_budget_snapshot(
         period_label = c._share_period_label(
             inputs.week_start_at, inputs.week_end_at, tz_label
         )
-        title = f"Budget — week of {inputs.week_start_at.strftime('%b %d')}"
+        title = f"Budget — week of {inputs.week_start_at.date().isoformat()}"
     period_spec = _lib_share.PeriodSpec(
         start=inputs.week_start_at, end=inputs.week_end_at,
         display_tz=tz_label, label=period_label,
@@ -3082,15 +3074,12 @@ def _build_budget_snapshot(
                               "value": _lib_share.MoneyCell(status.projected_eow_high_usd)}),
     )
     notes = ("LOW CONF — early in week",) if status.low_confidence else ()
-    subtitle = " · ".join([
-        period_label,
-        args.theme,
-        "real projects" if args.reveal_projects else "projects anonymized",
-    ])
     return _lib_share.ShareSnapshot(
         cmd="budget",
         title=title,
-        subtitle=subtitle,
+        # #503 S2 D5 — the facts strip states the period and the
+        # privacy mode; the theme is dropped deliberately.
+        subtitle=None,
         period=period_spec,
         columns=columns,
         rows=rows,
@@ -3118,22 +3107,17 @@ def _build_budget_no_data_snapshot(args, budget_cfg, now_utc):
         config, getattr(args, "week_start_name", None)
     )
     ws_date, we_date = compute_week_bounds(now_utc, week_start_name)
-    # internal fallback: host-local intentional
-    local_tz = dt.datetime.now().astimezone().tzinfo
-    week_start_dt = dt.datetime.combine(ws_date, dt.time.min, tzinfo=local_tz)
-    week_end_dt = dt.datetime.combine(
-        we_date + dt.timedelta(days=1), dt.time.min, tzinfo=local_tz
-    )
+    # Grounded in the zone `tz_label` names (#503 S2 D7), not host-local.
+    week_start_dt = c._share_ground_civil_date(ws_date, tz)
+    week_end_dt = c._share_ground_civil_date(we_date + dt.timedelta(days=1), tz)
     period_label = c._share_period_label(week_start_dt, week_end_dt, tz_label)
     target = budget_cfg["weekly_usd"]
-    subtitle = " · ".join([
-        period_label, args.theme,
-        "real projects" if args.reveal_projects else "projects anonymized",
-    ])
     return _lib_share.ShareSnapshot(
         cmd="budget",
-        title=f"Budget — week of {week_start_dt.strftime('%b %d')}",
-        subtitle=subtitle,
+        title=f"Budget — week of {week_start_dt.date().isoformat()}",
+        # #503 S2 D5 — the facts strip states the period and the
+        # privacy mode; the theme is dropped deliberately.
+        subtitle=None,
         period=_lib_share.PeriodSpec(
             start=week_start_dt, end=week_end_dt,
             display_tz=tz_label, label=period_label,
@@ -3172,14 +3156,12 @@ def _build_budget_no_budget_snapshot(args):
         tz = c.resolve_display_tz(args, config)
     tz_label = c._share_display_tz_label(tz)
     period_label = c._share_period_label(now_utc, now_utc, tz_label)
-    subtitle = " · ".join([
-        period_label, args.theme,
-        "real projects" if args.reveal_projects else "projects anonymized",
-    ])
     return _lib_share.ShareSnapshot(
         cmd="budget",
         title="Budget — no budget set",
-        subtitle=subtitle,
+        # #503 S2 D5 — the facts strip states the period and the
+        # privacy mode; the theme is dropped deliberately.
+        subtitle=None,
         period=_lib_share.PeriodSpec(
             start=now_utc, end=now_utc, display_tz=tz_label, label=period_label,
         ),

package/bin/_cctally_journal.py

@@ -5668,6 +5668,27 @@ def _run_stats_ingest_once(
             if own_conn and conn is not None:
                 conn.close()
     finally:
+        # §9.2 (#496 S6 F23): the routine stats write. The `-wal`/`-shm`
+        # sidecars are materialized by the FIRST write, not by the connect, so
+        # hardening at open time alone would leave a 0644 WAL behind every
+        # ingest cycle — the exact shape of the cache.db defect #150 fixed.
+        # This runs while the ingest lock is still held, so the sidecars it
+        # inspects are the ones this cycle produced.
+        #
+        # Guarded because it is the FIRST statement of this block and the two
+        # lock releases are the last two: anything raised here — including the
+        # import — skips both, and the flocks are fd-scoped, so a long-lived
+        # dashboard process would hold them until it exited. Hardening is
+        # best-effort; releasing the locks is not.
+        try:
+            import _cctally_store
+            _cctally_store._harden_stats_family(_cctally_core.DB_PATH)
+        except Exception as exc:  # noqa: BLE001 — never above a lock release
+            print(
+                f"[ingest] could not harden the stats family ({exc}); "
+                "continuing",
+                file=sys.stderr,
+            )
         if lock_fd is not None:
             _release_ingest_lock(lock_fd)
         if maintenance_fd is not None:
@@ -7055,14 +7076,14 @@ def _record_post_checkpoint_damage(
 
 
 def _binary_version() -> "str | None":
-    """The running binary's released version, or None when it cannot be read."""
-    try:
-        import _lib_changelog
+    """The running binary's released version, or None when it cannot be read.
 
-        value = _lib_changelog._read_latest_changelog_version()
-    except Exception:  # pragma: no cover — a missing CHANGELOG is not fatal
-        return None
-    return value[0] if value else None
+    One implementation, in `_cctally_db`, shared with the incident manifests
+    the quarantine path writes (#496 S6 §4.2).
+    """
+    import _cctally_db
+
+    return _cctally_db._binary_version()
 
 
 def _preserve_stats_family_for_cutover(
@@ -7494,6 +7515,7 @@ def _publish_stats_index_in_place(
     no incident directory), or `_FALL_BACK` when physical replacement is the
     sanctioned response.
     """
+    import _cctally_store
     import _lib_stats_publish as sp
 
     try:
@@ -7607,6 +7629,11 @@ def _publish_stats_index_in_place(
         conn.close()
     except Exception:
         pass
+    # §9.2 (#496 S6 F23): the in-place publisher never touches the destination
+    # file's mode — it mutates objects inside it — so a family that was 0644
+    # before the publication is still 0644 after it. The checkpoint above is
+    # also the last thing that can re-materialize a sidecar.
+    _cctally_store._harden_stats_family(destination)
     _stats_rebuild_test_pause("rebuild_after_publication_replace")
 
     # Phase 2: validate the bytes that are now live, on a connection that never
@@ -7780,6 +7807,12 @@ def _publish_rebuilt_stats_index(
     )
 
     _stats_rebuild_test_pause("rebuild_before_cutover")
+    # §9.2 (#496 S6 F23): the scratch is closed and about to BECOME the
+    # destination, so hardening it here is what makes the replacement private
+    # from the instant it is visible under the live name. `os.replace` carries
+    # the source inode's mode across; a chmod after the rename would leave a
+    # window in which the live index was world-readable.
+    _cctally_store._harden_stats_family(scratch)
     os.replace(str(scratch), str(destination))
     _fsync_dir(destination.parent)
     _stats_rebuild_test_pause("rebuild_after_publication_replace")
@@ -7787,6 +7820,10 @@ def _publish_rebuilt_stats_index(
     # Phase 2: validate the bytes that are now live, on a connection that never
     # saw them being written.
     post_error = validate_published_stats_index(destination, high_water)
+    # The validation opened the family read-only, which materializes sidecars
+    # the removal below deletes; harden the destination itself while they are
+    # still present so neither the main nor a surviving sidecar stays 0644.
+    _cctally_store._harden_stats_family(destination)
     # The read-only open above creates a zero-byte WAL and a 32 KiB SHM.
     # Remove them so the documented no-post-publication-stale-sidecar end state
     # still holds; an empty WAL is consistent with the freshly published main,
@@ -8949,6 +8986,41 @@ def rebuild_stats_index(
     high_water: "tuple[str, int] | None" = None,
     update_quota_cache: bool = True,
     before_swap=None,
+) -> RebuildResult:
+    """Rebuild the stats index under a SHARED `artifact-retention.lock` hold.
+
+    #496 S6 §5.3. A rebuild publishes three artifacts that reclamation must not
+    mark while they are being written: the preserved-family incident manifest,
+    the second manifest write `_record_post_checkpoint_damage` performs after
+    the explicit checkpoint, and the rebuild record that names both. The hold
+    spans all three, so no observer ever sees the incident half-described.
+
+    The hold is taken here rather than only at the producer call sites because
+    `db rebuild` and the auto-heal worker are not the only callers — the epoch
+    rebuild and the deferred rebuild reach the same cutover. It is refcounted,
+    so a caller that already holds it pays nothing.
+
+    See `_rebuild_stats_index_locked` for the rebuild itself.
+    """
+    import _cctally_retention
+
+    with _cctally_retention.retention_shared(label="stats rebuild"):
+        return _rebuild_stats_index_locked(
+            context=context,
+            target_path=target_path,
+            high_water=high_water,
+            update_quota_cache=update_quota_cache,
+            before_swap=before_swap,
+        )
+
+
+def _rebuild_stats_index_locked(
+    *,
+    context: RebuildContext,
+    target_path=None,
+    high_water: "tuple[str, int] | None" = None,
+    update_quota_cache: bool = True,
+    before_swap=None,
 ) -> RebuildResult:
     """Build a FRESH stats index from the journal alone (spec §5.4).