(CODUX-228) Expose trustworthy cost analytics rollups

[numnx]

🧩 Task: Expose trustworthy cost analytics rollups

Automated task PR opened by Code UX for T01.

📋 Summary

Sprint: Sprint 228 · Stats Cost analytics · Task: T01

Add a trustworthy, accessible Cost analysis mode to Stats that exposes provenance-aware spend, averages, token and spend allocation, canonical per-sprint and per-task detail, model and execution-purpose breakdowns, and resilient navigation and refresh states across every existing Stats time range.

🤖 Model & Provider

Provider	Codex CLI
Model	gpt-5.6-sol

⏱️ Timing

Started	2026-07-14 00:08:21 UTC
Finished	2026-07-14 00:19:11 UTC
Duration	10m 50s

📊 Token Usage

Metric	Value
Input tokens	171,959
Cached input tokens	5,181,440
Output tokens	25,125
Total tokens	5,378,524
Invocations	1
Tool calls	51
Active time	10m 16s

Included usage estimate (subscription/local login): $4.20

✅ QA Review

⏳ QA review runs after this PR is opened. Check the task card in the dashboard for the outcome once it lands.

📝 Full Task Prompt

## Objective
Make the existing project Stats API a trustworthy source for detailed Cost analytics without introducing a second endpoint or persistence table.

## Scope
- `src/contracts/app-types.ts`: `ExecutionUsageTotals`, new `ExecutionCostCoverage` and `ProjectCostAnalyticsSummary` contracts, and `ProjectExecutionStatsSnapshot.costAnalytics`
- `src/repositories/execution/project-stats-aggregation.ts`: `usageFields`, `UsageAggregationRow`, `mapAggregatedUsage`, `mergeAggregatedUsage`, and `accumulateBucketUsage`
- `src/repositories/execution/stats-buckets.ts`: `createEmptyUsageTotals`
- `src/repositories/execution/project-stats-snapshot-query.ts`: project, bucket, entity, and canonical sprint cost aggregation
- Verify existing wiring through `src/repositories/execution-repository.ts`, `src/app/lifecycle/dashboard-snapshot-cache.ts`, `src/app/lifecycle/dashboard-lifecycle-service.ts`, and `src/server/runtime-routes.ts`
- `tests/backend/repositories/execution/project-stats-aggregation.test.ts`
- `tests/backend/repositories/execution/project-stats-snapshot-query.test.ts`
- `tests/backend/repositories/execution-repository-model-pricing.test.ts`
- `tests/backend/server/dashboard-project-api.test.ts`
- `docs/architecture/usage-telemetry-and-stats.md`

## Implementation Requirements
1. Add an additive cost-provenance contract that records configured-pricing invocation count, provider-reported-cost invocation count, unpriced invocation count, and the provider-reported USD amount actually used as fallback; keep new fields optional for compatibility with older snapshots and test fixtures, but always populate them from `getProjectStatsSnapshot`.
2. Extend aggregation so configured model pricing remains authoritative, provider-reported `raw_usage_json.cost` remains the fallback, valid reported zero-cost rows count as covered, and invocations with neither source count as unpriced; merge these fields through project, bucket, task, provider, purpose, and model totals without exposing raw usage payloads.
3. Add `costAnalytics.sprints` keyed by canonical `sprint_id` so multiple sprint runs roll up into one conceptual sprint while preserving the existing sprint-run-oriented `sprints` array and its consumers.
4. Preserve current time-window validation, project scoping, pricing resolver caching, chart-series behavior, and existing input/output/cached pricing formulas; derive the new read model from existing columns and settings, with no database migration.
5. Add focused repository and REST integration tests for configured pricing, provider-reported fallback, legitimate zero cost, missing pricing, mixed coverage, multiple runs of one sprint, per-task/per-purpose/per-model rollups, and an empty window.
6. Document cost provenance, canonical Cost sprint aggregation, current-pricing recalculation semantics, and the distinction between zero-cost and unpriced telemetry.

## Constraints
- Do not add a Cost-specific API route, table, stored credential, or raw provider payload to the response.
- Do not change existing Stats query parameters, range limits, route error behavior, or the meaning of the current `sprints` ledger.
- Keep aggregation bounded to the existing project/range query and indexed `provider_invocations` columns; avoid per-entity or per-bucket follow-up queries.
- Preserve provider/model pricing precedence and cached-input pricing behavior used by existing Stats and PR billing consumers.

## Verification
- Run `pnpm exec vitest run tests/backend/repositories/execution/project-stats-aggregation.test.ts tests/backend/repositories/execution/project-stats-snapshot-query.test.ts tests/backend/repositories/execution-repository-model-pricing.test.ts tests/backend/server/dashboard-project-api.test.ts`.
- Run `pnpm run lint` and `pnpm run build`.
- Confirm the REST snapshot distinguishes fully priced, provider-reported, partially unpriced, fully unpriced, legitimate zero-cost, and no-usage windows, and returns one Cost row for multiple runs of the same sprint.

🌿 Branch Info

Base: feature/CODUX-228-stats-cost-analytics
Head: task/feature-codux-22-t01-codex-552afbfb-mrjw7tah

---

🤖 Generated by Code UX