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

2026-06-09 08:48:29 +02:00
parent 6dc85e4f3c
commit 8744f458cc
10 changed files with 108 additions and 11 deletions
@@ -6,6 +6,20 @@ All notable changes to this project will be documented in this file.

 ---

+## [1.10.0] - 2026-06-09
+
+### Added
+- **`last_upsert` (persisted write) vs `last_refresh` (run/liveness) in `stats`** — `TableStats.last_refresh` previously came from the persisted `last_refresh_at` column, which is only written when rows are actually written (a delta cycle with `total == 0` early-returns and leaves it unchanged). A healthy delta that keeps finding no new rows therefore *looked* frozen. The single value is now split:
+  - `last_upsert` — wall-clock (UTC) of the last actual data write (full load / delta with rows). Persisted, survives restarts (this is the existing `last_refresh_at` column, surfaced under a clearer name).
+  - `last_refresh` — wall-clock (UTC) of the last time a refresh cycle *ran* for the table, **even when it wrote nothing**. In-memory per process (`None` until the first cycle after start), tracked like `_states`/`_errors` — so **no schema change and no cache wipe**.
+  - `CacheManager` gained `mark_refresh_ran()` / `get_last_runs()`; an empty delta cycle now records a run. TTL staleness still uses the last *write* (`seconds_since_refresh` reads `last_refresh_at`), so behaviour is unchanged.
+
+### Changed
+- `pyproject.toml` — bumped version to `1.10.0`.
+- **`TableStats.last_refresh` is now `str | None`** (was `str`) and a new required `last_upsert: str | None` field is added. Consumers reading `last_refresh` for "when did data change?" should switch to `last_upsert`.
+
+---
+
 ## [1.8.0] - 2026-06-08

 ### Fixed