[GottZ]

Wave W06-5 of the OpenAI-compatible API plan (RC-A, telemetry foundation; design/06 §4.7). No migration, no /v1 surface.

What this changes

• /api/status llm_24h (server view, queryLLM24h) and the per-tenant llm_24h generation (buildTenantRollupInto) read the hourly rollup context_llm_usage_hourly from the first full UTC hour after now − 24 h plus the raw context_llm_log rows of that first, partial hour, through two new readers in internal/llmusage (Groups, TenantGroups), instead of scanning 24 h of raw rows per tick. The tenant reader joins both parts through context_api_keys → context_tenant_scopes exactly as the raw query did; a consumer's row (api_key_id NULL) counts for no tenant.
• llm_24h_complete comes from the rollup's unattributed_ok (successful rows without a backend) plus the same count over the edge rows: a failed row without a backend keeps complete true, as before.
• Output is byte-identical to the raw aggregate (golden below); the one deliberate difference is a deterministic tie order.
• Docs: docs/operations.md (rollup readers now quota + status; rollback coupling), docs/architecture.md.

Behaviour changes (intended)

• Rows with the same calls are now ordered by backend, then pipeline (the raw query ordered by calls alone and left ties to the plan; live has 16/16 ties).
• Backend and pipeline names longer than 100 characters show cut to 100 — the rollup's dimension width since migration 159 (the longest live name has 24 characters). Pinned by a test.
• The window ends at the daemon's clock, not the database's now() (same host in production; tests pin the anchor on the boundaries).
• On an error in the middle of the result the server view returns an empty list and complete=false instead of the rows read so far plus false.

Consumers of the changed contracts

Changed symbol	Callers / readers	Covered by
queryLLM24h, buildTenantRollupInto (same signatures, new source)	status tick (assemble), SnapshotForTenant, SSE /api/events	TestStatusLLM24hGolden (byte-equal to the base), TestStatusLLM24hParity (300 random seeds vs the raw SQL), TestStatusLLM24hPlan, TestStatusPerTenantView, TestStatusGoldenKeys, TestStatusEventCarriesEveryDualPathField, 58 handler top-level tests
llmusage.Groups, TenantGroups (new)	the two readers above	internal/llmusage suite (9/9), the handler suites
promptguard call-site census	internal/handler:g.Pipeline passthrough (a copied string, no prompt)	promptguard_callsite_test.go

Overlap search

Open PRs #55/#57/#63/#67 on 2026-11-03: no shared files. Based on #74 (14b99639); root unchanged since.

Cost

Per status tick: the edge is at most one hour of raw rows bounded on both sides (23 rows in the plan test vs 1 079 for the raw 24 h scan), the rest through idx_llm_usage_bucket; pinned under the custom and the forced-generic plan. Tenant view: the same two parts joined to the key and scope tables.

Verification

Gates, each red on 14b99639 first: (a) existing suites green before and after (handler 52 → 58, llmusage 9/9); (b) golden: a 16 027-byte JSON of both views generated on the base tree from the base SQL (only now() → $1 and the tie-break added; the base functions match it up to tie order), new code byte-equal (same sha256, empty diff); red on base by compile error, red against overlays: no edge hour 253/300 seeds, truncated mean 262/300, no tie-break 298/300; (c) complete probe: red when the rollup read omits unattributed_ok and when the edge does not count it; an error row without a backend keeps complete true; (d) EXPLAIN custom + generic: 23 raw rows (exactly the edge) vs 1 079, rollup via idx_llm_usage_bucket; the base SQL fails the same check; (e) consumer rows absent from the tenant view — pinned, red against an overlay that credits them to a tenant.

Suites on the head: go build ./..., go vet -tags=integration ./..., golangci-lint run with and without --build-tags=integration (0), go test -short -race ./..., deadcode.sh + deadcode.sh testonly, integration -p 1 for internal/llmusage and -run 'Status|Events|LLMLog|Quota' for internal/handler + internal/backends. Independent review by a fresh agent during the build: 1 minor (the 100-character cut — documented and pinned), 4 nits (3 fixed, the error-path change documented above).

Not verified

• Clock skew between daemon and database shifts the window by that skew (same host in production).
• The 100-character cut is only observable with names ctx does not produce today.

🤖 Generated with Claude Code

Summary by CodeRabbit

• Updates
  • Server-wide and tenant-level 24-hour LLM usage summaries now use hourly usage data alongside records from the current partial hour.
  • Summaries indicate when usage data is incomplete because successful calls could not be attributed.
  • Backend and pipeline names are limited to 100 characters in summaries; names that match after truncation are grouped together.
• Documentation
  • Updated architecture and operations guidance for usage summaries, attribution, retries, and the effects of removing or disabling rollup data collection.

[coderabbitai]

