[GottZ]

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

What this changes

• New leaf package internal/llmusage (imports only the pgxdb handle atoms; depguard rule llmusage-leaf pins that): Window(ctx, q, Spec{Now, Span, APIKeyIDs, Locality}) reads one rolling window as hourly rollup from the first full UTC hour after now − span plus the raw context_llm_log rows of that first, partial hour — the exact semantics of the raw created_at > now() - interval queries it replaces, with at most one hour of raw rows per window. It also returns the earliest relief of each figure (oldest counted row + span), microsecond-exact.
• backends.QuotaAccountant.spend reads its three figures (24 h calls, 24 h external cost, 30-day rolling external cost) through llmusage.Window instead of a 30-day scan over the hypertable. The filter stays the tenant's knowledge keys (api_key_id): a /v1 consumer row never counts here (K17, B-06-18) — consumer traffic cannot exhaust daily_calls or the cost budget and lock a tenant's people out of /api/query and the web chat. Relief timestamps are stored on the tenant state for W06-14 (no reader yet).
• Docs: docs/multi-tenancy.md (spend source, asymmetry), docs/operations.md (Migration 159 rollback now coupled to the reader), docs/architecture.md.

Behaviour changes (intended)

• Spend figures are byte-equal to the old query for the same clock (parity property below); the windows now end at the accountant's clock instead of the database's now() (same host, same clock in production).
• Three index probes per tenant refresh (one per window) instead of one 30-day scan.

Deviations from design/06 §4.7, with reasons

