feat(usage): add box usage metering ledger

[law-chain-hot]

Summary

• add box_usage_period and box_usage_period_archive as the usage ledger
• convert Box lifecycle events into running and stopped usage periods
• use Redis locks to serialize per-Box updates and deduplicate cron execution across API replicas
• roll open periods every 24 hours and archive closed periods every 5 seconds
• expose a read-only Metering API and inspection page for local verification
• keep rating, wallet, payment, and invoice behavior out of PR1

Architecture

BoxRepository emits lifecycle events
                |
                v
+--------------------------------------+
| UsageService                         |
| - per-Box Redis lock                 |
| - open / close usage period          |
| - 24h rollover                       |
| - archive closed periods             |
+-------------------+------------------+
                    |
          +---------+----------+
          |                    |
          v                    v
+-------------------+  +--------------------------+
| box_usage_period  |  | box_usage_period_archive |
| active + recent   |  | immutable closed history |
+---------+---------+  +------------+-------------+
          |                         |
          +------------+------------+
                       v
             UsageMeteringService
                       |
                       v
            GET /organization/:id/metering
                       |
                       v
             Dashboard /metering

Implementation notes

The lifecycle writer is intentionally small: Box state events open or close periods, Redis locks serialize writers, rollover bounds open-period duration, and archiving keeps the active table lightweight. BoxLite-specific metering queries remain outside the lifecycle writer.

Review order

1. apps/api/src/usage/services/usage.service.ts: lifecycle, locks, rollover, archive
2. apps/api/src/usage/entities/: ledger schema
3. apps/api/src/migrations/pre-deploy/1782700000000-migration.ts: physical tables and indexes
4. apps/api/src/usage/usage-metering.service.ts: read-only inspection adapter
5. apps/dashboard/src/pages/Metering.tsx: temporary verification UI

Validation

• Usage API tests: 4 suites, 23 tests passed
• Metering UI test: 1 test passed
• API production build passed
• Dashboard production build passed
• local-infra E2E passed against Postgres, Redis, API, and Dashboard
• E2E fixture cleanup verified: zero remaining mtr* / arc* rows

Supersedes #947.

[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: 94bc1e11-f66a-47f6-a89e-14617939dea0

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
• Commit unit tests in branch codex/billing-v3-pr1-daytona-usage

---

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.}