perf(cache): serve records_cost from the warm cache

pi/OpenClaw/CSV/JSONL probed records_cost in their constructors by
reading the whole corpus, and make_store builds the leaf before
CachedStore wraps it -- so even a 100% cache hit paid a serial full
read of every session file. Make records_cost a lazy property on those
four backends (derived from an already-run parse, with the early-exit
probe only as a first-read fallback), persist it in the cache payload
(CACHE_VERSION 3), and have CachedStore answer it on a fingerprint hit
without touching the leaf. CombinedStore's AND over its backends turns
into a cached_property for the same reason. While at it, a cache-hit
row that no longer matches the Workflow dataclass falls back to a real
parse instead of crashing.

Author: Gheat1

src/opentab/stores/cached.py

@@ -9,11 +9,12 @@
 falls through to a normal parse, then rewrites the cache, so a stale rollup is never
 shown; mtime is nanosecond-grained, so an in-place edit reliably invalidates.
 
-Only workflows() and model_breakdown() are intercepted -- they feed the first frame.
-Everything else (workflow_nodes, tool_breakdown, message_timeline, supports_*, summary,
-records_cost, demo, demo_scale, ...) delegates straight to the wrapped store, which
-parses lazily the first time you actually drill into a session. So a warm start paints
-instantly and only pays the parse if and when you open a session's detail.
+Only workflows(), model_breakdown() and records_cost are intercepted -- they feed the
+first frame (records_cost because some backends can only answer it by reading their
+whole corpus). Everything else (workflow_nodes, tool_breakdown, message_timeline,
+supports_*, summary, demo, demo_scale, ...) delegates straight to the wrapped store,
+which parses lazily the first time you actually drill into a session. So a warm start
+paints instantly and only pays the parse if and when you open a session's detail.
 
 The cache is disabled under --demo (demo never persists, and its per-process scale must
 not be baked in) and --no-cache; sources.make_store applies the wrapper.
@@ -28,7 +29,7 @@
 
 from opentab.models import Workflow
 
-CACHE_VERSION = 2  # bump when the cached payload shape changes (invalidates old files)
+CACHE_VERSION = 3  # bump when the cached payload shape changes (invalidates old files)
 
 
 def cache_dir() -> str:
@@ -49,10 +50,21 @@ def __init__(self, store, cache_id: str, args: argparse.Namespace):
         self.served_from_cache: bool | None = None  # set by workflows(); read by --timings
 
     # Anything not intercepted below is the wrapped store's -- workflow_nodes, the Turns/
-    # Tools extras, supports_*, records_cost, demo, source_name, summary, and so on.
+    # Tools extras, supports_*, demo, source_name, summary, and so on.
     def __getattr__(self, name):
         return getattr(self._store, name)
 
+    @property
+    def records_cost(self) -> bool:
+        # Served from the cache on a fingerprint hit: some backends (pi/OpenClaw/CSV/
+        # JSONL) can only answer this by reading their whole corpus, which would defeat
+        # the warm start. A miss (or a pre-v3 cache) delegates like __getattr__ does.
+        if self._disk is not None and "records_cost" in self._disk:
+            fp = self._live_fp if self._live_fp is not None else self._fingerprint()
+            if self._disk.get("fingerprint") == fp:
+                return bool(self._disk["records_cost"])
+        return getattr(self._store, "records_cost", True)
+
     # --- fingerprint / cache file -------------------------------------------------
     def _fingerprint(self) -> list:
         # Sorted [path, size, mtime_ns] over the backend's inputs. Lists (not tuples) so
@@ -89,6 +101,9 @@ def _write(self, fingerprint: list, workflows: list, model_breakdown: list) -> N
             "version": CACHE_VERSION,
             "source": self._source,
             "fingerprint": fingerprint,
+            # Cheap here: the backend just parsed, so a lazy records_cost derives from
+            # that parse instead of running its full-corpus probe.
+            "records_cost": bool(getattr(self._store, "records_cost", True)),
             "workflows": workflows,
             "model_breakdown": model_breakdown,
         }
@@ -108,9 +123,14 @@ def workflows(self) -> list:
         # fingerprint (the common warm start / no-op reload) serves the cache untouched.
         self._live_fp = self._fingerprint()
         if self._disk is not None and self._disk.get("fingerprint") == self._live_fp:
-            self._fresh_wf = None  # a hit: nothing new to write
-            self.served_from_cache = True
-            return [Workflow(**row) for row in self._disk["workflows"]]
+            try:
+                rows = [Workflow(**row) for row in self._disk["workflows"]]
+            except TypeError:
+                self._disk = None  # cached fields drifted from the dataclass: reparse
+            else:
+                self._fresh_wf = None  # a hit: nothing new to write
+                self.served_from_cache = True
+                return rows
         workflows = self._store.workflows()  # miss: real parse
         self._fresh_wf = [asdict(w) for w in workflows]
         self.served_from_cache = False

src/opentab/stores/combined.py

@@ -2,6 +2,7 @@
 from __future__ import annotations
 
 from concurrent.futures import ThreadPoolExecutor
+from functools import cached_property
 
 from opentab.models import Workflow
 