No actionable comments were generated in the recent review.

Walkthrough

Server and tenant status views now read 24-hour LLM usage through shared readers that combine hourly rollups with raw rows from the edge hour. Integration tests compare these readers with raw-row references and inspect their PostgreSQL execution plans.

Changes: Hourly LLM status rollups

Layer / File(s)	Summary
Shared reader contract and queries go/internal/llmusage/groups.go, go/internal/llmusage/window.go, go/internal/llmusage/window_integration_test.go, docs/architecture.md, docs/operations.md	The shared readers aggregate server-wide or tenant-scoped usage from hourly rollups and raw edge-hour rows. They normalize backend and pipeline names to 100 characters and order results deterministically. The documentation also describes identity constraints, retry behavior, and rollup operations.
Server and tenant status integration go/internal/handler/status.go, go/internal/handler/status_tenant.go, go/internal/handler/status_llm24h_ref_integration_test.go, go/internal/handler/status_llm24h_golden_integration_test.go, go/internal/handler/testdata/llm24h_golden.json, go/internal/promptguard/promptguard_callsite_test.go, docs/operations.md	Both status paths use the shared readers. Server completeness is false when a group has unattributed successful calls. Integration fixtures check output against raw-row references, including tenant attribution, edge-hour cases, and truncated names. Operations documentation describes status behavior when the rollup table or trigger is removed.
Parity and query-plan validation go/internal/handler/status_llm24h_parity_integration_test.go, go/internal/handler/status_llm24h_plan_integration_test.go	Integration tests compare randomized reader results with raw-row references and check custom and generic PostgreSQL plans for bounded raw scans and rollup index use.

Estimated code review effort: 3 (Moderate) | ~25 minutes

Change: Refactor

Sequence Diagram(s)

sequenceDiagram
  participant ServerStatus
  participant TenantStatus
  participant llmusage
  participant PostgreSQL
  ServerStatus->>llmusage: Groups(ctx, now, 24h)
  llmusage->>PostgreSQL: Read raw edge rows and hourly rollups
  PostgreSQL-->>llmusage: Return grouped usage
  llmusage-->>ServerStatus: Return groups
  TenantStatus->>llmusage: TenantGroups(ctx, now, 24h)
  llmusage->>PostgreSQL: Read tenant-scoped edge rows and rollups
  PostgreSQL-->>llmusage: Return scoped groups
  llmusage-->>TenantStatus: Return groups

Loading

Possibly related PRs

• GottZ/ctx#74: Adds the shared rolling-window package that these status readers extend.
• GottZ/ctx#73: Adds the hourly rollup table and trigger queried by these readers.
• GottZ/ctx#72: Adds the consumer identity constraint used by tenant attribution and the status fixtures.

Suggested reviewers: w4-nerf

Merge Risk: Minimal · up to 76779

No actionable issue is established for the server or tenant 24-hour status views; the change is mergeable after normal checks.

Security architecture risk: Low · up to 76779

The reviewed changes preserve administrator and tenant visibility controls. No introduced security vulnerability was established. The main operational consideration is keeping the status readers and rollup database objects compatible during rollback.

Retained concerns
No architecture-level concerns identified.

Security review details

Security Blast Radius

• observed — The affected output is usage telemetry on the existing administrator-or-tenant-administrator status endpoint. Proven server administrators receive the global view; tenant administrators receive a projection keyed by their authenticated HomeScope.

Trust Boundaries and Controls

• observed — The new aggregation functions do not replace route authorization or caller-specific projection. Tenant ownership continues to be resolved through the same current key-to-tenant relationship used by the base raw query; historical reattribution through mapping changes is therefore a pre-existing behavior, not an introduced boundary bypass.

Resilience and Maintainability Implications

• observed — Status inherits the rollup's insert-only accounting: manual raw-log deletion does not remove the corresponding rolled-up counts. Documentation specifies stopping the daemon and rebuilding the rollup transactionally after such deletion. This affects interpretation and recovery of telemetry, not tenant authorization.

Pre-merge checks: 4 · 1

Failed checks: 1 warning

Check name	Status	Explanation	Resolution
Docstring Coverage		Docstring coverage is 69.57% which is insufficient. The required threshold is 80.00%. Docstring coverage is scoped to functions touched by this diff with cyclomatic complexity of at least 2. Documenta…	Write docstrings for the functions missing them to satisfy the coverage threshold.

Passed checks: 4 passed

Check name	Status	Explanation
Description Check		Check skipped - CodeRabbit’s high-level summary is enabled.
Title check		The title clearly and concisely describes the main change: server and tenant llm_24h status views now read from the hourly rollup plus the edge hour.
Linked Issues check		Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check		Check skipped because no linked issues were found for this pull request.

Full details: Docstring Coverage

Explanation

