fix(billing): classify permanent callback conflicts

[icecrasher321]

Summary

• Return distinct non-retryable conflicts when a frozen billing period has elapsed or the usage ledger references a deleted user. Keep transient failures retryable and preserve compatibility with older markerless clients.
• Preserve historical usage attribution and report that explicit reconciliation is required instead of repeatedly returning server errors.
• Companion: Copilot retry handling. Deploy Copilot's handling first so these charges remain durable and stop replaying.

Type of Change

• Bug fix

Testing

• 67 billing tests pass, including real HTTP and PostgreSQL integration across all three billing protocols, actual missing-user constraint failures, temporary failure recovery, duplicate recording, and stale-claim/cumulative-update interleavings. Subscription and payment-provider behavior uses fixtures.
• Full lint, all 45 repository audits, block-registry and docs checks, app TypeScript check, and generated billing/trace contract checks pass.
• The integration test also fails with the original elapsed-period classification and passes with the fix.

Checklist

• Code follows project style guidelines
• Self-reviewed my changes
• Tests added/updated and passing
• No new warnings introduced
• I confirm that I have read and agree to the terms outlined in the Contributor License Agreement (CLA)

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

1 Skipped Deployment

Project	Deployment	Actions	Updated
docs	Skipped		Sep 7, 2026 9:09pm UTC

[greptile-apps]

Greptile Summary

This PR distinguishes permanent billing callback conflicts from transient settlement failures while retaining compatibility with markerless clients.

• Returns non-retryable reconciliation outcomes for elapsed frozen billing periods and deleted billing users.
• Keeps overlapping or future period mismatches and other settlement failures retryable.
• Extends generated billing and tracing constants for the new outcomes.
• Adds unit and cross-service integration coverage for replay, attribution preservation, missing users, and transient recovery.

Confidence Score: 5/5

The PR appears safe to merge, with the new permanent-conflict behavior aligned with frozen attribution, cycle-close handling, and protocol compatibility.

No actionable failures remain: permanent conditions receive explicit reconciliation outcomes, transient failures remain retryable, markerless clients retain their established semantics, and the affected paths have focused unit and integration coverage.

Important Files Changed

Filename	Overview
apps/sim/app/api/billing/update-cost/route.ts	Classifies elapsed-period and deleted-user failures as protocol-aware, non-retryable reconciliation conflicts while preserving markerless behavior.
apps/sim/lib/billing/threshold-billing.ts	Adds the permanent elapsed-period settlement code and distinguishes it from retryable overlapping or future mismatches.
apps/sim/app/api/billing/update-cost/route.test.ts	Covers reconciliation responses across all protocols, exact PostgreSQL constraint matching, and markerless compatibility.
apps/sim/app/api/billing/update-cost/replay.integration.test.ts	Adds an environment-gated PostgreSQL and Go integration test for durable replay and transient recovery.
apps/sim/lib/copilot/generated/billing-protocol-v1.ts	Adds stable callback outcome codes and messages for elapsed periods and deleted users.

Flowchart

%%{init: {'theme': 'neutral'}}%%
flowchart TD
    A[Billing callback] --> B[Record cumulative usage]
    B -->|Missing billing user FK| C{Protocol marker present?}
    B -->|Recorded or duplicate| D[Reconcile threshold settlement]
    D -->|Frozen period elapsed| C
    D -->|Transient settlement failure| E[503 retryable]
    D -->|Settlement succeeds| F{New cumulative cost?}
    C -->|Yes| G[409 reconciliation required]
    C -->|No, markerless legacy| H[Preserve legacy error behavior]
    F -->|Yes| I[200 billed]
    F -->|No| J[409 duplicate event]

Loading

_{Reviews (1): Last reviewed commit: "fix(billing): classify permanent callbac..." | Re-trigger Greptile}

[cubic-dev-ai]

No issues found across 7 files

Confidence score: 5/5

• Automated review surfaced no issues in the provided summaries.
• No files require special attention.

_{Re-trigger cubic}