feat(billing): add billing arrangement entity and validation
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
| Type | Required | Optional | endsAt means |
|---|---|---|---|
COMMITTED_SEATS | seats, seatCapMode, endsAt | stripePriceId | end of the commitment term |
FREE_SEATS | seats | endsAt | when the seats stop being free |
DISCOUNT | stripeDiscountId | endsAt | when the discount stops |
TRIAL_EXTENSION | endsAt | the new trial end | |
WORKSPACE_CREDIT_ALLOWANCE | creditAllowanceMicro (0 allowed) | endsAt | when the plan's AI credits come back |
LIMIT_OVERRIDE | usageLimitId | endsAt | when the default limit comes back |
REFUND | stripeCreditNoteId | not allowed, one-time | |
CREDIT_GRANT | creditGrantId | not 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:jeston the 4 new specs: 45 passed. After applying the command throughrun-instance-commandson a scratch database, a second generator run produces nobillingArrangementstatement.
Merge Danger
Door: two-way
New table, no readers or writers; down drops it.
Blast Radius: none
Billing-enabled instances get an empty table.