@@ -45,7 +46,6 @@ class CombinedStore:
 
     def __init__(self, stores: list):
         self.stores = stores
-        self.records_cost = all(getattr(s, "records_cost", True) for s in stores)
         # Combined demo: each backend would otherwise draw its own random hidden scale,
         # which would distort the cross-source ratio (the Sources view lies about the
         # OpenCode-vs-Claude proportion). Share ONE scale across all backends so the
@@ -66,6 +66,13 @@ def __init__(self, stores: list):
         )
         self._owner: dict[str, object] = {}
 
+    @cached_property
+    def records_cost(self) -> bool:
+        # AND of the backends (False when any doesn't record cost), evaluated lazily so
+        # building the merged view never forces a backend's full-corpus cost probe --
+        # after workflows() the warm-start cache answers this for free.
+        return all(getattr(s, "records_cost", True) for s in self.stores)
+
     def workflows(self) -> list[Workflow]:
         # Roll up every backend in parallel, then build the id->owner map and merge on
         # this thread (deterministic, order-preserving) -- see _gather.

src/opentab/stores/csv_source.py

@@ -39,7 +39,9 @@ class CsvStore:
     list rates.
     But cost is handled per-row like HermesStore: if the CSV carries a cost_usd/credits
     column with positive values those rows price as real spend, so records_cost is a
-    per-instance attr (True iff any row has a recorded cost), probed cheaply in __init__.
+    per-instance property (True iff any row has a recorded cost), resolved lazily --
+    derived from a parse when one has run, else probed on first read (never in __init__,
+    so the warm-start cache can answer it without touching the file).
 
     Models are mixed-provider, so each id is provider-prefixed (claude->anthropic/,
     gpt|o3->openai/, gemini->google/) for pricing and the Providers rollup. OpenAI-style
@@ -103,7 +105,7 @@ def __init__(self, csv_path: str, args: argparse.Namespace):
         self.demo_scale = 3.0 ** random.uniform(-1.0, 1.0) if self.demo else 1.0
         self._sessions: dict[str, dict] | None = None  # parsed lazily / on reload
         self._git_root_cache: dict[str, str] = {}
-        self.records_cost = self._probe_records_cost()
+        self._records_cost: bool | None = None  # resolved lazily (records_cost property)
 
     # --- header / value parsing ---------------------------------------------
     @classmethod
@@ -207,9 +209,23 @@ def _resolve_dir(self, project: str) -> str:
             return self._git_root(project)
         return project
 
+    @property
+    def records_cost(self) -> bool:
+        # True iff any row records a positive cost. Lazy so construction never reads the
+        # file (the warm-start cache answers a hit without reaching here): after a parse
+        # it derives from the accumulated per-model costs; the full-file probe runs only
+        # when it is read before any parse.
+        if self._sessions is not None:
+            return any(
+                acc["cost"] > 0 for s in self._sessions.values() for acc in s["models"].values()
+            )
+        if self._records_cost is None:
+            self._records_cost = self._probe_records_cost()
+        return self._records_cost
+
     def _probe_records_cost(self) -> bool:
-        # True iff the CSV has a cost column with any positive value. Cheap pass so it is
-        # safe in __init__ (CombinedStore reads records_cost before workflows()).
+        # True iff the CSV has a cost column with any positive value. Early-exits so it
+        # stays cheap.
         try:
             with open(self.csv_path, newline="", encoding="utf-8", errors="replace") as fh:
                 reader = csv.DictReader(fh)

src/opentab/stores/jsonl_source.py

@@ -81,7 +81,7 @@ def __init__(self, path: str, args: argparse.Namespace):
         self.demo_scale = 3.0 ** random.uniform(-1.0, 1.0) if self.demo else 1.0
         self._sessions: dict[str, dict] | None = None
         self._git_root_cache: dict[str, str] = {}
-        self.records_cost = self._probe_records_cost()
+        self._records_cost: bool | None = None  # resolved lazily (records_cost property)
 
     def cache_inputs(self) -> list[str]:
         # The single JSONL file whose (size, mtime) fingerprints the warm-start cache.
@@ -107,8 +107,8 @@ def _row_cost(self, obj: dict) -> float:
         return 0.0
 
     def _probe_records_cost(self) -> bool:
-        # True iff any line records a positive cost. Cheap pass, safe in __init__
-        # (CombinedStore reads records_cost before workflows()).
+        # True iff any line records a positive cost. Early-exits so it stays cheap; only
+        # run when records_cost (the lazy CsvStore property) is read before any parse.
         try:
             with open(self.path, encoding="utf-8", errors="replace") as fh:
                 for line in fh:

src/opentab/stores/openclaw.py

@@ -31,9 +31,10 @@ class OpenClawStore:
     **unpriced** (the "$" view estimates them) while metered messages with a real cost price
     as spend. The two accumulate independently per message, so a session (even one model)
     mixing both routes is split correctly. Cost is therefore mixed, so -- exactly like
