cctally 1.38.0 → 1.38.1

package/CHANGELOG.md

@@ -5,6 +5,11 @@ based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/).
 
 ## [Unreleased]
 
+## [1.38.1] - 2026-06-12
+
+### Fixed
+- Dashboard: stop the steady-state one-core CPU peg on large caches. The background sync thread rebuilds the full snapshot every few seconds, and several panels read wide historical ranges that re-parsed the per-row `usage_extra_json` JSON blob on every tick — on a ~260K-entry cache a single rebuild cost roughly a core-second, so rebuilds ran back-to-back and one core stayed pinned. The only non-token field any reader consumes (`speed`, for the `<model>-fast` label) is now materialized into a real `session_entries.speed` column, so the hot cache read paths reconstruct usage with zero JSON parsing; a one-time cache migration backfills the column from the existing blobs, and new ingests write the column directly (the now-unused blob is written `NULL` and reclaimed on the next `cache-sync --rebuild`). Output is byte-identical everywhere `speed` matters; on a 250K-row synthetic cache the wide read dropped from ~1.6s to ~0.35s per call (#181).
+
 ## [1.38.0] - 2026-06-12
 
 ### Added

package/bin/_cctally_cache.py

@@ -928,14 +928,12 @@ def sync_cache(
                             out = int(usage.get("output_tokens", 0) or 0)
                             cc = int(usage.get("cache_creation_input_tokens", 0) or 0)
                             cr = int(usage.get("cache_read_input_tokens", 0) or 0)
-                            extras = {
-                                k: v for k, v in usage.items()
-                                if k not in (
-                                    "input_tokens", "output_tokens",
-                                    "cache_creation_input_tokens",
-                                    "cache_read_input_tokens",
-                                )
-                            }
+                            # #181: `speed` is the ONLY non-token usage key any
+                            # consumer reads, so materialize just that scalar and
+                            # write NULL into usage_extra_json — no more
+                            # serializing the deeply-nested blob the read paths
+                            # used to json.loads per row.
+                            speed = usage.get("speed")
                             rows.append((
                                 path_str,
                                 offset,
@@ -944,7 +942,8 @@ def sync_cache(
                                 msg_id,
                                 req_id,
                                 inp, out, cc, cr,
-                                json.dumps(extras, sort_keys=True) if extras else None,
+                                None,    # usage_extra_json — bloat no longer written (#181)
+                                speed,   # materialized speed column
                                 entry.cost_usd,
                             ))
                         if mrow is not None:
@@ -1005,8 +1004,8 @@ def sync_cache(
                            (source_path, line_offset, timestamp_utc, model,
                             msg_id, req_id, input_tokens, output_tokens,
                             cache_create_tokens, cache_read_tokens,
-                            usage_extra_json, cost_usd_raw)
-                           VALUES (?,?,?,?,?,?,?,?,?,?,?,?)
+                            usage_extra_json, speed, cost_usd_raw)
+                           VALUES (?,?,?,?,?,?,?,?,?,?,?,?,?)
                            ON CONFLICT(msg_id, req_id)
                            WHERE msg_id IS NOT NULL AND req_id IS NOT NULL
                            DO UPDATE SET
@@ -1017,6 +1016,7 @@ def sync_cache(
                                cache_create_tokens = excluded.cache_create_tokens,
                                cache_read_tokens = excluded.cache_read_tokens,
                                usage_extra_json = excluded.usage_extra_json,
+                               speed = excluded.speed,
                                cost_usd_raw = excluded.cost_usd_raw
                            WHERE
                                (excluded.input_tokens + excluded.output_tokens
@@ -1030,8 +1030,8 @@ def sync_cache(
                                =
                                (session_entries.input_tokens + session_entries.output_tokens
                                 + session_entries.cache_create_tokens + session_entries.cache_read_tokens)
-                               AND json_extract(excluded.usage_extra_json, '$.speed') IS NOT NULL
-                               AND json_extract(session_entries.usage_extra_json, '$.speed') IS NULL
+                               AND excluded.speed IS NOT NULL
+                               AND session_entries.speed IS NULL
                             )""",
                         rows,
                     )
@@ -1266,7 +1266,7 @@ def iter_entries(
 
     sql = (
         "SELECT timestamp_utc, model, input_tokens, output_tokens, "
-        "cache_create_tokens, cache_read_tokens, usage_extra_json, "
+        "cache_create_tokens, cache_read_tokens, speed, "
         "cost_usd_raw, source_path "
         "FROM session_entries "
         "WHERE timestamp_utc >= ? AND timestamp_utc <= ?"
@@ -1292,12 +1292,12 @@ def iter_entries(
             "cache_creation_input_tokens": row[4],
             "cache_read_input_tokens":     row[5],
         }
-        if row[6]:
-            # Safe because sync_cache strips the four token keys from
-            # extras before storing them in usage_extra_json. If that
-            # write-side invariant ever changes, extras could shadow
-            # the int-normalized token columns.
-            usage.update(json.loads(row[6]))
+        # speed is the only non-token usage key any consumer reads (#181);
+        # materialized into its own column so this hot path never parses JSON.
+        # `is not None` (not truthiness) so an empty-string speed still surfaces,
+        # mirroring the SQL `json_extract(...) IS NOT NULL` parity.
+        if row[6] is not None:
+            usage["speed"] = row[6]
         entries.append(UsageEntry(
             timestamp=dt.datetime.fromisoformat(row[0]),
             model=row[1],
@@ -1430,7 +1430,7 @@ def get_claude_session_entries(
         "  se.cache_create_tokens, se.cache_read_tokens, "
         "  se.source_path, "
         "  sf.session_id, sf.project_path, "
-        "  se.cost_usd_raw, se.usage_extra_json "
+        "  se.cost_usd_raw, se.speed "
         "FROM session_entries se "
         "LEFT JOIN session_files sf ON sf.path = se.source_path "
         "WHERE se.timestamp_utc >= ? AND se.timestamp_utc <= ?"
@@ -1458,7 +1458,10 @@ def get_claude_session_entries(
             session_id=row[7],
             project_path=row[8],
             cost_usd=row[9],
-            usage_extra=(json.loads(row[10]) if row[10] else None),
+            # speed materialized into its own column (#181); reconstruct the
+            # {"speed": …} shape _usage_entry_from_joined already merges, with
+            # zero JSON parsing. `is not None` so an empty-string speed surfaces.
+            usage_extra=({"speed": row[10]} if row[10] is not None else None),
         )
         for row in rows
     ]

package/bin/_cctally_db.py

@@ -2304,7 +2304,8 @@ def _apply_cache_schema(conn: sqlite3.Connection) -> None:
             cache_create_tokens INTEGER NOT NULL DEFAULT 0,
             cache_read_tokens   INTEGER NOT NULL DEFAULT 0,
             usage_extra_json    TEXT,
-            cost_usd_raw        REAL
+            cost_usd_raw        REAL,
+            speed               TEXT
         );
         CREATE INDEX IF NOT EXISTS idx_entries_timestamp
             ON session_entries(timestamp_utc);
@@ -2384,6 +2385,14 @@ def _apply_cache_schema(conn: sqlite3.Connection) -> None:
     # populated lazily in sync_cache() / _ensure_session_files_row().
     add_column_if_missing(conn, "session_files", "session_id", "TEXT")
     add_column_if_missing(conn, "session_files", "project_path", "TEXT")
+    # #181: materialize the only-ever-consumed extra `usage` key (`speed`) into
+    # a real session_entries column so the hot cache read paths (iter_entries /
+    # get_claude_session_entries) stop json.loads-ing the deeply-nested
+    # usage_extra_json blob per row — that per-tick parse was pegging a core in
+    # the dashboard. Idempotent column-add (no marker, no version), appended
+    # after cost_usd_raw to match the CREATE TABLE order; cache migration 008
+    # then backfills it from the legacy blob on existing rows.
+    add_column_if_missing(conn, "session_entries", "speed", "TEXT")
     # Existing-DB guard for the skill-content fold link (cctally-dev
     # skill-content-nesting): the message-level sourceToolUseID. Idempotent
     # column-add (no marker, no version); cache migration 006 then re-ingests
@@ -3171,6 +3180,33 @@ def _007_conversation_reingest_enrichment(conn: sqlite3.Connection) -> None:
     conn.commit()
 
 
+@cache_migration("008_session_entries_speed_backfill")
+def _008_session_entries_speed_backfill(conn: sqlite3.Connection) -> None:
+    """Backfill the materialized ``session_entries.speed`` column from the
+    legacy ``usage_extra_json`` blob (#181). ``speed`` is the ONLY non-token
+    ``usage`` key any consumer reads (``<model>-fast`` rendering in
+    _lib_aggregators + the _should_replace dedup tiebreak); materializing it
+    lets the hot read paths (iter_entries / get_claude_session_entries) stop
+    ``json.loads``-ing the deeply-nested blob per row — the per-tick dashboard
+    rebuild was pegging a core on a ~261K-row cache.
+
+    The column is added by _apply_cache_schema's add_column_if_missing (which
+    runs before this dispatcher), so it always exists here. This handler only
+    backfills existing rows; new ingests write the column directly and write
+    NULL to usage_extra_json. ``WHERE speed IS NULL`` self-guards re-runs.
+    We do NOT rewrite/NULL usage_extra_json on existing rows or VACUUM — the
+    stale blob has no reader and is reclaimed on the next cache-sync --rebuild.
+    json_extract returns NULL when '$.speed' is absent, so speed-less rows stay
+    NULL. Central stamp via the dispatcher (#140); a fresh install stamps it
+    without effect (empty table)."""
+    conn.execute(
+        "UPDATE session_entries "
+        "SET speed = json_extract(usage_extra_json, '$.speed') "
+        "WHERE speed IS NULL AND usage_extra_json IS NOT NULL"
+    )
+    conn.commit()
+
+
 # === Region 7d: Stats migration 008_recompute_weekly_cost_snapshots_dedup_fix ===
 
 @stats_migration("008_recompute_weekly_cost_snapshots_dedup_fix")
@@ -3323,6 +3359,10 @@ def _008_recompute_weekly_cost_snapshots_dedup_fix(
                         "cache_creation_input_tokens": cc,
                         "cache_read_input_tokens": cr,
                     }
+                    # #181: usage_extra_json is cost-irrelevant (cost is
+                    # token-only); parsed here only for pre-008 rows that may
+                    # still carry the legacy blob — NOT a speed reader, so the
+                    # write-side NULL going forward is safe.
                     if extras_json:
                         usage.update(json.loads(extras_json))
                     total += _calculate_entry_cost(
@@ -3637,6 +3677,10 @@ def _009_recompute_five_hour_blocks_dedup_fix(
                         "cache_creation_input_tokens": cc_t,
                         "cache_read_input_tokens": cr_t,
                     }
+                    # #181: usage_extra_json is cost-irrelevant (cost is
+                    # token-only); parsed here only for pre-008 rows that may
+                    # still carry the legacy blob — NOT a speed reader, so the
+                    # write-side NULL going forward is safe.
                     if extras_json:
                         usage.update(json.loads(extras_json))
                     cost = _calculate_entry_cost(
@@ -3909,6 +3953,10 @@ def _010_recompute_percent_milestones_dedup_fix(
                         "cache_creation_input_tokens": cc,
                         "cache_read_input_tokens": cr,
                     }
+                    # #181: usage_extra_json is cost-irrelevant (cost is
+                    # token-only); parsed here only for pre-008 rows that may
+                    # still carry the legacy blob — NOT a speed reader, so the
+                    # write-side NULL going forward is safe.
                     if extras_json:
                         usage.update(json.loads(extras_json))
                     cumulative += _calculate_entry_cost(

package/bin/_cctally_statusline.py

@@ -345,7 +345,7 @@ def _build_statusline_injections(warn_once):
                 "SELECT se.timestamp_utc, se.model, "
                 "  se.input_tokens, se.output_tokens, "
                 "  se.cache_create_tokens, se.cache_read_tokens, "
-                "  se.cost_usd_raw, se.usage_extra_json "
+                "  se.cost_usd_raw "
                 "FROM session_entries se "
                 "LEFT JOIN session_files sf ON sf.path = se.source_path "
                 "WHERE sf.session_id = ?"
@@ -368,13 +368,10 @@ def _build_statusline_injections(warn_once):
                 "cache_creation_input_tokens": r[4] or 0,
                 "cache_read_input_tokens":     r[5] or 0,
             }
-            try:
-                if r[7]:
-                    extras = json.loads(r[7])
-                    if isinstance(extras, dict):
-                        usage.update(extras)
-            except Exception:
-                pass
+            # #181: cost is token-only (_calculate_entry_cost ignores `speed`),
+            # so the statusline cost path no longer selects or json.loads the
+            # usage_extra_json blob — output is byte-identical. r[6] is still
+            # cost_usd_raw (the dropped column was the trailing slot).
             try:
                 total += c._calculate_entry_cost(
                     r[1], usage, mode="auto", cost_usd=r[6],

package/bin/_lib_jsonl.py

@@ -85,8 +85,10 @@ def _should_replace(
     finalization row carries `speed`; streaming intermediates don't).
 
     The `usage.get("speed") is not None` check matches the SQL UPDATE WHERE
-    clause's `json_extract(..., '$.speed') IS NOT NULL` in `sync_cache`'s
-    INSERT … ON CONFLICT … DO UPDATE, keeping the direct-parse fallback and
+    clause's `excluded.speed IS NOT NULL` in `sync_cache`'s INSERT … ON
+    CONFLICT … DO UPDATE — `speed` is materialized into its own
+    `session_entries.speed` column (#181), so the tiebreak no longer
+    `json_extract`s the blob — keeping the direct-parse fallback and
     cache-ingest paths in lockstep on the rare-but-possible "explicit JSON
     null" payload.
     """

package/bin/cctally

@@ -1614,13 +1614,14 @@ def _usage_entry_from_joined(je) -> "UsageEntry":
     and the per-token integers; this adapter is pure shape conversion
     with no cache re-read.
 
-    Non-token ``usage`` extras (``je.usage_extra``) — notably ``speed`` —
+    Non-token ``usage`` extras (``je.usage_extra``) — now just ``speed`` —
     are merged AFTER the four token keys, mirroring ``iter_entries``'
-    ``usage.update(json.loads(...))``. Without this, the project-axis
+    reconstruction of ``usage["speed"]`` from the materialized
+    ``session_entries.speed`` column (#181). Without this, the project-axis
     ``daily`` path (and the diff/report joined-entry consumers) would
     drop the fast-tier flag and render ``<model>`` where the normal path
-    renders ``<model>-fast``. The write-side strips the four token keys
-    from ``usage_extra_json`` so the merge never shadows the integers.
+    renders ``<model>-fast``. ``je.usage_extra`` is ``{"speed": …}`` or
+    ``None``, so the merge never shadows the token integers.
     """
     usage = {
         "input_tokens": je.input_tokens,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "cctally",
-  "version": "1.38.0",
+  "version": "1.38.1",
   "description": "Claude Code usage tracker and local dashboard for Pro/Max subscription limits - weekly cost-per-percent trend, quota forecasts, threshold alerts. ccusage-compatible.",
   "homepage": "https://github.com/omrikais/cctally",
   "repository": {