fix(cost-insights): decouple usage rollups and gate plan suggestions

[jeanduplessis]

Summary

Make AI usage accounting resilient under contention and restrict Coding Plan suggestions to eligible personal usage.

Why this change is needed

Synchronous updates to hot microdollar_usage_daily rows caused usage transactions to wait on the same index tuple, exhaust the primary database pool, and fail unrelated routes. One pathological usage transaction also remained idle while holding locks for roughly 80 minutes.

Coding Plan suggestions could also be generated for organization owners and unsupported provider/model combinations.

How this is addressed

• Keep authoritative raw usage, metadata, required balance effects, and durable repair enqueueing atomic.
• Remove daily-rollup mutation and canonical reconstruction from the gateway request lifecycle.
• Rebuild daily aggregates asynchronously from authoritative usage with bounded transactions, retry state, claim fencing, signed-cost support, and UTC day boundaries.
• Apply a transaction-local 60-second idle timeout as the first statement in the authoritative usage transaction.
• Process and report daily-rollup repair work through the existing hourly maintenance path.
• Restrict Coding Plan suggestions to personal owners with eligible variable spend on a covered provider/model.
• Add generated schema and migration artifacts for durable daily-rollup repair records.

Human Verification

• Focused AI-gateway usage suites passed: 3 suites, 51 tests.
• Database schema consistency test passed.
• Local review verified the authoritative transaction no longer mutates microdollar_usage_daily and applies the idle timeout before lock acquisition or usage writes.

Reviewer Notes

Human Reviewer Flags

• Daily aggregates are eventually consistent; consumers must tolerate repair lag.
• The repair queue stores one row per non-zero usage, while the hourly sweep currently claims at most 20 keys. Review expected production enqueue/drain rates and backlog monitoring before rollout.
• Seed data still contains organization-owned and below-threshold Coding Plan suggestion fixtures that do not match the new runtime eligibility rules; confirm whether they intentionally represent historical/UI states.

Code Reviewer Agent

Code Reviewer Notes

• Canonical replacement makes retries idempotent and avoids additive double counting.
• Repair completion is fenced by claim token and exact user/organization/day scope.
• The 60-second idle timeout is transaction-local and does not limit statement execution, lock waits, or total transaction duration.
• Existing post-commit Cost Insights timeouts remain unchanged.

[kilo-code-bot]

Code Review Summary

Status: No Issues Found | Recommendation: Merge

Executive Summary

Since the last review, this branch was rebased onto a newer main; no new authored changes were introduced. The only file-level delta is the migration file being renumbered from 0186_clammy_zarda.sql to 0187_wide_inertia.sql (content identical, confirmed via diff), plus regenerated Drizzle snapshot/journal metadata reflecting that rebase. The decoupled rollup-repair pipeline and Coding Plan eligibility gating remain unchanged and still check out.

Files Reviewed (15 files)

• apps/web/src/app/api/cron/cost-insights-hourly/route.test.ts
• apps/web/src/app/api/cron/cost-insights-hourly/route.ts
• apps/web/src/lib/ai-gateway/processUsage.test.ts
• apps/web/src/lib/ai-gateway/processUsage.ts
• apps/web/src/lib/ai-gateway/usage-daily-rollup-repairs.test.ts
• apps/web/src/lib/ai-gateway/usage-daily-rollup-repairs.ts
• apps/web/src/lib/coding-plans/index.test.ts
• apps/web/src/lib/coding-plans/pricing.ts
• apps/web/src/lib/cost-insights/evaluation.ts
• apps/web/src/lib/cost-insights/jobs.ts
• apps/web/src/lib/cost-insights/suggestion-eligibility.test.ts
• apps/web/src/lib/cost-insights/suggestion-eligibility.ts
• dev/seed/cost-insights/spend-evidence.ts
• packages/db/src/migrations/0187_wide_inertia.sql
• packages/db/src/schema.ts

Generated migration snapshot/journal files were excluded per review scope.

Previous Review Summary (commit c4b3d25)

Current summary above is authoritative. Previous snapshots are kept for context only.

Previous review (commit c4b3d25)

Status: No Issues Found | Recommendation: Merge

Executive Summary

Reviewed the decoupling of daily usage rollups into a durable, claim-fenced async repair pipeline and the restriction of Coding Plan suggestions to eligible personal usage; the transaction-local idle timeout placement, claim/fencing/advisory-lock logic, UTC day bucketing, and eligibility gating all check out against the changed code with high confidence.

Files Reviewed (15 files)

• apps/web/src/app/api/cron/cost-insights-hourly/route.test.ts
• apps/web/src/app/api/cron/cost-insights-hourly/route.ts
• apps/web/src/lib/ai-gateway/processUsage.test.ts
• apps/web/src/lib/ai-gateway/processUsage.ts
• apps/web/src/lib/ai-gateway/usage-daily-rollup-repairs.test.ts
• apps/web/src/lib/ai-gateway/usage-daily-rollup-repairs.ts
• apps/web/src/lib/coding-plans/index.test.ts
• apps/web/src/lib/coding-plans/pricing.ts
• apps/web/src/lib/cost-insights/evaluation.ts
• apps/web/src/lib/cost-insights/jobs.ts
• apps/web/src/lib/cost-insights/suggestion-eligibility.test.ts
• apps/web/src/lib/cost-insights/suggestion-eligibility.ts
• dev/seed/cost-insights/spend-evidence.ts
• packages/db/src/migrations/0186_clammy_zarda.sql
• packages/db/src/schema.ts

Generated migration snapshot/journal files were excluded per review scope.

---

_{Reviewed by claude-sonnet-5 · Input: 48 · Output: 14K · Cached: 1.2M}

_{Review guidance: REVIEW.md from base branch main}