Milestone 4.P.4 — Query, Usage & Cost Data PlatformCopy Anchor Link

Status: In progress — ledger and hard-cap foundations exist; read and reconciliation contracts remain. Outcome: Dashboard reads are bounded, explainable, tenant-scoped, and explicit about usage freshness and cost certainty. Track: Track P — Operator Readiness, Evidence & Control Plane Dependencies: 4.P.2; 4.P.3 Estimated effort: 4 weeks Gate: post-P.3 data-platform gate

Query and lifecycle contractCopy Anchor Link

The typed query grammar defines fields, operators, time ranges, facets, cursor pagination, query budgets, and saved-view serialization. High-cardinality IDs remain event fields rather than metric labels. Usage facts are immutable and tenant-scoped; billing retention is a documented carve-out from org deletion. Query errors, unavailable dependencies, and bounded truncation are visible states, not empty-success responses.

Estimate versus actual contractCopy Anchor Link

At enqueue, freeze estimated_cost_cents and rate_card_version. Only a provider invoice or other explicitly named authoritative source may produce actual_cost_cents; reconciliation must retain source, version, timestamp, currency, and adjustment lineage. Until that source exists, the UI and API must label estimates as advisory, omit or mark actuals unavailable, and expose estimate-to-actual drift as deferred—not silently equate estimates with actuals. Spend-cap decisions are a separate enforcement record and may fail closed even while reconciliation is pending.

ResidualsCopy Anchor Link

The baseline records CH-to-Postgres spent rollup and hard-cap denial foundations. Invoice reconciliation, drift alerts, full saved-view round-trip, autocomplete, and the complete operator browser matrix remain open; issue #859 is the stated blocker for estimate-to-actual reconciliation. D2–D6 must preserve these labels.

Verification gateCopy Anchor Link

Run tenant-scoped query contract fixtures, EXPLAIN samples, duplicate/retry billing tests, rate-card replay, hard-cap denial, freshness/truncation checks, and estimate/actual separation tests. P6 must parse responses at runtime and prove cache isolation across users and tenants.

Rollout and rollbackCopy Anchor Link

Trigger: query scope leak, hard-cap error, reconciliation drift, or SLO breach. Reversal: disable hard enforcement only through an approved alert-only control, preserve immutable facts and versions, and reconcile outstanding decisions before re-enabling.

Findings addressedCopy Anchor Link

F4-005.

Exit checklistCopy Anchor Link

• Every query shape requires server-supplied org_id and bounded pagination.
• Read DTOs expose freshness, completeness, truncation, lag, and source versions.
• Estimates and actuals are separate fields with authoritative-source provenance.
• Reconciliation and drift residuals are labeled for D2–D6.
• Cache isolation and cross-tenant query negatives pass through P6.