cctally 1.92.2 → 1.93.0

package/bin/_lib_share_templates.py

@@ -36,7 +36,7 @@ from typing import Any
 
 # --- Panel set ---
 #
-# Share-capable panels are the 8 data-view panels in the dashboard.
+# Share-capable panels are the 9 data-view panels in the dashboard.
 # RecentAlertsPanel ('alerts') is intentionally excluded: it's a
 # notification stream, not a data view — shipping share templates over
 # alerts would conflate the two concepts (spec §6.1, §9.5).
@@ -65,8 +65,8 @@ class ShareTemplate:
     builder: Callable[..., Any]  # (panel_data, share_options) -> ShareSnapshot
 
 
-# Filled in subsequent tasks (M1.4 adds the 8 Recap templates;
-# M2.1 adds the 16 Visual + Detail templates).
+# Filled in below: 9 Recap templates, then 9 Visual + 9 Detail, for 27
+# templates across the 9 share-capable panels.
 SHARE_TEMPLATES: tuple[ShareTemplate, ...] = ()
 
 
@@ -198,8 +198,11 @@ def _top_projects_rows(top_projects, cap: int) -> tuple:
     """Build `Row` tuple with ProjectCell + MoneyCell from a list of
     `(project_path, cost_usd)` pairs.
 
-    Anonymization happens later in `_scrub()` — builders always emit real
-    names. Accepts both 2-tuples and `(path, cost, ...)` longer tuples;
+    Anonymization happens later, in the preparation pass `render()` and
+    `compose()` run over the raw snapshot — builders always emit real names.
+    (It is NOT `_scrub()`: that function is retained for backward
+    compatibility and no production path calls it.) Accepts both 2-tuples
+    and `(path, cost, ...)` longer tuples;
     only the first two positional elements are used so callers can pass
     enriched rows without copy-coercion.
     """
@@ -387,7 +390,7 @@ def _display_tz(options) -> str:
     return options.get("display_tz", "Etc/UTC")
 
 
-# --- 8 Recap builders ---
+# --- 9 Recap builders ---
 
 
 def _build_weekly_recap(*, panel_data, options):
@@ -834,7 +837,7 @@ def _build_sessions_recap(*, panel_data, options):
     )
 
 
-# --- 16 Visual + Detail builders ---
+# --- 18 Visual + Detail builders ---
 #
 # Archetype contract (spec §9.4):
 #   - Visual: chart populated (same density as Recap), `rows=()`, `columns=()`,
