feat(billing): add billing arrangement entity and validation

Merged
ET
14d ago
+869-0

First step of core-team-issues#2997: a table that records every commercial exception to a plan (who granted it, why, until when). Nothing reads or writes it yet. Admin actions, seat sync and the migration of today's Stripe coupons come in follow-up PRs.

Summary

One row per exception, typed settings, no foreign keys so the history outlives the workspace and the rows it points to.

core.billingArrangement
  workspaceId, type, label, comment
  settings      seats | seatCapMode | stripePriceId | stripeDiscountId (unique)
                | creditAllowanceMicro | stripeCreditNoteId | creditGrantId | usageLimitId
  period        startsAt, endsAt (null = open-ended), revokedAt, revokedByUserId
  grantedByUserId, createdAt, updatedAt
TypeRequiredOptionalendsAt means
COMMITTED_SEATSseats, seatCapMode, endsAtstripePriceIdend of the commitment term
FREE_SEATSseatsendsAtwhen the seats stop being free
DISCOUNTstripeDiscountIdendsAtwhen the discount stops
TRIAL_EXTENSIONendsAtthe new trial end
WORKSPACE_CREDIT_ALLOWANCEcreditAllowanceMicro (0 allowed)endsAtwhen the plan's AI credits come back
LIMIT_OVERRIDEusageLimitIdendsAtwhen the default limit comes back
REFUNDstripeCreditNoteIdnot allowed, one-time
CREDIT_GRANTcreditGrantIdnot allowed, one-time

These rules live in BILLING_ARRANGEMENT_SETTINGS_BY_TYPE; an optional endsAt left empty means no end date.

A DISCOUNT row mirrors one Stripe discount, so it stores the discount id, not the coupon: the coupon is only the template staff pick, and the same coupon applied twice gives two discounts. The unique index lets the admin action and the discount webhook (#29425) both write a row without a lock.

label is a TypeScript enum stored as varchar (APP_OWNER_WORKSPACE, COMPENSATION, OTHER for now), so adding a label needs no migration. type and seatCapMode are Postgres enums.

Pure utils the service layer will use:

getBillingArrangementValidationErrors(draft) -> errors[]
  missing or unexpected settings for the type (endsAt included),
  seats a positive int4, allowance a safe integer >= 0,
  comment <= 500 chars, valid dates, end after start

isBillingArrangementActive({ arrangement, now })
  lasting type, started, not past min(endsAt, revokedAt)

findOverlappingBillingArrangement({ arrangement, workspaceArrangements })
  same lasting type with overlapping periods -> the conflict
  (periods ended before they started never conflict)
  (one active arrangement per type per workspace, checked at write time
   since a time-based condition cannot live in a unique index)

The table is created by a fast instance command generated with database:migrate:generate against a billing-enabled database. Only the billingArrangement statements are kept (the generator also emits pre-existing drift on other billing tables), and the command is skipped when billingCustomer is absent, like billingCreditGrant.

Evidence

  • Before: no table, no validation.
    After: jest on the 4 new specs: 45 passed. After applying the command through run-instance-commands on a scratch database, a second generator run produces no billingArrangement statement.

Merge Danger

Door: two-way

New table, no readers or writers; down drops it.

Blast Radius: none

Billing-enabled instances get an empty table.