Repository navigation
Usage snapshots: move ingestion out of the aggregator read path and report writer health #1205
Description
Part of epic #1184 (PM stack coherence review, 2026-10-26).
Snapshot history depends on a write side-effect inside a read path and on manual backfill scripts. Evidence: live.ts usage() appends feed snapshots during a GET — 'the one write this reader makes' — and history otherwise depends on scripts/backfill-usage-snapshots.ts and append-usage-snapshots.ts being run by owning jobs. Empty history renders as a bare 'No snapshots yet' with no writer-health context.
Acceptance:
- GET /quota and /quota/service/* perform no writes (test with a read-only store dir).
- Snapshot freshness per service is visible on the service page/health.
- Backfill remains a documented one-shot, not a load-bearing manual step.
Acceptance criteria
- GET /quota and /quota/service/* perform no writes (verified with a read-only store dir).
- Snapshot freshness per service is visible on the service page and/or /health.
- Backfill remains a documented one-shot step, not a load-bearing manual step.
Metadata
Metadata
Assignees
Labels
pm-stack (Pad/Grist) in developing-today/codeMedium: expected under 1 day of workRoutine maintenance, housekeeping, dependency hygieneIntake review done: acceptance criteria, links, and normalized labels addedOrdinary priority (the default)Filed directly by a humanQueue packet kind: verify, reproduce, and route this item
Activity
developing-today commentedon Oct 27, 2026
CODE-339
dezren39 commentedon Oct 28, 2026
Intake review — fleet monitor
Liveness: Verified still live at intake (2026-10-28): issue is open and unheld, and a merged-PR search for
#1205returned only unrelated text matches (no PR title or fix reference resolves this item). Part of epic #1184 (PM stack coherence review, 2026-10-26); sibling batch #1210–#1222 was enriched in the previous monitor run.Notes: A write inside a GET is the root smell; moving ingestion to the writer jobs also makes freshness measurable. Risk: snapshot cadence changes must not starve history — keep the backfill script as the documented one-shot it already is.
Risks: Scope creep across the pm-stack pages is the main risk for this batch; the acceptance criteria above (converted from the issue's original Acceptance list) bound the work. CI on the aggregator's render/derive tests is the verification surface.
Suggested approach: Take the acceptance criteria in order; keep the JSON twins in lockstep with the HTML pages, per the batch convention.
Labels normalised this pass:
source/human(coherence-review filer),effort/m,meta/enriched; existing kind/priority/status/app labels kept.17 remaining items
dezren39 commentedon Nov 3, 2026
agent-note:v1
state: triaged (coverage pass)
Coverage pass 2026-11-03: reviewed in the fleet-wide per-issue pass (drift / overlap / already-handled / stale / blockers / ordering). Verdict: still live; queued in repo-health-code-pilot as triage at priority 40 (priority/normal). If this is already handled at current main, the triage closes it with evidence; if it needs splitting, the triage files the split.
Found via: coverage pass 2026-11-03
dezren39 commentedon Nov 3, 2026
🤖 Agent note · done — already done (verified at current main)
live.tsusage()now only reads the store ("This reader only reads it"); the append moved to a dedicatedingestSnapshots()on the source, called only fromserver.ts's background writer tick (setInterval(SNAPSHOT_INGEST_INTERVAL_MS)+ one startup recovery call, server.ts:1857-1871) — never from a GET handler.freshnessStamp(measuredAt, sourceClass, cadenceDays)with stale flagging (render.ts ~2212-2227);/healthreports feed freshness against the 5m threshold (health.ts:355).scripts/backfill-usage-snapshots.tsas an "idempotent one-shot recovery, not normal history startup" and inventories the three snapshot writers (README ~553-556).already_done.