coulomb/state-hub
2
0
Fork 0
generated from coulomb/repo-seed
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

feat(summary): revision-gated cache with stale-while-revalidate (STATE-WP-0066)

Browse Source 
Replace the fixed 15s TTL on GET /state/summary with per-table revision
watermarks, stale-while-revalidate background refresh, and a progress-tail
section split. SQLAlchemy write hooks invalidate core or progress sections
on mutation. Adds tests, benchmark script, and operator docs.
This commit is contained in:
Bernd Worsch
2026-06-22 16:27:32 +02:00
parent f88e74288d
commit 94c7817339
10 changed files with 614 additions and 35 deletions
Download Patch File Download Diff File Expand all files Collapse all files

37
workplans/STATE-WP-0066-state-summary-revision-cache.md
View File

@@ -4,12 +4,13 @@ type: workplan
title: "State summary revision cache and stale-while-revalidate"
domain: custodian
repo: state-hub
status: ready
status: finished
owner: codex
topic_slug: custodian
created: "2026-06-22"
updated: "2026-06-22"
state_hub_workstream_id: ""
finished: "2026-06-22"
state_hub_workstream_id: "f738cd77-6b8b-40e5-b348-dc304c7821f1"
---
# STATE-WP-0066 — State summary revision cache and stale-while-revalidate
@@ -147,9 +148,9 @@ Preserve truthful `generated_at` on cache hits (when the snapshot was built).
```task
id: STATE-WP-0066-T01
status: todo
status: done
priority: high
state_hub_task_id: ""
state_hub_task_id: "8ee836ec-048c-44f6-b16e-e7454d07371a"
```
Extract summary cache logic from `api/routers/state.py` into a dedicated
@@ -171,9 +172,9 @@ Done when revision fetch is tested in isolation and profiled under local DB.
```task
id: STATE-WP-0066-T02
status: todo
status: done
priority: high
state_hub_task_id: ""
state_hub_task_id: "c5fc8ab8-5fc8-463b-9ae7-c304a7e0383e"
```
Wire revision check into `GET /state/summary`:
@@ -192,9 +193,9 @@ skip the heavy query path (assert via mock or elapsed-ms header threshold).
```task
id: STATE-WP-0066-T03
status: todo
status: done
priority: high
state_hub_task_id: ""
state_hub_task_id: "aa079e17-6103-4539-878d-b451035e5f8a"
```
When revision differs but a cached snapshot exists:
@@ -214,9 +215,9 @@ runs; second request after rebuild shows `hit-revision`.
```task
id: STATE-WP-0066-T04
status: todo
status: done
priority: medium
state_hub_task_id: ""
state_hub_task_id: "99b14a10-ff1b-4609-a62b-5da19b79be68"
```
Split cache into `core` and `progress_tail` sections:
@@ -234,9 +235,9 @@ re-running domain/SBOM/flow-engine work (verify via query count or spy).
```task
id: STATE-WP-0066-T05
status: todo
status: done
priority: medium
state_hub_task_id: ""
state_hub_task_id: "0df9c1c2-6edf-4be3-bee8-b75e0d24fc02"
```
Call `invalidate_summary_cache()` (or equivalent revision bump) from write
@@ -254,9 +255,9 @@ Done when mutation routes trigger invalidation and tests pass.
```task
id: STATE-WP-0066-T06
status: todo
status: done
priority: high
state_hub_task_id: ""
state_hub_task_id: "5f68f999-d5ca-40df-a054-aaf762837342"
```
Prove cache effectiveness under realistic load:
@@ -276,9 +277,9 @@ and CI tests are green.
```task
id: STATE-WP-0066-T07
status: todo
status: done
priority: low
state_hub_task_id: ""
state_hub_task_id: "aee0f349-761f-42b7-82b2-6a319936a68e"
```
Update:
@@ -300,9 +301,9 @@ Done when docs match implemented headers and invalidation semantics.
```task
id: STATE-WP-0066-T08
status: todo
status: done
priority: medium
state_hub_task_id: ""
state_hub_task_id: "b4e967ab-57ba-4f0f-9161-373b383248b5"
```
End-to-end check from Railiance01 (or documented manual runbook):