feat(billing): enforce prepaid usage access(Phase 8 Enforcement )

[law-chain-hot]

Summary

Adds the minimum prepaid access-control layer on top of the existing Usage, Rating, Wallet, and payment pipeline.

Create / Start / Proxy auto-start / hot Resize
                    |
                    v
       Redis organization admission lock
                    |
                    v
 wallet - unsettled usage - safety buffer
          |                     |
      has access             no access
          |                     |
   existing Box flow          HTTP 402

Wallet debit event ------> immediate recheck
Every-minute sweep ------> stop unfunded running Boxes

Changes

• Derives hasAccess, available balance, unsettled usage, and a two-minute safety buffer without adding a business table.
• Covers open/closed periods, archived-but-unrated periods, and rated-but-undebited periods exactly once.
• Gates Create, Start, proxy auto-start, and running resource increases under a token-safe Redis organization lock.
• Rechecks after committed wallet debits and runs a globally locked, batched one-minute fallback sweep.
• Stops Boxes through the existing persisted desired-state flow; top-ups do not automatically restart them.
• Adds query indexes only, exposes access data in the Billing overview, and keeps enforcement disabled by default for staged rollout.
• Adds a loopback-only local-infra E2E that restores the wallet and removes its test Box.

Verification

• 117 API unit tests
• 11 PostgreSQL concurrency and recovery tests
• 39 Dashboard tests
• 12 Stripe Sandbox configuration tests
• Billing-scoped ESLint
• API and Dashboard production builds
• local-infra E2E: funded Create succeeds; zero balance blocks Create, Start, and proxy auto-start with 402; minute sweep stops the running Box; cleanup verified

Rollout

Set BILLING_ENFORCEMENT_ENABLED=true per stage after migrations are applied. The default is false.

This first version intentionally has no grace states, reservations, automatic restart, or destructive storage cleanup.

Dev E2E Result

PR1-PR8 aggregate Dev validation (732608da):

Stripe test payment
  -> webhook / reconcile
  -> wallet credit / refund                    [PASS]

Real Box lifecycle
  -> usage archive -> rating -> wallet debit   [PASS]

PR8 zero-balance enforcement
  -> Create / Start / proxy auto-start = 402   [PASS]
  -> running Box -> minute sweep -> stopped    [PASS]

Deployment smoke
  -> API health -> create Box -> exec bash
  -> delete Box                                [PASS]

Final database state
  -> pending top-ups          0
  -> negative wallets         0
  -> unrated periods          0
  -> unsettled periods        0
  -> leaked test Boxes        0

Billing behavior passed. The Ops release was not marked promotable because the unrelated Otel Collector image build hit proxy.golang.org download unexpected EOF; API revision 189 completed rollout and the manual smoke passed.

[coderabbitai]

Important

Review skipped

Draft detected.

Please check the settings in the CodeRabbit UI or the .coderabbit.yaml file in this repository. To trigger a single review, invoke the @coderabbitai review command.

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro Plus

Run ID: 01e0be21-1cfe-40fa-a29a-103d8dfa7dbb

You can disable this status message by setting the reviews.review_status to false in the CodeRabbit configuration file.

Use the checkbox below for a quick retry:

• 🔍 Trigger review

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}