@@ -1525,10 +1528,19 @@ def _build_sessions_visual(*, panel_data, options):
         chart=_LS.HorizontalBarChart(
             points=tuple(
                 _LS.ChartPoint(
-                    x_label=str(s.get("session_id") or ""),
+                    # #503 S1 P7: the gutter label is RANK + PROJECT. It used
+                    # to be the raw session id, which is a canonical UUID in
+                    # production and was disclosed verbatim next to
+                    # `project-1` in the same anonymized artifact (F1). The
+                    # rank is what correlates a bar with its table row, and it
+                    # carries no identifier. Preparation composes the final
+                    # `x_label` from this prefix and the resolved project.
+                    x_label=str(i + 1),
                     x_value=float(i),
                     y_value=float(s.get("cost_usd") or 0.0),
                     project_label=str(s.get("project_path") or "") or None,
+                    x_label_kind="project",
+                    x_label_prefix=str(i + 1),
                 )
                 for i, s in enumerate(rows_iter)
             ),
@@ -1551,7 +1563,7 @@ def _build_sessions_detail(*, panel_data, options):
     Default `top_n` is 50 (Recap's is 15). Sessions Recap explicitly omits the
     chart (table-first panel); Detail re-introduces a compact horizontal bar
     of the same top-N so the archetype contract (chart populated + rows
-    populated) holds uniformly across all 8 panels' Detail siblings.
+    populated) holds uniformly across all 9 panels' Detail siblings.
     """
     sessions = panel_data.get("sessions") or []
     cap = options.get("top_n", 50)
@@ -1587,10 +1599,19 @@ def _build_sessions_detail(*, panel_data, options):
         chart=_LS.HorizontalBarChart(
             points=tuple(
                 _LS.ChartPoint(
-                    x_label=str(s.get("session_id") or ""),
+                    # #503 S1 P7: the gutter label is RANK + PROJECT. It used
+                    # to be the raw session id, which is a canonical UUID in
+                    # production and was disclosed verbatim next to
+                    # `project-1` in the same anonymized artifact (F1). The
+                    # rank is what correlates a bar with its table row, and it
+                    # carries no identifier. Preparation composes the final
+                    # `x_label` from this prefix and the resolved project.
+                    x_label=str(i + 1),
                     x_value=float(i),
                     y_value=float(s.get("cost_usd") or 0.0),
                     project_label=str(s.get("project_path") or "") or None,
+                    x_label_kind="project",
+                    x_label_prefix=str(i + 1),
                 )
                 for i, s in enumerate(rows_iter)
             ),
@@ -1667,6 +1688,7 @@ def _projects_chart_for_template(rows: list[dict], cap: int):
             x_value=cost,
             y_value=cost,
             project_label=label,
+            x_label_kind="project",
         ))
     return _LS.HorizontalBarChart(
         points=tuple(points), x_label="$", cap=cap,
@@ -1683,7 +1705,9 @@ def _projects_period(panel_data: dict, options: dict):
 
 
 def _projects_subtitle(options: dict, total_rows: int) -> str:
-    reveal = options.get("reveal_projects", True)
+    # FAIL CLOSED (#503 S1 F3): an omitted field made the Projects panel
+    # print the claim "real projects" about its own contents.
+    reveal = options.get("reveal_projects", False)
     return " · ".join([
         f"{total_rows} project{'' if total_rows == 1 else 's'}",
         "real projects" if reveal else "projects anonymized",

package/bin/_lib_stats_wal.py

@@ -0,0 +1,327 @@
+"""Bounded structural inspection of a SQLite WAL and its wal-index.
+
+The WAL carries database pages. This module reads only file/header identity,
+WAL frame headers, and wal-index page numbers; it never reads or returns frame
+payloads. Callers decide whether their surrounding locks make the snapshot
+authoritative enough for an operational decision.
+"""
+
+from __future__ import annotations
+
+import os
+import pathlib
+import struct
+import sys
+
+
+_WAL_MAGICS = {0x377F0682, 0x377F0683}
+_FIRST_PGNO_COUNT = 4062
+_LATER_PGNO_COUNT = 4096
+_SHM_REGION_BYTES = 32768
+_MISMATCH_SAMPLE_MAX = 8
+_FRAME_ANALYSIS_MAX = 16384
+
+_INCOHERENT_VERDICTS = {
+    "wal_index_generation_mismatch",
+    "wal_index_mapping_mismatch",
+}
+
+
+def _file_record(stat: os.stat_result) -> dict:
+    return {
+        "inode": int(stat.st_ino),
+        "sizeBytes": int(stat.st_size),
+        "mtimeNs": int(stat.st_mtime_ns),
+    }
+
+
+def _same_file(left: os.stat_result, right: os.stat_result) -> bool:
+    return (
+        left.st_dev,
+        left.st_ino,
+        left.st_size,
+        left.st_mtime_ns,
+    ) == (
+        right.st_dev,
+        right.st_ino,
+        right.st_size,
+        right.st_mtime_ns,
+    )
+
+
+def _read_at(handle, offset: int, size: int) -> bytes:
+    """Read one bounded structural range (test seam for byte accounting)."""
+    handle.seek(offset)
+    return handle.read(size)
+
+
+def _native_u16(raw: bytes, offset: int) -> int:
+    prefix = "<" if sys.byteorder == "little" else ">"
+    return int(struct.unpack_from(f"{prefix}H", raw, offset)[0])
+
+
+def _native_u32(raw: bytes, offset: int) -> int:
+    prefix = "<" if sys.byteorder == "little" else ">"
+    return int(struct.unpack_from(f"{prefix}I", raw, offset)[0])
+
+
+def _shm_page_offset(frame_number: int) -> int:
+    index = frame_number - 1
+    if index < _FIRST_PGNO_COUNT:
+        return 136 + index * 4
+    index -= _FIRST_PGNO_COUNT
+    region = 1 + index // _LATER_PGNO_COUNT
+    return region * _SHM_REGION_BYTES + (index % _LATER_PGNO_COUNT) * 4
+
+
+def _empty_evidence(verdict: str, reason: str | None = None) -> dict:
+    return {
+        "schemaVersion": 1,
+        "verdict": verdict,
+        "captureStable": False,
+        "reason": reason,
+        "wal": None,
+        "shm": None,
+        "frameMapping": {
+            "comparedCount": 0,
+            "mismatchCount": 0,
+            "mismatchSample": [],
+            "truncated": False,
+        },
+    }
+
+
+def _path_matches(path: pathlib.Path, opened: os.stat_result) -> bool:
+    try:
+        return _same_file(path.stat(), opened)
+    except OSError:
+        return False
+
+
+def _inspect_zero_wal(wal_path: pathlib.Path, shm_path: pathlib.Path) -> dict:
+    result = _empty_evidence("wal_empty")
+    try:
+        with wal_path.open("rb") as wal_handle:
+            wal_before = os.fstat(wal_handle.fileno())
+            result["wal"] = _file_record(wal_before)
+            if wal_before.st_size != 0:
+                result["verdict"] = "capture_raced"
+                result["reason"] = "WAL refilled before zero-WAL capture"
+                return result
+            try:
+                with shm_path.open("rb") as shm_handle:
+                    shm_before = os.fstat(shm_handle.fileno())
+                    result["shm"] = _file_record(shm_before)
+                    wal_after = os.fstat(wal_handle.fileno())
+                    shm_after = os.fstat(shm_handle.fileno())
+                    result["captureStable"] = (
+                        _same_file(wal_before, wal_after)
+                        and _same_file(shm_before, shm_after)
+                        and _path_matches(wal_path, wal_after)
+                        and _path_matches(shm_path, shm_after)
+                    )
+            except FileNotFoundError:
+                # Absence cannot be proven as one stable pair on the unlocked
+                # forensic path. The locked cutover still treats a zero WAL as
+                # safe, but the evidence does not overclaim capture stability.
+                result["captureStable"] = False
+            except OSError as exc:
+                result["reason"] = f"shm open failed: {exc}"[:200]
+    except OSError as exc:
+        return _empty_evidence("capture_raced", str(exc)[:200])
+    if not result["captureStable"] and result["shm"] is not None:
+        result["verdict"] = "capture_raced"
+        result["reason"] = "WAL or SHM identity changed during capture"
+    return result
+
+
+def inspect_wal_index_family(db_path) -> dict:
+    """Return bounded WAL/SHM coherence evidence without opening SQLite."""
+    db_path = pathlib.Path(db_path)
+    wal_path = pathlib.Path(f"{db_path}-wal")
+    shm_path = pathlib.Path(f"{db_path}-shm")
+    try:
+        wal_stat = wal_path.stat()
+    except FileNotFoundError:
+        return _empty_evidence("wal_absent")
+    except OSError as exc:
+        return _empty_evidence("unavailable", f"wal stat failed: {exc}"[:200])
+    if wal_stat.st_size == 0:
+        return _inspect_zero_wal(wal_path, shm_path)
+    try:
+        shm_path.stat()
+    except FileNotFoundError:
+        result = _empty_evidence("shm_absent")
+        result["wal"] = _file_record(wal_stat)
+        return result
+    except OSError as exc:
+        return _empty_evidence("unavailable", f"shm stat failed: {exc}"[:200])
+
+    result = _empty_evidence("unavailable")
+    try:
+        with wal_path.open("rb") as wal_handle, shm_path.open("rb") as shm_handle:
+            wal_before = os.fstat(wal_handle.fileno())
+            shm_before = os.fstat(shm_handle.fileno())
+            result["wal"] = _file_record(wal_before)
+            result["shm"] = _file_record(shm_before)
+            wal_header = _read_at(wal_handle, 0, 32)
+            shm_header = _read_at(shm_handle, 0, 136)
+            if len(wal_header) < 32 or len(shm_header) < 136:
+                result["reason"] = "WAL or SHM header is truncated"
+            else:
+                _populate_evidence(
+                    result, wal_handle, shm_handle, wal_header, shm_header,
+                    wal_before, shm_before,
+                )
+            wal_header_after = _read_at(wal_handle, 0, 32)
+            shm_header_after = _read_at(shm_handle, 0, 136)
+            wal_after = os.fstat(wal_handle.fileno())
+            shm_after = os.fstat(shm_handle.fileno())
+            stable = (
+                _same_file(wal_before, wal_after)
+                and _same_file(shm_before, shm_after)
+                and _path_matches(wal_path, wal_after)
+                and _path_matches(shm_path, shm_after)
+                and wal_header == wal_header_after
+                and shm_header == shm_header_after
+            )
+    except OSError as exc:
+        return _empty_evidence("capture_raced", str(exc)[:200])
+
+    result["captureStable"] = stable
+    if not stable:
+        result["verdict"] = "capture_raced"
+        result["reason"] = "WAL or SHM identity changed during capture"
+    return result
+
+
+def _populate_evidence(
+    result: dict,
+    wal_handle,
+    shm_handle,
+    wal_header: bytes,
+    shm_header: bytes,
+    wal_stat: os.stat_result,
+    shm_stat: os.stat_result,
+) -> None:
+    magic = struct.unpack_from(">I", wal_header, 0)[0]
+    page_size_raw = struct.unpack_from(">I", wal_header, 8)[0]
+    page_size = 65536 if page_size_raw == 1 else int(page_size_raw)
+    if magic not in _WAL_MAGICS or page_size < 512 or page_size > 65536:
+        result["reason"] = "WAL header magic or page size is invalid"
+        return
+
+    frame_bytes = 24 + page_size
+    physical_frames = max(0, (wal_stat.st_size - 32) // frame_bytes)
+    trailing_bytes = max(0, (wal_stat.st_size - 32) % frame_bytes)
+    wal_salt_bytes = wal_header[16:24]
+    wal_salt = wal_salt_bytes.hex()
+    shm_salt = shm_header[32:40].hex()
+    shm_page_size_raw = _native_u16(shm_header, 14)
+    shm_page_size = 65536 if shm_page_size_raw == 1 else shm_page_size_raw
+    mx_frame = _native_u32(shm_header, 16)
+    scan_limit = min(physical_frames, _FRAME_ANALYSIS_MAX)
+    current_generation_frames = 0
+    current_generation_commit_frames = 0
+    first_stale_tail_frame = None
+    frame_headers: dict[int, bytes] = {}
+    for frame_number in range(1, scan_limit + 1):
+        offset = 32 + (frame_number - 1) * frame_bytes
+        frame_header = _read_at(wal_handle, offset, 24)
+        if len(frame_header) < 24:
+            result["reason"] = "WAL frame header is truncated"
+            return
+        frame_headers[frame_number] = frame_header
+        if frame_header[8:16] != wal_salt_bytes:
+            first_stale_tail_frame = frame_number
+            break
+        current_generation_frames = frame_number
+        if struct.unpack_from(">I", frame_header, 4)[0] != 0:
+            current_generation_commit_frames = frame_number
+
+    analysis_truncated = (
+        first_stale_tail_frame is None
+        and physical_frames > _FRAME_ANALYSIS_MAX
+    ) or mx_frame > _FRAME_ANALYSIS_MAX
+    compared_limit = min(
+        mx_frame, current_generation_commit_frames, _FRAME_ANALYSIS_MAX
+    )
+    mismatch_count = 0
+    mismatch_sample = []
+    compared_count = 0
+    mapping_incomplete = False
+    for frame_number in range(1, compared_limit + 1):
+        frame_header = frame_headers.get(frame_number)
+        if frame_header is None:
+            offset = 32 + (frame_number - 1) * frame_bytes
+            frame_header = _read_at(wal_handle, offset, 24)
+        shm_offset = _shm_page_offset(frame_number)
+        if shm_offset + 4 > shm_stat.st_size:
+            mapping_incomplete = True
+            break
+        shm_page_raw = _read_at(shm_handle, shm_offset, 4)
+        if len(shm_page_raw) < 4:
+            mapping_incomplete = True
+            break
+        wal_page = int(struct.unpack_from(">I", frame_header, 0)[0])
+        shm_page = _native_u32(shm_page_raw, 0)
+        compared_count += 1
+        if wal_page != shm_page:
+            mismatch_count += 1
+            if len(mismatch_sample) < _MISMATCH_SAMPLE_MAX:
+                mismatch_sample.append({
+                    "frame": frame_number,
+                    "walPage": wal_page,
+                    "shmPage": shm_page,
+                })
+
+    header_copies_match = shm_header[:48] == shm_header[48:96]
+    result["wal"].update({
+        "magicHex": f"{magic:08x}",
+        "saltHex": wal_salt,
+        "pageSize": page_size,
+        "physicalFrameCount": physical_frames,
+        "trailingBytes": trailing_bytes,
+        "currentGenerationFrameCount": current_generation_frames,
+        "currentGenerationCommitFrameCount": current_generation_commit_frames,
+        "stalePhysicalTailFrameCount": max(
+            0, physical_frames - current_generation_frames
+        ),
+    })
+    result["shm"].update({
+        "headerCopiesMatch": header_copies_match,
+        "saltHex": shm_salt,
+        "pageSize": shm_page_size,
+        "mxFrame": mx_frame,
+        "nPage": _native_u32(shm_header, 20),
+        "nBackfill": _native_u32(shm_header, 96),
+        "nBackfillAttempted": _native_u32(shm_header, 128),
+    })
+    result["frameMapping"] = {
+        "comparedCount": compared_count,
+        "mismatchCount": mismatch_count,
+        "mismatchSample": mismatch_sample,
+        "truncated": analysis_truncated or mapping_incomplete,
+    }
+
+    if analysis_truncated:
+        verdict = "analysis_truncated"
+    elif wal_salt != shm_salt:
+        verdict = "wal_index_generation_mismatch"
+    elif (
+        not header_copies_match
+        or mismatch_count
+        or mapping_incomplete
+        or mx_frame != current_generation_commit_frames
+        or shm_page_size != page_size
+        or trailing_bytes != 0
+    ):
+        verdict = "wal_index_mapping_mismatch"
+    else:
+        verdict = "coherent"
+    result["verdict"] = verdict
+    result["reason"] = None
+
+
+def is_incoherent_wal_index(evidence: dict) -> bool:
+    return evidence.get("verdict") in _INCOHERENT_VERDICTS

package/bin/_lib_view_models.py

@@ -262,7 +262,8 @@ class TuiSessionRow:
     # Absolute project_path (NULL ⇒ ``(unknown)`` resolved upstream).
     # Carried so the sync-thread builder can compute ``project_key``
     # without re-reading ``session_files`` and so the share path can
-    # privacy-scrub via ``_lib_share._scrub``.
+    # anonymize it in the preparation pass ``_lib_share.render()`` /
+    # ``compose()`` run over the raw snapshot.
     project_path: str | None = None
     # Dashboard/TUI-only: the human-readable session title (AI-generated
     # title when present, else the first non-marker user prompt). Populated