tokenol 0.2.0__tar.gz → 0.3.0__tar.gz

{tokenol-0.2.0 → tokenol-0.3.0}/CHANGELOG.md

@@ -4,6 +4,35 @@ All notable changes to tokenol are documented here. The format follows
 [Keep a Changelog](https://keepachangelog.com/en/1.1.0/), and versions follow
 [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [0.3.0] — 2026-04-27
+
+### Changed
+- **`tokenol serve` resource use slashed.** On a real session-history workload,
+  steady-state RSS drops ~8× (from ~4 GiB to ~500 MiB) and idle CPU falls to
+  near zero between heartbeats. Multi-tab dashboards now share a single
+  background producer, so adding tabs does not multiply server CPU.
+- The SSE stream (`/api/stream`) is driven by `SnapshotBroadcaster`: one task
+  per `period` fans payloads out to N subscribers, each maintaining its own
+  shallow-diff state. The wire format is unchanged.
+- The producer now gates rebuilds on JSONL file `(path, size, mtime_ns)`
+  changes, with a configurable heartbeat (default 60 s) so time-windowed
+  panels (`recent_activity`, day boundaries) stay reasonably fresh. Trade-off:
+  panels may lag wall-clock by up to the heartbeat between file writes.
+- `ParseCache` now memoizes derived `(turns, sessions, fired)` keyed on the
+  active file-key set; idle ticks skip the per-tick `_build_turns_and_sessions`
+  rebuild entirely.
+- `_build_turns_and_sessions` now returns the per-build assumption-fired
+  `Counter` instead of mutating the global `assumption_recorder`.
+- `create_app` migrated from the deprecated `@app.on_event("shutdown")` to a
+  lifespan context manager.
+
+### Removed
+- **`RawEvent.raw` field.** Was populated by the parser with the full JSON
+  dict (message bodies, tool I/O) for "extensibility" but read by no
+  downstream code. Removing it is the dominant memory win. Code that wants
+  raw JSON should re-read from disk (as `serve/session_detail.py` already
+  does).
+
 ## [0.2.0] — 2026-04-25
 
 ### Added

{tokenol-0.2.0 → tokenol-0.3.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: tokenol
-Version: 0.2.0
+Version: 0.3.0
 Summary: Audit Claude Code JSONL session logs: track cost, cache health, context blow-ups, and 5h-window pressure.
 Project-URL: Homepage, https://github.com/farhanferoz/tokenol
 Project-URL: Issues, https://github.com/farhanferoz/tokenol/issues

{tokenol-0.2.0 → tokenol-0.3.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "tokenol"
-version = "0.2.0"
+version = "0.3.0"
 description = "Audit Claude Code JSONL session logs: track cost, cache health, context blow-ups, and 5h-window pressure."
 readme = "README.md"
 license = { text = "MIT" }

{tokenol-0.2.0 → tokenol-0.3.0}/src/tokenol/__init__.py

@@ -1,3 +1,3 @@
 """tokenol — Claude Code usage & efficiency audit tool."""
 
-__version__ = "0.2.0"
+__version__ = "0.3.0"

{tokenol-0.2.0 → tokenol-0.3.0}/src/tokenol/ingest/parser.py

@@ -118,7 +118,6 @@ def parse_file(path: Path) -> Iterator[RawEvent]:
                 tool_error_count=tool_error_count,
                 tool_names=tool_names,
                 cwd=cwd,
-                raw=ev,
             )
 
 

{tokenol-0.2.0 → tokenol-0.3.0}/src/tokenol/model/events.py

@@ -55,9 +55,6 @@ class RawEvent:
     # Working directory (from system events)
     cwd: str | None = None
 
-    # Raw for extensibility (caller may inspect)
-    raw: dict = field(default_factory=dict)  # type: ignore[assignment]
-
 
 @dataclass
 class Turn:

{tokenol-0.2.0 → tokenol-0.3.0}/src/tokenol/serve/app.py

@@ -4,6 +4,7 @@ from __future__ import annotations
 
 import asyncio
 from collections import Counter
+from contextlib import asynccontextmanager
 from dataclasses import dataclass
 from datetime import date, datetime, timezone
 from pathlib import Path
@@ -37,6 +38,7 @@ from tokenol.serve.state import (
     encode_cwd,
     range_since,
 )
+from tokenol.serve.streaming import SnapshotBroadcaster
 
 _WINDOW_MINUTES: dict[str, int] = {"15m": 15, "60m": 60, "4h": 240, "24h": 1440}
 _KNOWN_PREFS_KEYS: frozenset[str] = frozenset({"tick_seconds", "reference_usd", "thresholds"})
@@ -121,12 +123,29 @@ def create_app(
     _prefs_path = prefs_path or default_path()
     prefs = Preferences.load(_prefs_path)
 
-    app = FastAPI(title="tokenol")
+    parse_cache = ParseCache()
+    broadcaster = SnapshotBroadcaster(
+        parse_cache=parse_cache,
+        all_projects=config.all_projects,
+        get_reference_usd=lambda: prefs.reference_usd,
+        get_tick_seconds=lambda: prefs.tick_seconds,
+        get_thresholds=lambda: prefs.thresholds,
+    )
+
+    @asynccontextmanager
+    async def lifespan(_app: FastAPI):
+        try:
+            yield
+        finally:
+            await broadcaster.shutdown()
+
+    app = FastAPI(title="tokenol", lifespan=lifespan)
     app.state.config = config
     app.state.prefs = prefs
     app.state.prefs_path = _prefs_path
-    app.state.parse_cache = ParseCache()
+    app.state.parse_cache = parse_cache
     app.state.snapshot_result = None
+    app.state.broadcaster = broadcaster
 
     if STATIC_DIR.exists():
         app.mount("/assets", StaticFiles(directory=str(STATIC_DIR)), name="assets")
@@ -220,21 +239,10 @@ def create_app(
 
     @app.get("/api/stream")
     async def api_stream(request: Request, period: str = "today"):
-        from tokenol.serve.streaming import snapshot_stream
-
-        cfg: ServerConfig = request.app.state.config
-        prefs: Preferences = request.app.state.prefs
-        cache: ParseCache = request.app.state.parse_cache
+        broadcaster: SnapshotBroadcaster = request.app.state.broadcaster
 
         async def event_generator():
-            async for chunk in snapshot_stream(
-                parse_cache=cache,
-                all_projects=cfg.all_projects,
-                reference_usd=prefs.reference_usd,
-                get_tick_seconds=lambda: prefs.tick_seconds,
-                period=period,
-                thresholds=prefs.thresholds,
-            ):
+            async for chunk in broadcaster.subscribe(period):
                 if await request.is_disconnected():
                     break
                 yield chunk
@@ -275,6 +283,13 @@ def create_app(
         if range not in ("7d", "30d", "90d", "all"):
             raise HTTPException(status_code=400, detail="range must be 7d, 30d, 90d, or all")
         result = request.app.state.snapshot_result or _build_and_cache_snapshot(request)
+        # Fall back silently to the longest available window when the requested range
+        # exceeds the data we have — return 200 with a `note` so the UI can caption it.
+        # Returning 400 here forced clients to special-case "policy" failures even though
+        # the request itself is well-formed.
+        effective_range = range
+        note: str | None = None
+        have_days: int | None = None
         if range != "all" and result.turns:
             today = date.today()
             since = range_since(range, today)
@@ -282,11 +297,17 @@ def create_app(
                 earliest = min(t.timestamp.date() for t in result.turns)
                 if earliest > since:
                     have_days = (today - earliest).days + 1
-                    return JSONResponse(
-                        status_code=400,
-                        content={"error": "insufficient_history", "have_days": have_days},
+                    effective_range = "all"
+                    note = (
+                        f"Only {have_days} days of history available — "
+                        f"showing all data instead of {range}."
                     )
-        return JSONResponse(build_daily_panel(result.turns, result.sessions, range, metric, project, model))
+        panel = build_daily_panel(result.turns, result.sessions, effective_range, metric, project, model)
+        if note is not None:
+            panel["requested_range"] = range
+            panel["have_days"] = have_days
+            panel["note"] = note
+        return JSONResponse(panel)
 
     @app.get("/api/models")
     async def api_models(request: Request, range: str = "today"):

{tokenol-0.2.0 → tokenol-0.3.0}/src/tokenol/serve/state.py

@@ -19,7 +19,6 @@ from dataclasses import dataclass, field
 from datetime import date, datetime, timedelta, timezone
 from pathlib import Path
 
-from tokenol import assumptions as assumption_recorder
 from tokenol.enums import AssumptionTag, BlowUpVerdict
 from tokenol.ingest.discovery import find_jsonl_files, get_config_dirs
 from tokenol.ingest.parser import dedup_key, parse_file
@@ -51,10 +50,17 @@ class ParseCache:
     """JSONL parse cache keyed by (path_str, size, mtime_ns).
 
     All public methods are thread-safe via an internal lock.
+
+    Also memoizes the derived (turns, sessions) tuple keyed on the active set of
+    parse keys: when no JSONL file changed since the last build, build_snapshot_full
+    can skip the O(total events) re-derivation. The memo is invalidated automatically
+    on any get_or_parse miss or any purge that drops a key.
     """
 
     _store: dict[tuple[str, int, int], list[RawEvent]] = field(default_factory=dict)
     _lock: threading.Lock = field(default_factory=threading.Lock)
+    _derived_keys: frozenset[tuple[str, int, int]] | None = None
+    _derived: tuple[list[Turn], list[Session], Counter[AssumptionTag]] | None = None
 
     def get_or_parse(self, path: Path) -> tuple[tuple[str, int, int], list[RawEvent]]:
         """Return (cache_key, events). Parses only when (size, mtime_ns) changes."""
@@ -63,6 +69,9 @@ class ParseCache:
         with self._lock:
             if key not in self._store:
                 self._store[key] = list(parse_file(path))
+                # New file content invalidates any derived memo.
+                self._derived_keys = None
+                self._derived = None
             return key, self._store[key]
 
     def purge(self, keep_keys: set[tuple[str, int, int]]) -> None:
@@ -71,6 +80,36 @@ class ParseCache:
             stale = [k for k in self._store if k not in keep_keys]
             for k in stale:
                 del self._store[k]
+            if stale:
+                self._derived_keys = None
+                self._derived = None
+
+    def get_derived(
+        self,
+        keys: frozenset[tuple[str, int, int]],
+        builder: Callable[[list[RawEvent]], tuple[list[Turn], list[Session], Counter[AssumptionTag]]],
+    ) -> tuple[list[Turn], list[Session], Counter[AssumptionTag]]:
+        """Return memoized (turns, sessions, fired_counts) for the given key set; rebuild on miss.
+
+        The memo is keyed on `keys` (the set of active ParseCache entries). When no
+        file changed mtime/size since the last build, the cached derivation is
+        returned without re-iterating events — this is the dominant per-tick cost.
+        """
+        with self._lock:
+            if self._derived is not None and self._derived_keys == keys:
+                return self._derived
+            # Build outside the parse-cache invariant by snapshotting events first.
+            events: list[RawEvent] = []
+            for k in keys:
+                bucket = self._store.get(k)
+                if bucket is not None:
+                    events.extend(bucket)
+        # Builder runs without the lock — it's pure CPU over a private list.
+        derived = builder(events)
+        with self._lock:
+            self._derived = derived
+            self._derived_keys = keys
+        return derived
 
     @property
     def size(self) -> int:
@@ -80,12 +119,18 @@ class ParseCache:
 
 def _build_turns_and_sessions(
     all_events: list[RawEvent],
-) -> tuple[list[Turn], list[Session]]:
-    """Build deduplicated turns and sessions from pre-parsed raw events."""
+) -> tuple[list[Turn], list[Session], Counter[AssumptionTag]]:
+    """Build deduplicated turns and sessions from pre-parsed raw events.
+
+    Returns the (turns, sessions, fired-assumption-counts). Fired counts are returned
+    rather than written to a global recorder so the result is referentially
+    transparent and safe to memoize on ParseCache.
+    """
     seen: dict[str, tuple[RawEvent, str]] = {}
     passthroughs: list[tuple[RawEvent, None]] = []
     cwd_by_session: dict[str, str] = {}
     session_source: dict[str, str] = {}
+    fired: Counter[AssumptionTag] = Counter()
 
     for ev in all_events:
         if ev.cwd and ev.session_id not in cwd_by_session:
@@ -115,7 +160,8 @@ def _build_turns_and_sessions(
 
         tc = cost_for_turn(ev.model, usage)
         tags.extend(t for t in tc.assumptions if t not in tags)
-        assumption_recorder.record(tags)
+        for tag in tags:
+            fired[tag] += 1
 
         key_str = k or ev.uuid or str(id(ev))
         turns.append(Turn(
@@ -153,7 +199,7 @@ def _build_turns_and_sessions(
             turns=t_list,
         ))
     sessions.sort(key=lambda s: s.turns[0].timestamp if s.turns else s.session_id)
-    return turns, sessions
+    return turns, sessions, fired
 
 
 @dataclass
@@ -709,7 +755,6 @@ def build_snapshot_full(
       hourly_today, daily, models, recent_activity,
       assumptions_summary
     """
-    assumption_recorder.reset()
     now = datetime.now(tz=timezone.utc)
     today_date = now.date()
     since_90d = today_date - timedelta(days=89)
@@ -717,18 +762,18 @@ def build_snapshot_full(
     dirs = get_config_dirs(all_projects=all_projects)
     paths = find_jsonl_files(dirs)
 
-    all_raw_events: list[RawEvent] = []
     active_keys: set[tuple[str, int, int]] = set()
     for path in paths:
         try:
-            key, events = parse_cache.get_or_parse(path)
+            key, _events = parse_cache.get_or_parse(path)
             active_keys.add(key)
-            all_raw_events.extend(events)
         except OSError:
             pass
 
     parse_cache.purge(active_keys)
-    all_turns, all_sessions = _build_turns_and_sessions(all_raw_events)
+    all_turns, all_sessions, _fired = parse_cache.get_derived(
+        frozenset(active_keys), _build_turns_and_sessions
+    )
 
     turns_90d = [t for t in all_turns if t.timestamp.date() >= since_90d]
     daily_90d = _build_daily_series(turns_90d, since_90d)
@@ -756,7 +801,6 @@ def build_snapshot_full(
     models = _build_models(period_turns, period)
     recent_activity = _build_recent_activity(all_turns, cwd_by_sid, now)
 
-    _fired = assumption_recorder.fired()
     payload = {
         "generated_at": now.isoformat(),
         "config": {"reference_usd": reference_usd, "tick_seconds": tick_seconds},
@@ -781,6 +825,25 @@ def build_snapshot_full(
     return SnapshotResult(payload=payload, turns=all_turns, sessions=all_sessions)
 
 
+def compute_active_keys(all_projects: bool) -> frozenset[tuple[str, int, int]]:
+    """Stat all active JSONL files and return their (path, size, mtime_ns) keys.
+
+    Cheap alternative to a full build_snapshot_full when the only question is
+    "did anything change since the last build?". The SSE broadcaster uses this as
+    an idle gate so unchanged ticks skip the full snapshot assembly entirely.
+    """
+    dirs = get_config_dirs(all_projects=all_projects)
+    paths = find_jsonl_files(dirs)
+    keys: set[tuple[str, int, int]] = set()
+    for p in paths:
+        try:
+            s = p.stat()
+            keys.add((str(p), s.st_size, s.st_mtime_ns))
+        except OSError:
+            pass
+    return frozenset(keys)
+
+
 # ---------------------------------------------------------------------------
 # Endpoint panel builders
 # ---------------------------------------------------------------------------

{tokenol-0.2.0 → tokenol-0.3.0}/src/tokenol/serve/static/app.js

@@ -660,6 +660,7 @@ function _apiToDailyChartData(d) {
   const chart = _normApiSeries(d, p => p.date, dt => new Date(dt + 'T00:00:00').getTime() / 1000);
   chart._activeProjects = d.active_projects ?? [];
   chart._activeModels   = d.active_models   ?? [];
+  chart._note           = d.note ?? null;
   return chart;
 }
 
@@ -714,6 +715,11 @@ const _fetchDaily = _makeFetcher({
 function _paintDaily(data) {
   const scale = _scaleFor(_dMetric, _dScaleRaw);
   _syncScalePills('daily-scale-pills', _dMetric === 'hit_pct' ? 'linear-forced' : scale);
+  const note = $('daily-note');
+  if (note) {
+    if (data._note) { note.textContent = data._note; note.classList.remove('hidden'); }
+    else            { note.textContent = '';         note.classList.add('hidden');    }
+  }
   _paintTimeline('daily-chart', data, 'No history yet — check back after a few days.', {
     xFmt: _xFmtDate,
     stepped: data.labels.map(lbl => lbl !== '7d avg'),

{tokenol-0.2.0 → tokenol-0.3.0}/src/tokenol/serve/static/index.html

@@ -249,6 +249,7 @@
       <span class="filter-group">model <button class="cur" id="daily-model-filter">all ▾</button></span>
       <span class="tl-y-lbl">y auto-fits data · hover for exact values</span>
     </div>
+    <div id="daily-note" class="tl-note hidden"></div>
     <div id="daily-chart" class="tl-chart">
       <div class="tl-insufficient">No history yet — check back after a few days.</div>
     </div>

{tokenol-0.2.0 → tokenol-0.3.0}/src/tokenol/serve/static/styles.css

@@ -487,6 +487,15 @@ header.topbar {
   border-radius: 2px;
   background: var(--bg-soft);
 }
+.tl-note {
+  margin: 0 0 8px;
+  padding: 6px 10px;
+  font-size: 12px;
+  color: var(--mute);
+  background: var(--bg-soft);
+  border-left: 2px solid var(--rule-2);
+  border-radius: 2px;
+}
 .u-tooltip {
   position: absolute;
   pointer-events: none;

tokenol-0.3.0/src/tokenol/serve/streaming.py

@@ -0,0 +1,245 @@
+"""SSE broadcaster: one shared producer fans out diffs to N subscribers per period.
+
+Each connected dashboard tab is a subscriber. Without sharing, N tabs cause N
+independent snapshot rebuilds per tick (the rebuild dominates serve CPU). The
+broadcaster groups subscribers by the only request-scoped axis — `period` — and
+runs one background task per group that builds the snapshot once and fans the
+payload out to every subscriber's queue. Each subscriber tracks its own
+`prev_payload` so the wire format (full first message, shallow-diff thereafter)
+is preserved per-tab regardless of when they joined.
+
+Idle back-off: after `IDLE_THRESHOLD` seconds with no payload changes, the
+producer's tick stretches to `max(tick * 3, 15)` until the next change.
+"""
+
+from __future__ import annotations
+
+import asyncio
+import contextlib
+import json
+import logging
+import time
+from collections.abc import AsyncGenerator, Callable
+
+from tokenol.serve.state import (
+    ParseCache,
+    SnapshotResult,
+    build_snapshot_full,
+    compute_active_keys,
+)
+
+log = logging.getLogger(__name__)
+
+IDLE_THRESHOLD = 30.0
+IDLE_TICK_FLOOR = 15
+SUBSCRIBER_QUEUE_MAXSIZE = 2
+# Time-windowed panels (recent_activity = last 60 min, day boundaries) drift even
+# when no JSONL files change, so we force a rebuild at this cadence regardless of
+# the file-mtime gate. Keeps idle CPU near zero between heartbeats.
+DEFAULT_HEARTBEAT_S = 60.0
+
+
+def _shallow_diff(prev: dict, curr: dict) -> dict:
+    """Return only top-level keys whose values changed."""
+    return {k: v for k, v in curr.items() if prev.get(k) != v}
+
+
+def _effective_tick(tick: int, idle_seconds: float) -> int:
+    if idle_seconds >= IDLE_THRESHOLD:
+        return max(tick * 3, IDLE_TICK_FLOOR)
+    return tick
+
+
+class _Subscriber:
+    __slots__ = ("queue",)
+
+    def __init__(self) -> None:
+        # Bounded queue: producer drops the oldest entry on overflow rather than
+        # blocking, so a slow client can't stall fan-out to other subscribers.
+        self.queue: asyncio.Queue[dict] = asyncio.Queue(maxsize=SUBSCRIBER_QUEUE_MAXSIZE)
+
+
+class _Group:
+    """One producer task + its subscriber set, keyed by `period`."""
+
+    def __init__(
+        self,
+        period: str,
+        build_payload: Callable[[str], dict],
+        compute_keys: Callable[[], frozenset[tuple[str, int, int]]],
+        get_tick_seconds: Callable[[], int],
+        heartbeat_s: float = DEFAULT_HEARTBEAT_S,
+    ) -> None:
+        self.period = period
+        self._build_payload = build_payload
+        self._compute_keys = compute_keys
+        self._get_tick_seconds = get_tick_seconds
+        self._heartbeat_s = heartbeat_s
+        self.subscribers: set[_Subscriber] = set()
+        self.task: asyncio.Task | None = None
+        self.last_payload: dict | None = None
+
+    async def run(self) -> None:
+        """Producer loop with a two-stage gate:
+
+        1. Stat all JSONL files (cheap). If the (path, size, mtime_ns) set is
+           unchanged AND the last build is younger than `heartbeat_s`, skip the
+           build entirely — most idle ticks land here, so per-tick CPU is just
+           the cost of stat'ing a few hundred files.
+        2. Otherwise rebuild and fan out.
+        """
+        prev_payload: dict | None = None
+        prev_keys: frozenset[tuple[str, int, int]] | None = None
+        last_change_ts = time.monotonic()
+        last_built_at: float = 0.0
+        loop = asyncio.get_running_loop()
+        try:
+            while True:
+                tick = int(self._get_tick_seconds())
+                idle_seconds = time.monotonic() - last_change_ts
+                sleep_for = _effective_tick(tick, idle_seconds)
+
+                try:
+                    keys = await loop.run_in_executor(None, self._compute_keys)
+                except Exception:
+                    log.exception("active-keys probe failed — forcing build")
+                    keys = None
+
+                now = time.monotonic()
+                stale = (now - last_built_at) >= self._heartbeat_s
+                changed = keys is None or keys != prev_keys
+                if not (changed or stale or prev_payload is None):
+                    await asyncio.sleep(sleep_for)
+                    continue
+
+                try:
+                    curr = await loop.run_in_executor(
+                        None, self._build_payload, self.period
+                    )
+                except Exception:
+                    log.exception("snapshot build failed — skipping tick")
+                    await asyncio.sleep(sleep_for)
+                    continue
+
+                if prev_payload is None or _shallow_diff(prev_payload, curr):
+                    last_change_ts = time.monotonic()
+                self.last_payload = curr
+                prev_payload = curr
+                prev_keys = keys
+                last_built_at = now
+
+                for sub in list(self.subscribers):
+                    self._push(sub, curr)
+
+                await asyncio.sleep(sleep_for)
+        except asyncio.CancelledError:
+            raise
+
+    @staticmethod
+    def _push(sub: _Subscriber, payload: dict) -> None:
+        """Non-blocking fan-out; on overflow, drop the oldest entry and replace.
+
+        We never want a stuck client to back-pressure the producer.
+        """
+        try:
+            sub.queue.put_nowait(payload)
+            return
+        except asyncio.QueueFull:
+            pass
+        with contextlib.suppress(asyncio.QueueEmpty):
+            sub.queue.get_nowait()
+        with contextlib.suppress(asyncio.QueueFull):
+            sub.queue.put_nowait(payload)
+
+
+class SnapshotBroadcaster:
+    """Shared producer for /api/stream: one task per `period`, fan-out to all tabs.
+
+    The broadcaster is created once per app and held on `app.state.broadcaster`.
+    Subscribers use `subscribe(period)` as an async generator yielding SSE-
+    formatted strings.
+    """
+
+    def __init__(
+        self,
+        parse_cache: ParseCache,
+        all_projects: bool,
+        get_reference_usd: Callable[[], float],
+        get_tick_seconds: Callable[[], int],
+        get_thresholds: Callable[[], dict],
+        heartbeat_s: float = DEFAULT_HEARTBEAT_S,
+    ) -> None:
+        self._parse_cache = parse_cache
+        self._all_projects = all_projects
+        self._get_reference_usd = get_reference_usd
+        self._get_tick_seconds = get_tick_seconds
+        self._get_thresholds = get_thresholds
+        self._heartbeat_s = heartbeat_s
+        self._groups: dict[str, _Group] = {}
+        self._lock = asyncio.Lock()
+
+    def _compute_active_keys(self) -> frozenset[tuple[str, int, int]]:
+        return compute_active_keys(self._all_projects)
+
+    def _build_payload(self, period: str) -> dict:
+        result: SnapshotResult = build_snapshot_full(
+            self._parse_cache,
+            all_projects=self._all_projects,
+            reference_usd=self._get_reference_usd(),
+            tick_seconds=int(self._get_tick_seconds()),
+            period=period,
+            thresholds=self._get_thresholds(),
+        )
+        return result.payload
+
+    async def subscribe(self, period: str) -> AsyncGenerator[str, None]:
+        sub = _Subscriber()
+        async with self._lock:
+            grp = self._groups.get(period)
+            if grp is None:
+                grp = _Group(
+                    period,
+                    self._build_payload,
+                    self._compute_active_keys,
+                    self._get_tick_seconds,
+                    heartbeat_s=self._heartbeat_s,
+                )
+                grp.task = asyncio.create_task(
+                    grp.run(), name=f"snapshot-broadcaster:{period}"
+                )
+                self._groups[period] = grp
+            grp.subscribers.add(sub)
+            # Bootstrap a late-joining subscriber with the most recent payload so
+            # they don't wait a full tick for their first message.
+            if grp.last_payload is not None:
+                _Group._push(sub, grp.last_payload)
+
+        prev_payload: dict | None = None
+        try:
+            while True:
+                payload = await sub.queue.get()
+                data = payload if prev_payload is None else _shallow_diff(prev_payload, payload)
+                prev_payload = payload
+                if data:
+                    yield f"data: {json.dumps(data)}\n\n"
+        finally:
+            async with self._lock:
+                grp.subscribers.discard(sub)
+                if not grp.subscribers:
+                    if grp.task is not None:
+                        grp.task.cancel()
+                    self._groups.pop(period, None)
+
+    async def shutdown(self) -> None:
+        async with self._lock:
+            tasks = [g.task for g in self._groups.values() if g.task is not None]
+            for t in tasks:
+                t.cancel()
+            self._groups.clear()
+        for t in tasks:
+            with contextlib.suppress(asyncio.CancelledError, Exception):
+                await t
+
+    def group_count(self) -> int:
+        """Number of active producer groups (testing aid)."""
+        return len(self._groups)