Docstring coverage is 69.57% which is insufficient. The required threshold is 80.00%. Docstring coverage is scoped to functions touched by this diff with cyclomatic complexity of at least 2. Documentation-only edits and deletions within surviving functions are included; unchanged diff context and fully deleted functions are excluded. Analyzed 23 functions across 10 files. (3 skipped: 3 unsupported.)

Resolution

Write docstrings for the functions missing them to satisfy the coverage threshold.

Finishing Touches

Generate docstrings

• Commit to this branch
• Create a new PR

Generate unit tests (beta)

• Commit to this branch
• Create a new PR

• Autofix · Keep fixing CodeRabbit findings and required CI, and resolving merge conflicts

CodeRabbit Verify

• Run CodeRabbit Verify to test the changes in this pull request.

Recent review info

Run configuration

• Source mode: Auto
• Repository: Unavailable
• Branch: Unavailable
• File: No configuration file from this repository applied
• Commit: Unavailable
• Layers: defaults
• Review profile: CHILL
• Plan: Advanced
• Run ID: 98e82b44-0562-4b32-b6e0-b38d54ce0507

Commits

Reviewing files that changed from the base of the PR and between 14b9963 and 7677938.

Files selected for processing: 13

• docs/architecture.md
• docs/operations.md
• go/internal/handler/status.go
• go/internal/handler/status_llm24h_golden_integration_test.go
• go/internal/handler/status_llm24h_parity_integration_test.go
• go/internal/handler/status_llm24h_plan_integration_test.go
• go/internal/handler/status_llm24h_ref_integration_test.go
• go/internal/handler/status_tenant.go
• go/internal/handler/testdata/llm24h_golden.json
• go/internal/llmusage/groups.go
• go/internal/llmusage/window.go
• go/internal/llmusage/window_integration_test.go
• go/internal/promptguard/promptguard_callsite_test.go

Included review availability: This review used your included allowance. Your plan provides up to 10 included reviews per hour; 9 remain after this review.

[Copilot]

Note

Copilot was unable to complete this review at the selected tier due to model policy or plan restrictions.

🟢 Approval recommended

The change replaces the 24h status aggregation with rollup-plus-edge-hour readers and includes extensive parity/golden/plan integration tests and documentation updates, with no unresolved issues noted beyond a minor performance nit.

No open issues 🎉

What changed in this PR

This pull request updates the /api/status llm_24h aggregation (server-wide and per-tenant) to compute results from the hourly rollup table (context_llm_usage_hourly) plus the raw “edge hour” of context_llm_log, preserving output parity with the legacy 24-hour raw scan while significantly reducing per-tick query cost and making tie ordering deterministic.

Changes:

• Add new rollup-backed readers in internal/llmusage (Groups, TenantGroups) to aggregate (backend, pipeline) over a 24h window using rollup + bounded raw edge-hour rows.
• Switch status collection paths (queryLLM24h and per-tenant rollup generation) to use the new readers, including anchored time handling for tests.
• Add/refresh integration tests (golden/parity/plan/reference) and update docs (operations, architecture) to reflect the new read path and rollback coupling.

File	Summary
go/​internal/​promptguard/​promptguard_callsite_test.go	Update promptguard callsite census coverage for the status pipeline passthrough.
go/​internal/​llmusage/​window.go	Package-level documentation updates for the window/reader functionality.
go/​internal/​llmusage/​window_integration_test.go	Adjust integration test helpers for edge-hour row membership/counting.
go/​internal/​llmusage/​groups.go	Implement rollup + edge-hour readers for server and tenant grouped usage (note: one nit raised about avoiding per-row allocation in scan destination construction in readGroups).
go/​internal/​handler/​testdata/​llm24h_golden.json	Add/refresh golden fixture for llm_24h outputs.
go/​internal/​handler/​status.go	Switch server llm_24h to llmusage.Groups and add mapping/anchoring support.
go/​internal/​handler/​status_tenant.go	Switch per-tenant llm_24h generation to llmusage.TenantGroups.
go/​internal/​handler/​status_llm24h_ref_integration_test.go	Add raw SQL reference helpers for parity/golden comparisons.
go/​internal/​handler/​status_llm24h_plan_integration_test.go	Add plan assertions to enforce bounded raw-edge reads and rollup index access paths.
go/​internal/​handler/​status_llm24h_parity_integration_test.go	Add randomized parity test comparing new readers vs reference queries.
go/​internal/​handler/​status_llm24h_golden_integration_test.go	Add golden/completeness/consumer-exclusion/long-name-cut integration tests.
docs/​operations.md	Document operational implications of status reading rollup + edge hour (including rollback coupling).
docs/​architecture.md	Update architecture documentation to reflect the new rollup-backed status reader behavior.

_{Review effort: Balanced}