• The raw edge always ends at the next full hour, also when since lies exactly on one: the bucket starting at since holds a row stamped exactly at since, which the strict lower bound excludes; the design formula counted such a row twice (90 parity deviations with it, 0 with the fix).
• Keys are probed one by one (LATERAL … OFFSET 0) instead of api_key_id = ANY($1): with = ANY the planner preferred the time-leading indexes (uq_llm_usage_hourly, the log's created_at index) and read every tenant's rows in the range — under the generic plan the whole instance's edge hour. The locality condition sits in the aggregates' FILTER so both renderings share one access path. Pinned by TestQuotaSpendPlan under the custom and the forced-generic plan.
• Relief is exact (oldest raw row of the oldest counted rollup hour, one bounded lookup) rather than bucket_start: the bucket variant reports relief too early (11:00 for a row at 11:05:00.000007); a safe conservative variant would have been bucket_start + 1 h.

Consumers of the changed contracts

Changed symbol	Callers / readers	Covered by
QuotaAccountant.spend (signature, now fills tenantState incl. relief)	refresh (quota.go)	TestQuotaAccountant_* (backends 80 → 83), TestChatQuota, TestSynthesizeQuota, handler status/quota suites
NewQuotaAccountant(q quotaDB, …) (needs Querier + Rower)	cmd/ctxd, tests	compile; existing callers pass *pgxpool.Pool
context_llm_usage_hourly (first reader)	llmusage.Window	TestWindowParity (500 seeds vs the old raw SQL), TestWindowBounds (unit, hour-exact edges), TestQuotaSpendPlan
.golangci.yml depguard	CI lint	golangci-lint run 0

Overlap search

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

Cost

Per policy tenant every 30 s: three statements, each ≤ 1 h of raw rows through idx_llm_log_apikey plus the rollup through idx_llm_usage_key; measured in TestQuotaSpendPlan: raw rows touched 3–5 (base: 1 441, with no upper bound on created_at and no rollup). Planner edge: on a rollup of a few dozen tenants the custom plan may still pick the time-leading uq_llm_usage_hourly for the 30-day window (≈ 1.5× the probe's cost); from ~100 tenants on it moves to idx_llm_usage_key. Candidate for later: INCLUDE columns on idx_llm_usage_key, one batched statement over all tenants.

Verification

Gates, each red on 43041709 first: (a) existing quota suites green before and after (backends 80/83, chat 1, llm 4, handler 52); (b) parity property llmusage.Window vs the old spend SQL over 500 random seeds with rows around both window edges — 425 deviations without the edge rows, 90 with the design's ceilHour, 0 final; (c) EXPLAIN under custom and generic plan: raw rows 1 441 → 3–5, rollup via idx_llm_usage_key; (d) asymmetry pin: a spend-union variant (OR consumer_id = ANY) counts 5 consumer calls and the gate refuses on daily_calls, the shipped code counts 0 and lets the tenant through, the control with 5 knowledge-key calls refuses; (e) relief with a fixed clock: compile error on base, bucket_start variant 11:00 vs exact 11:05:00.000007.

Suites on the head: go build ./..., go vet -tags=integration ./..., golangci-lint run with and without --build-tags=integration (0), go test -short -race ./... (65 ok), deadcode.sh + deadcode.sh testonly (ok; the new package is reached from spend), integration -p 1 -race for internal/llmusage + internal/backends, and -run 'Quota|Status|LLMLog' for internal/chat, internal/llm, internal/handler. Independent review by a fresh agent during the build: 4 minor + 5 nit, all fixed or documented in the wave report.

Not verified

• Clock skew between the daemon and the database shifts the windows by that skew (the old query used the database clock); in production both run on one host.
• The planner edge above is observed at ~30 synthetic tenants, not measured on the live rollup.

🤖 Generated with Claude Code

Summary by CodeRabbit

• Quota Improvements

  • Tenant quota calculations now use rolling 24-hour and 30-day windows for attributed calls and provider-reported costs. Consumer-only activity is excluded from tenant quota totals.
  • Quota status now includes the earliest time counted calls or costs are expected to leave each window.
  • Usage totals combine hourly summaries with raw records from the current partial hour, preserving accurate rolling-window figures.

• Documentation

  • Updated quota and operations guidance to explain usage windows, deleted-log behavior, and migration rollback considerations.

[coderabbitai]

No actionable comments were generated in the recent review.

Walkthrough

The change adds a reader that combines hourly usage rollups with raw rows from the partial hour. Tenant quota accounting now uses this reader for rolling call and cost totals, and stores earliest-relief timestamps. Tests and documentation cover the reader and its quota integration.

Changes: Tenant usage accounting

Layer / File(s)	Summary
Usage window calculation go/internal/llmusage/window.go, go/internal/llmusage/window_test.go, go/internal/llmusage/window_integration_test.go, .golangci.yml	The new llmusage package calculates rolling totals and relief times from hourly rollups and raw rows in the partial hour. Unit and integration tests cover window bounds, totals, relief times, locality filters, and parity with raw-row queries. The package receives a depguard rule with a restricted import allowlist.
Quota accounting and verification go/internal/backends/quota.go, go/internal/backends/export_test.go, go/internal/backends/quota_integration_test.go, go/internal/backends/quota_plan_integration_test.go, docs/architecture.md, docs/multi-tenancy.md, docs/operations.md	The quota accountant uses three windows for daily calls, daily external cost, and monthly external cost, and stores their relief times. Tests cover consumer-row exclusion, quota totals, and query plans. The documentation describes the rollup reader, quota behavior, and downgrade guidance.

Estimated code review effort: 4 (Complex) | ~45 minutes

Change: Refactor

Sequence Diagram(s)

sequenceDiagram
  participant QuotaAccountant
  participant llmusage.Window
  participant PostgreSQL
  participant tenantState
  QuotaAccountant->>llmusage.Window: request call and cost windows
  llmusage.Window->>PostgreSQL: query hourly rollups and partial-hour log rows
  PostgreSQL-->>llmusage.Window: return totals and oldest qualifying timestamps
  llmusage.Window-->>QuotaAccountant: return totals and relief times
  QuotaAccountant->>tenantState: store spend totals and relief times

Loading

Possibly related PRs

• GottZ/ctx#72: Adds the exclusive consumer_id and api_key_id caller identity model used to distinguish consumer rows from tenant-key rows.
• GottZ/ctx#73: Adds the hourly rollup and trigger that this change reads alongside raw rows from the partial hour.

Suggested reviewers: w4-nerf

Merge Risk: Minimal · up to e0a39

Tenant call and cost quotas now read from hourly rollups plus the partial-hour raw rows, with tests for window boundaries, consumer-row exclusion and query plans. No concrete merge-blocking risk was identified. The one disclosed caveat is that quota windows now end at the daemon clock rather than the database clock.

Security architecture risk: Low · up to e0a39

Tenant attribution and safe publication of refreshed limits are preserved. The main added risk is operational: an incomplete application and database rollback can weaken spending-limit enforcement.

Retained concerns
No architecture-level concerns identified.

Security review details

Security Blast Radius

• inferred — Failure or corruption of the shared rollup can affect spending-limit accuracy for every configured policy tenant using that database. This is a shared accounting dependency, not a new public authority grant; the identified disruptive rollback operations require database administrative access.

Trust Boundaries and Controls

• observed — The production caller supplies tenant-resolved knowledge-key IDs rather than accepting a consumer identity as an accounting substitute. SQL parameters carry key lists and locality values. Consumer-only rows cannot satisfy the reader's api_key_id predicates, preventing consumer traffic from exhausting these knowledge-key quotas through this path.

Resilience and Maintainability Implications

• observed — Partial query failure or cancellation propagates before a new generation is published, retaining the previous policy and spend snapshot. Background refresh remains single-flight and time-bounded. These mechanisms contain transient failures, but do not detect a disabled rollup trigger because stale aggregate reads can still succeed. Cold-cache fail-open behavior is unchanged from the base.

Hardening Proposals

• proposed — A deployment or maintenance check could validate reader/schema compatibility and continued rollup-trigger operation before schema teardown or application restart. This would reinforce the documented rollback requirement; it is a hardening proposal, not an observed vulnerability.

Pre-merge checks: 4 · 1

Failed checks: 1 warning

Check name	Status	Explanation	Resolution
Docstring Coverage		Docstring coverage is 53.33% 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: tenant spend now reads the hourly rollup plus the partial 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 53.33% 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 30 functions across 7 files. (4 skipped: 4 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: 432e238d-f63a-4d36-902e-b67295bb5194

Commits

Reviewing files that changed from the base of the PR and between 4304170 and e0a3906.

Files selected for processing: 11

• .golangci.yml
• docs/architecture.md
• docs/multi-tenancy.md
• docs/operations.md
• go/internal/backends/export_test.go
• go/internal/backends/quota.go
• go/internal/backends/quota_integration_test.go
• go/internal/backends/quota_plan_integration_test.go
• go/internal/llmusage/window.go
• go/internal/llmusage/window_integration_test.go
• go/internal/llmusage/window_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.

🟡 Changes recommended

The change still has an active moderate issue in go/internal/llmusage/window_integration_test.go where tenant key membership is checked via substring matching, risking false positives and making the edge coverage assertion unreliable until replaced with exact set membership.

1 open issue

• edgeRows uses substring matching for tenant key membership · New

What changed in this PR

This PR introduces a new rollup-backed LLM usage window reader (internal/llmusage) and refactors tenant quota spend accounting to use hourly rollups plus a bounded “edge hour” of raw context_llm_log rows, aiming to preserve prior window semantics while eliminating per-tenant 30‑day raw scans. It also updates related integration/unit tests, documentation, and depguard rules.

Changes:

• Add internal/llmusage.Window(...) to compute rolling spend windows from context_llm_usage_hourly plus at most one partial-hour slice of raw logs, including relief timestamps.
• Refactor internal/backends.QuotaAccountant spend computation to use llmusage.Window for 24h calls, 24h external cost, and 30d external cost windows (tenant knowledge keys only).
• Add/adjust plan-parity, bounds, and integration tests; update docs and .golangci.yml depguard configuration.

File	Review Notes
go/​internal/​llmusage/​window.go	Reviewed
go/​internal/​llmusage/​window_test.go	Reviewed
go/​internal/​llmusage/​window_integration_test.go	Reviewed — Moderate: edgeRows uses substring matching via strings.Contains(strings.Join(keys, \",\"), *r.key) which can produce false positives; replace with exact set-membership.
go/​internal/​backends/​quota.go	Reviewed
go/​internal/​backends/​quota_plan_integration_test.go	Reviewed — Moderate: walkPlan() undercounts touched rows because it multiplies only Actual Rows by Actual Loops but not Rows Removed by Filter / Rows Removed by Index Recheck (JSON EXPLAIN reports per-loop averages); can let plan regressions slip past the ceiling check.
go/​internal/​backends/​quota_integration_test.go	Reviewed
go/​internal/​backends/​export_test.go	Reviewed
docs/​operations.md	Reviewed
docs/​multi-tenancy.md	Reviewed
docs/​architecture.md	Reviewed
.golangci.yml	Reviewed

_{Review effort: Balanced}

[GottZ]

The keys are full 36-character UUIDs and the joined list is comma-separated, so a substring match across a boundary would need a comma inside a UUID — there is no false positive today. Agreed that an exact set check says what it means; the next wave (W06-5, status rollups on this package) carries the one-line change rather than a comment-only CI round here.