ADORSYS-GIS / ADORSYS-GIS/lightbridge-authz

[Story]: Continuous aggregates per KPI measure, refresh proven, aggregates never span grains

Aperta
#587 1 commento 0 reazioni 0 assegnatari Vedi su GitHub
user-story
Lingua principale
Rust
Stelle
0
Fork
1
Merge medio
6h 42m
PR unite (30g)
246

Descrizione

Parent epic: #581

### Story Statement

As a platform operator, every dashboard KPI reads a named continuous aggregate with a running refresh policy — never a raw-table scan — and each measure has exactly one authoritative source.

### Real Intent

Deliver #491's "10 named continuous aggregates" goal on the new grain tables, under governance#166's rules: one aggregate per measure, exactly one authoritative source per measure, no aggregate spans grains.

### Background and Context

There are zero continuous aggregates today (and there could not be — production had no TimescaleDB, #489/#549). Once the grain tables are real hypertables, the KPI read path must be proven to use aggregates, not assumed: the house failure mode is silent success.

### Source of truth (links)

ADR-0027 Decision 5 · #491 · governance#166 · #489

### Acceptance Criteria

1. A named continuous aggregate per KPI measure (spend, tokens, requests, latency percentiles where supported, active users, acceptance placeholders as sources land), each built on exactly one grain table — no aggregate joins or unions across grains.
2. Refresh policies exist in `timescaledb_information.jobs` and have demonstrably run in the target cluster.
3. For each KPI query, an `EXPLAIN` (captured in the PR) proves the aggregate is read.
4. Aggregates preserve the money discipline: unknown-cost rows counted separately, never coerced to 0 in the rollup.
5. If a percentile aggregate needs `timescaledb_toolkit`, the image decision records it (the `-ha` image question from governance#163); an approximation, if used, is named in the API docs.

### Out of Scope

New KPI definitions (take #491's list); dashboard wiring.

### Dependencies and Blockers

Grain tables + Timescale image landed; per-grain query endpoints (aggregates back them).

### Assumptions

The 90d retention window (#489) is compatible with every aggregate's refresh lag — verify, don't assume, for month-boundary billing queries.

### Implementation Notes

`migrations-usage/`, fail-loud; aggregate names are part of the API surface — document them beside the endpoints they back.

### Test Expectations

A test (or CI check) per aggregate asserting existence + refresh-policy presence; an EXPLAIN-based assertion that the query path hits the aggregate.

### Verification evidence

To be attached on the implementing PR: `timescaledb_information.jobs` output, EXPLAIN captures.

### Human accountable owner

Stephane Segning Lambou

### AI Usage
AI-assisted (Claude): research and drafting. Reviewed and owned by Stephane Segning Lambou.

Guida per i contributori

Apri la guida per i contributori

Valutazione

Questa issue non è ancora stata valutata.

Ricevi le nuove issue nella tua casella

Un breve riepilogo di issue GitHub adatte ai principianti.