-    `CsvStore`/`HermesStore`/`PiStore` -- **`records_cost` is a per-instance attr** (True iff
-    any *metered* message has a cost), set by a cheap early-exit probe in `__init__` so
-    `CombinedStore` can read it before `workflows()`.
+    `CsvStore`/`HermesStore`/`PiStore` -- **`records_cost` is a per-instance property** (True
+    iff any *metered* message has a cost), resolved lazily: derived from a parse when one
+    has run, else by an early-exit probe on first read (never in `__init__`, so construction
+    stays free and the warm-start cache can answer it without touching the files).
 
     Parsing: each session file is newline-delimited JSON,
     and only `type:"message"` records with `message.role == "assistant"` and a `message.usage`
@@ -85,7 +86,7 @@ def __init__(self, root_dir: str, args: argparse.Namespace):
         # provider logs in via "oauth" (a consumer plan, subscription) or a static "token"
         # (a metered API key). Read-only; we read only the mode + provider name.
         self._oauth_providers = self._load_oauth_providers()
-        self.records_cost = self._probe_records_cost()
+        self._records_cost: bool | None = None  # resolved lazily (records_cost property)
 
     # --- mixed-provider model ids (mirrors CsvStore) -------------------------
     @staticmethod
@@ -276,10 +277,24 @@ def _files(self) -> list[str]:
                 out.append(path)
         return out
 
+    @property
+    def records_cost(self) -> bool:
+        # True iff any *metered* (non-subscription) message records real spend. Lazy so
+        # construction never reads the corpus (the warm-start cache answers a hit without
+        # reaching here): after a parse it derives from the accumulated per-model costs;
+        # the full-file probe runs only when it is read before any parse.
+        if self._sessions is not None:
+            return any(
+                acc["cost"] > 0 for s in self._sessions.values() for acc in s["models"].values()
+            )
+        if self._records_cost is None:
+            self._records_cost = self._probe_records_cost()
+        return self._records_cost
+
     def _probe_records_cost(self) -> bool:
         # True iff any *metered* (non-subscription) assistant message records a positive
-        # cost. Early-exits so it stays cheap (safe in __init__; CombinedStore reads it
-        # before workflows()). A subscription-only setup -> False (every cost is estimated).
+        # cost. Early-exits so it stays cheap. A subscription-only setup -> False (every
+        # cost is estimated).
         for path in self._files():
             try:
                 fh = open(path, encoding="utf-8", errors="replace")

src/opentab/stores/pi.py

@@ -31,9 +31,10 @@ class PiStore:
     **unpriced** (the "$" view estimates them), while metered messages with a real cost
     price as spend. The two accumulate independently per message, so a session (even one
     model) mixing both routes is split correctly. Cost is therefore mixed, so -- exactly
-    like `CsvStore`/`HermesStore` -- **`records_cost` is a per-instance attr** (True iff any
-    *metered* message has a cost), set by a cheap early-exit probe in `__init__` so
-    `CombinedStore` can read it before `workflows()`.
+    like `CsvStore`/`HermesStore` -- **`records_cost` is a per-instance property** (True iff
+    any *metered* message has a cost), resolved lazily: derived from a parse when one has
+    run, else by an early-exit probe on first read (never in `__init__`, so construction
+    stays free and the warm-start cache can answer it without touching the files).
 
     Each session file is newline-delimited JSON: a `session` record carries the canonical
     id + **cwd** (so directories fold to the **git root**, no path-decoding the project
@@ -66,7 +67,7 @@ def __init__(self, root_dir: str, args: argparse.Namespace):
         # "$" view estimates them -- exactly like HermesStore's billing_mode split. The
         # signal: auth.json marks plan logins as type "oauth"; plus a few provider markers.
         self._oauth_providers = self._load_oauth_providers()
-        self.records_cost = self._probe_records_cost()
+        self._records_cost: bool | None = None  # resolved lazily (records_cost property)
 
     # --- helpers -------------------------------------------------------------
     def _git_root(self, cwd: str) -> str:
@@ -186,10 +187,24 @@ def cache_inputs(self) -> list[str]:
     def _files(self) -> list[str]:
         return glob.glob(os.path.join(self.root_dir, "**", "*.jsonl"), recursive=True)
 
+    @property
+    def records_cost(self) -> bool:
+        # True iff any *metered* (non-subscription) message records real spend. Lazy so
+        # construction never reads the corpus (the warm-start cache answers a hit without
+        # reaching here): after a parse it derives from the accumulated per-model costs;
+        # the full-file probe runs only when it is read before any parse.
+        if self._sessions is not None:
+            return any(
+                acc["cost"] > 0 for s in self._sessions.values() for acc in s["models"].values()
+            )
+        if self._records_cost is None:
+            self._records_cost = self._probe_records_cost()
+        return self._records_cost
+
     def _probe_records_cost(self) -> bool:
         # True iff any *metered* (non-subscription) assistant message records a positive
-        # cost. Early-exits so it stays cheap (safe in __init__; CombinedStore reads it
-        # before workflows()). A subscription-only setup -> False (every cost is estimated).
+        # cost. Early-exits so it stays cheap. A subscription-only setup -> False (every
+        # cost is estimated).
         for path in self._files():
             try:
                 fh = open(path, encoding="utf-8", errors="replace")