Split last_upsert (persisted write) and last_refresh (run liveness) in stats

src/sqlmem/stats.py

@@ -17,7 +17,13 @@ class TableState:
 class TableStats:
     rows: int
     columns: list[str]
-    last_refresh: str
+    # Persisted wall-clock of the last actual data write (full load / delta with rows).
+    # Survives restarts. Answers "when did the data last change?".
+    last_upsert: str | None
+    # In-memory (this process) wall-clock of the last time a refresh cycle ran for the
+    # table — bumped even when the cycle wrote nothing. Liveness signal; ``None`` until
+    # the first cycle runs after start. Answers "is the refresh loop alive?".
+    last_refresh: str | None = None
     state: str = TableState.READY
     tracking: str = "static"  # "delta" | "ttl" | "static"
     # Most recent load/refresh failure for this table, if any. ``consecutive_failures``
@@ -64,7 +70,7 @@ class StatsCollector:
 
         tables: dict[str, TableStats] = {}
         cached: set[str] = set()
-        for table_name, row_count, last_refresh in conn.execute(
+        for table_name, row_count, last_upsert in conn.execute(
             "SELECT table_name, row_count, last_refresh_at FROM _sqlmem_tables"
         ).fetchall():
             cached.add(table_name)
@@ -75,16 +81,18 @@ class StatsCollector:
                     (table_name,),
                 ).fetchall()
             ]
+            # last_refresh (run/liveness) is filled in by the engine from the
+            # in-memory last-run map; only the persisted write time is read here.
             tables[table_name] = TableStats(
                 rows=row_count or 0,
                 columns=columns,
-                last_refresh=last_refresh,
+                last_upsert=last_upsert,
                 state=states.get(table_name, TableState.READY),
             )
 
         # Surface tables that are mid-first-load (not yet in _sqlmem_tables) or failed.
         for name, state in states.items():
             if name not in cached and state in (TableState.LOADING, TableState.ERROR):
-                tables[name] = TableStats(rows=0, columns=[], last_refresh="", state=state)
+                tables[name] = TableStats(rows=0, columns=[], last_upsert=None, state=state)
 
         return Stats(hits=hits, misses=misses, refetches=refetches, tables=tables)