@saasicat/spec 1.0.0-rc.2 → 1.0.0-rc.20

package/index.cjs

@@ -3,16 +3,19 @@ const adminManifestSchema = require('./schemas/admin-manifest.schema.json');
 const planCatalogSchema = require('./schemas/plan-catalog.schema.json');
 const promoCodeSchema = require('./schemas/promo-code.schema.json');
 const auditEventSchema = require('./schemas/audit-event.schema.json');
+const tenantLedgerSchema = require('./schemas/tenant-ledger.schema.json');
 
 module.exports = {
     adminManifestSchema,
     planCatalogSchema,
     promoCodeSchema,
     auditEventSchema,
+    tenantLedgerSchema,
     SCHEMAS: {
         adminManifest: adminManifestSchema,
         planCatalog: planCatalogSchema,
         promoCode: promoCodeSchema,
         auditEvent: auditEventSchema,
+        tenantLedger: tenantLedgerSchema,
     },
 };

package/index.d.cts

@@ -1,13 +1,15 @@
-// @saasicat/spec — TS-Definitionen für CommonJS-Konsumenten.
+// @saasicat/spec — TypeScript definitions for CommonJS consumers.
 
 export declare const adminManifestSchema: Record<string, unknown>;
 export declare const planCatalogSchema: Record<string, unknown>;
 export declare const promoCodeSchema: Record<string, unknown>;
 export declare const auditEventSchema: Record<string, unknown>;
+export declare const tenantLedgerSchema: Record<string, unknown>;
 
 export declare const SCHEMAS: {
     readonly adminManifest: Record<string, unknown>;
     readonly planCatalog: Record<string, unknown>;
     readonly promoCode: Record<string, unknown>;
     readonly auditEvent: Record<string, unknown>;
+    readonly tenantLedger: Record<string, unknown>;
 };

package/index.d.ts

@@ -5,10 +5,12 @@ export declare const adminManifestSchema: Record<string, unknown>;
 export declare const planCatalogSchema: Record<string, unknown>;
 export declare const promoCodeSchema: Record<string, unknown>;
 export declare const auditEventSchema: Record<string, unknown>;
+export declare const tenantLedgerSchema: Record<string, unknown>;
 
 export declare const SCHEMAS: {
     readonly adminManifest: Record<string, unknown>;
     readonly planCatalog: Record<string, unknown>;
     readonly promoCode: Record<string, unknown>;
     readonly auditEvent: Record<string, unknown>;
+    readonly tenantLedger: Record<string, unknown>;
 };

package/index.js

@@ -6,12 +6,20 @@ import adminManifestSchema from './schemas/admin-manifest.schema.json' with { ty
 import planCatalogSchema from './schemas/plan-catalog.schema.json' with { type: 'json' };
 import promoCodeSchema from './schemas/promo-code.schema.json' with { type: 'json' };
 import auditEventSchema from './schemas/audit-event.schema.json' with { type: 'json' };
+import tenantLedgerSchema from './schemas/tenant-ledger.schema.json' with { type: 'json' };
 
-export { adminManifestSchema, planCatalogSchema, promoCodeSchema, auditEventSchema };
+export {
+    adminManifestSchema,
+    planCatalogSchema,
+    promoCodeSchema,
+    auditEventSchema,
+    tenantLedgerSchema,
+};
 
 export const SCHEMAS = {
     adminManifest: adminManifestSchema,
     planCatalog: planCatalogSchema,
     promoCode: promoCodeSchema,
     auditEvent: auditEventSchema,
+    tenantLedger: tenantLedgerSchema,
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@saasicat/spec",
-  "version": "1.0.0-rc.2",
+  "version": "1.0.0-rc.20",
   "description": "Language-neutral spec of the SaaS platform: JSON Schemas, OpenAPI contract, Prisma fragments, acceptance scenarios.",
   "type": "module",
   "main": "./index.cjs",
@@ -38,6 +38,7 @@
   "devDependencies": {
     "ajv": "^8.17.1",
     "ajv-formats": "^3.0.1",
+    "pg": "^8.22.0",
     "prisma": "^6.19.0"
   },
   "keywords": [
@@ -63,6 +64,7 @@
   },
   "scripts": {
     "gen:sql": "node scripts/generate-reference-sql.mjs",
-    "test": "node --test tests/*.test.js"
+    "test": "node --test tests/*.test.js",
+    "test:integration": "node --test 'tests/integration/*.test.js'"
   }
 }

package/prisma-fragments/01-subscription.prisma

@@ -1,5 +1,5 @@
 // =============================================================================
-// SaaS-Platform Prisma fragment: Subscription + Payment method
+// SaaS-Platform Prisma fragment: Subscription + CheckoutOffer
 // =============================================================================
 //
 // REFERENCE SNIPPET — not a standalone schema. Consumers copy
@@ -39,14 +39,6 @@ enum SubscriptionStatus {
     PENDING_SALES
 }
 
-enum SubscriptionPaymentType {
-    CARD
-    SEPA
-    PAYPAL
-    KLARNA
-    INVOICE
-}
-
 // -----------------------------------------------------------------------------
 // Subscription — one per Tenant. Binds to PlanVersion (see 03-plan-versions).
 // -----------------------------------------------------------------------------
@@ -61,12 +53,42 @@ model Subscription {
 
     trialEndsAt DateTime?
     startedAt   DateTime?
-    canceledAt  DateTime?
+    // WHEN the customer said they want out. Never refused: a cancellation is a
+    // declaration, and `canceledEffectiveAt` is when it lands. The two are
+    // separate because a subscription cancelled in month three of a year is
+    // still running, still billed and still entitled until the term ends —
+    // rendering it as "cancelled, gone" is how a tenant loses access they paid
+    // for. `SubscriptionBundle` already models it this way.
+    canceledAt          DateTime?
+    canceledEffectiveAt DateTime?
 
     // Renewal period (maintained by PlanVersionRenewalService).
     currentPeriodStart DateTime?
     currentPeriodEnd   DateTime?
 
+    // The end of what was committed to, which is not always the end of the
+    // period. They coincide while nothing changes, and part company the moment
+    // a notice period is configured: a cancellation declared after the window
+    // closed lands at the end of the FOLLOWING period, and this is where that
+    // date is kept rather than recomputed by whoever asks.
+    //
+    // Null means no commitment — a trial, or a subscription that predates this
+    // field. Readers treat null as "the period end is the answer".
+    minimumTermUntil DateTime?
+
+    // The day of the month this subscription is billed on, 1–31.
+    //
+    // Written when a period window is opened — at activation, and again at a
+    // plan change that resets the window — and never rewritten by a renewal.
+    // That is the whole point: a renewal reads it, and reading its own previous
+    // result is how the day used to drift. A subscription starting on the 31st
+    // was billed on the 28th from its first February onwards.
+    //
+    // Null on a row that predates this column, and on one with no period at
+    // all. Readers fall back to the day of whichever date opened the window,
+    // which is the old behaviour for one step and correct for that step.
+    billingAnchorDay Int?
+
     // Plan versioning — binds to a published PlanVersion.
     // `pendingPlanVersion*` concern a version change within the
     // same plan; `pendingPlan` the change to a different plan. Both
@@ -110,7 +132,6 @@ model Subscription {
 
     // Relations — consumer must define `Tenant` and enable the relation.
     // tenant             Tenant                    @relation(fields: [tenantId], references: [id], onDelete: Cascade)
-    paymentMethod       SubscriptionPaymentMethod?
     promoRedemption     PromoCodeRedemption? // see 02-promo-code.prisma
     planVersion         PlanVersion                 @relation("SubscriptionPlanVersion", fields: [planVersionId], references: [id])
     pendingPlanVersion  PlanVersion?                @relation("SubscriptionPendingPlanVersion", fields: [pendingPlanVersionId], references: [id])
@@ -124,39 +145,6 @@ model Subscription {
     @@map("subscriptions")
 }
 
-// -----------------------------------------------------------------------------
-// SubscriptionPaymentMethod — masked payment data per Subscription.
-// -----------------------------------------------------------------------------
-
-model SubscriptionPaymentMethod {
-    id             String                  @id @default(uuid())
-    subscriptionId String                  @unique
-    type           SubscriptionPaymentType
-
-    // Card (masked)
-    cardName  String?
-    cardBrand String?
-    cardLast4 String?
-    cardExp   String?
-
-    // SEPA (masked)
-    ibanLast4 String?
-    ibanName  String?
-
-    // PayPal
-    paypalEmail String?
-
-    // Klarna
-    klarnaPlan String? // "invoice" | "instalments"
-
-    createdAt DateTime @default(now())
-    updatedAt DateTime @updatedAt
-
-    subscription Subscription @relation(fields: [subscriptionId], references: [id], onDelete: Cascade)
-
-    @@map("subscription_payment_methods")
-}
-
 // -----------------------------------------------------------------------------
 // CheckoutOffer — immutable package snapshot from the website through to the
 // Subscription (METAMODELL §17a).
@@ -171,8 +159,7 @@ model SubscriptionPaymentMethod {
 // -----------------------------------------------------------------------------
 
 model CheckoutOffer {
-    id         String @id @default(uuid())
-    projectKey String
+    id String @id @default(uuid())
 
     planKey       String
     planVersionId String?
@@ -197,6 +184,6 @@ model CheckoutOffer {
     createdAt DateTime @default(now())
     updatedAt DateTime @updatedAt
 
-    @@index([projectKey, status])
+    @@index([status])
     @@map("checkout_offers")
 }

package/prisma-fragments/03-plan-versions.prisma

@@ -20,7 +20,7 @@
 // -----------------------------------------------------------------------------
 // Plan — root identity of a plan (SPEC_V2 §11.1 M6).
 // `planKey` is the business plan identity (STARTER / STANDARD / PROFESSIONAL),
-// unique per `projectKey`. PlanVersion.planId points **softly** to
+// unique for the installation. PlanVersion.planId points **softly** to
 // `Plan.planKey` (no DB FK — the binding is enforced via service logic in M6
 // so that the greenfield cutover can run without a destructive schema
 // migration).
@@ -32,7 +32,6 @@
 
 model Plan {
     id          String  @id @default(uuid())
-    projectKey  String
     planKey     String
     label       String
     description String?
@@ -43,8 +42,8 @@ model Plan {
     updatedAt DateTime  @updatedAt
     deletedAt DateTime?
 
-    @@unique([projectKey, planKey])
-    @@index([projectKey, deletedAt])
+    @@unique([planKey])
+    @@index([deletedAt])
     @@map("plans")
 }
 

package/prisma-fragments/05-bundle.prisma

@@ -6,8 +6,8 @@
 //
 // Global catalog tables (no tenantId, no RLS). Write access only via the
 // SUPER_ADMIN guard in the AdminController of the `@saasicat/nest`
-// package. Entries are assigned to the respective consumer app via
-// `projectKey`.
+// package. One installation serves one application, so `bundleKey` is the
+// whole identity.
 //
 // Versioning pattern identical to PlanVersion:
 //   - at most 1 draft (publishedAt IS NULL) per identity — constraint via a
@@ -25,7 +25,6 @@
 
 model Bundle {
     id          String   @id @default(uuid())
-    projectKey  String // e.g. 'clubapp' | 'demoapp' | …
     bundleKey   String // SCREAMING_SNAKE_CASE, e.g. 'SPORT', 'ACCOUNTING', 'EVERSEND_PEPPOL'
     label       String
     description String?
@@ -41,8 +40,8 @@ model Bundle {
 
     versions BundleVersion[]
 
-    @@unique([projectKey, bundleKey])
-    @@index([projectKey, deletedAt])
+    @@unique([bundleKey])
+    @@index([deletedAt])
     @@map("bundles")
 }
 

package/prisma-fragments/06-catalog-entries.prisma

@@ -42,7 +42,6 @@
 
 model CapabilityCatalogEntry {
     id            String  @id @default(uuid())
-    projectKey    String // e.g. 'clubapp' | 'demoapp' | …
     capabilityKey String // 'invoice.create' | 'member.archive' | …
     label         String
     description   String?
@@ -77,9 +76,9 @@ model CapabilityCatalogEntry {
     updatedAt DateTime  @updatedAt
     deletedAt DateTime?
 
-    @@unique([projectKey, capabilityKey])
-    @@index([projectKey, codeStatus])
-    @@index([projectKey, featureKey])
+    @@unique([capabilityKey])
+    @@index([codeStatus])
+    @@index([featureKey])
     @@map("capability_catalog_entries")
 }
 
@@ -100,7 +99,6 @@ model CapabilityCatalogEntry {
 
 model FeatureCatalogEntry {
     id          String  @id @default(uuid())
-    projectKey  String
     featureKey  String // 'INVOICE_MANAGEMENT' | 'MEMBER_LIST' | …
     label       String
     description String?
@@ -148,9 +146,9 @@ model FeatureCatalogEntry {
     updatedAt DateTime  @updatedAt
     deletedAt DateTime?
 
-    @@unique([projectKey, featureKey])
-    @@index([projectKey, discoveryStatus])
-    @@index([projectKey, plannedOnly])
+    @@unique([featureKey])
+    @@index([discoveryStatus])
+    @@index([plannedOnly])
     @@map("feature_catalog_entries")
 }
 
@@ -164,7 +162,6 @@ model FeatureCatalogEntry {
 
 model QuotaCatalogEntry {
     id          String  @id @default(uuid())
-    projectKey  String
     quotaKey    String // 'invoicesPerMonth' | 'members' | 'storageGb' | …
     label       String
     description String?
@@ -200,8 +197,8 @@ model QuotaCatalogEntry {
     updatedAt DateTime  @updatedAt
     deletedAt DateTime?
 
-    @@unique([projectKey, quotaKey])
-    @@index([projectKey, discoveryStatus])
+    @@unique([quotaKey])
+    @@index([discoveryStatus])
     @@map("quota_catalog_entries")
 }
 
@@ -223,8 +220,7 @@ model QuotaCatalogEntry {
 // -----------------------------------------------------------------------------
 
 model MarketingProjection {
-    id         String @id @default(uuid())
-    projectKey String
+    id String @id @default(uuid())
 
     // Polymorphic reference to a versioned entity.
     targetType      String // 'PLAN' | 'BUNDLE'
@@ -239,7 +235,7 @@ model MarketingProjection {
     // not appear on the pricing page.
     visible Boolean @default(true)
 
-    // Optional badge at the top of the card ('Beliebt', 'Neu'). '' = no badge.
+    // Optional badge at the top of the card ('Popular', 'New'). '' = no badge.
     badge String @default("")
 
     // Top features for the public catalog card: [{ label, strong }].
@@ -250,7 +246,7 @@ model MarketingProjection {
     trialEnabled Boolean @default(false)
     trialDays    Int     @default(30)
 
-    // Optional formatted pricing tag (e.g. "€ 9,90 / Monat" or "auf Anfrage").
+    // Optional formatted pricing tag (e.g. "EUR 9.90 / month" or "on request").
     // If null: pricing is formatted automatically from PlanVersion.monthlyNet
     // etc. at public-catalog render time.
     priceTag String?
@@ -261,28 +257,32 @@ model MarketingProjection {
     // Sort order in the public list (DESC). Higher values first.
     priority Int @default(0)
 
-    // "Empfohlen" star / featured highlight in the UI.
+    // The recommended plan: a star, or a featured card, in the UI.
     highlight Boolean @default(false)
 
     createdAt DateTime @default(now())
     updatedAt DateTime @updatedAt
 
     @@unique([targetType, targetVersionId, locale])
-    @@index([projectKey, targetType, locale, priority])
+    @@index([targetType, locale, priority])
     @@map("marketing_projections")
 }
 
 // -----------------------------------------------------------------------------
-// MarketingSettings — project-wide, runtime-editable marketing config.
-// One row per project (`projectKey` unique). Currently exactly one field:
-// `activeLocales` — the subset of the `availableLocales` pool activated in the
-// marketing catalog (the pool comes from the app config, SPEC_V2 §6.5).
-// If the row is missing, the full pool counts as active.
+// MarketingSettings — installation-wide, runtime-editable marketing config.
+// At most one row. The constant default gets a caller that omits `id` onto the
+// right row, but it is not what holds the rule — a default does not apply to a
+// caller that supplies one, and a primary key accepts every distinct value. The
+// `CHECK` in sql/constraints.postgres.sql is what holds it; the Prisma DSL
+// cannot say it here.
+// Currently exactly one field: `activeLocales` — the subset of the
+// `availableLocales` pool activated in the marketing catalog (the pool comes
+// from the app config, SPEC_V2 §6.5). If the row is missing, the full pool
+// counts as active.
 // -----------------------------------------------------------------------------
 
 model MarketingSettings {
-    id         String @id @default(uuid())
-    projectKey String @unique
+    id String @id @default("marketing-settings")
 
     activeLocales Json @default("[]") // string[]
 

package/prisma-fragments/07-promotion.prisma

@@ -14,8 +14,7 @@
 // via the SUPER_ADMIN guard in the AdminController.
 
 model Promotion {
-    id         String @id @default(uuid())
-    projectKey String // e.g. 'clubapp' | 'demoapp' | …
+    id String @id @default(uuid())
 
     // Internal label (not public).
     internalLabel String
@@ -60,6 +59,6 @@ model Promotion {
     createdAt DateTime @default(now())
     updatedAt DateTime @updatedAt
 
-    @@index([projectKey, targetType, validFrom, validTo])
+    @@index([targetType, validFrom, validTo])
     @@map("promotions")
 }

package/prisma-fragments/08-subscription-contract.prisma

@@ -8,6 +8,12 @@
 // V3 rule: billing and entitlement must not depend on live-mutable catalog
 // tables. `SubscriptionContract` and `ContractLineItem` therefore store full
 // snapshots. Catalog FKs are optional and only audit/trace references.
+//
+// A contract belongs to its subscriber (13-subscriber.prisma), not to the
+// tenant, and outlives the tenant (ADR 0012). `tenantId` is kept as a trace of
+// the tenant it was concluded for, and deliberately has no relation to the
+// application's `Tenant` model: a cascade there deletes the tax record with the
+// tenant, and a restriction keeps a tenant from ever being deleted.
 
 enum SubscriptionContractStatus {
     active
@@ -25,9 +31,21 @@ enum ContractLineItemKind {
 }
 
 model SubscriptionContract {
-    id         String @id @default(uuid())
-    projectKey String
-    tenantId   String
+    id       String @id @default(uuid())
+    tenantId String
+
+    // Who the contract is between, copied on the day it is concluded: the
+    // subscriber as its record stood, and the issuer as `config/saas.yaml`
+    // named it — null where it named none. Neither copy follows a later change
+    // to the subscriber or the configuration. The invoice email is not copied:
+    // it says how the party is reached, not who it is.
+    subscriberId       String
+    subscriberSnapshot Json
+    issuerSnapshot     Json?
+    // The copies were made by the migration that attached contracts concluded
+    // before subscribers existed, not at conclusion, and are never presented as
+    // what was agreed.
+    partiesMigrated    Boolean @default(false)
 
     status         SubscriptionContractStatus @default(active)
     effectiveFrom  DateTime
@@ -51,10 +69,11 @@ model SubscriptionContract {
     createdAt DateTime @default(now())
     updatedAt DateTime @updatedAt
 
-    // tenant Tenant @relation(fields: [tenantId], references: [id], onDelete: Cascade)
+    subscriber Subscriber @relation(fields: [subscriberId], references: [id], onDelete: Restrict)
 
     @@index([tenantId, status, effectiveFrom])
-    @@index([projectKey, status])
+    @@index([subscriberId])
+    @@index([status])
     @@index([originalOfferId])
     @@map("subscription_contracts")
 }
@@ -76,6 +95,24 @@ model ContractLineItem {
     priceGross   Decimal @db.Decimal(10, 2)
     billingCycle String // monthly | yearly
 
+    // What this line is worth, as facts rather than as something to work out
+    // later. An installation sells in one currency and applies one rate at a
+    // time, and both are configured elsewhere — but a row has to keep saying
+    // what it meant after either is changed, and a change is a migration
+    // precisely because it must not relabel history.
+    //
+    // `taxRate` is recorded even though `priceNet` and `priceGross` are both
+    // here, because the ratio between them is not the rate: it cannot be
+    // reproduced for a gross that was rounded, it cannot express an exempt or a
+    // reverse-charge line, and it does not survive a rate change.
+    //
+    // `taxAmount` closes the gap between net and gross exactly, so the row
+    // cannot disagree with itself. Deriving it at read time instead would round
+    // a second time, once per reader.
+    currency  String
+    taxRate   Decimal @db.Decimal(5, 2)
+    taxAmount Decimal @db.Decimal(10, 2)
+
     minimumTermUntil DateTime?
 
     featuresSnapshot     Json @default("[]")

package/prisma-fragments/09-pending-registration.prisma

@@ -1,5 +1,5 @@
 // =============================================================================
-// SaaS Platform Prisma fragment: PendingRegistration + PaymentEventLog
+// SaaS Platform Prisma fragment: PendingRegistration
 // =============================================================================
 //
 // REFERENCE SNIPPET — see 01-subscription.prisma for conventions.
@@ -7,8 +7,9 @@
 // Persistence of the multi-step registration and onboarding flow
 // (`PendingRegistrationService`). A PendingRegistration holds the
 // intermediate state between step 1 (capturing sign-up data) and the final
-// activation (step 4: payment). Only after successful payment does it become
-// User + Tenant + Subscription — until then the record deliberately stays
+// activation (step 4: billing address and payment method). Only once the
+// payment gateway confirmed the payment method does it become User + Tenant +
+// Subscriber + Subscription — until then the record deliberately stays
 // without a foreign key to consumer models.
 //
 // Unlike the other fragments, WITHOUT `@@map`: the model was adopted back from
@@ -16,12 +17,14 @@
 // default names — a subsequent `@@map` would only force a table rename.
 //
 // Contract: @saasicat/core (src/registration.types.ts) (PendingRegistration,
-//           PendingRegistrationRepository, PaymentEventLog).
+//           PendingRegistrationRepository). The gateway events a sign-up's
+//           confirmation is claimed in are `PaymentEventLog`, in
+//           14-payments.prisma.
 // Service logic: @saasicat/nest/registration (PendingRegistrationService).
 
 // Multi-step registration flow: status of a PendingRegistration
 // between sign-up-data capture (step 1) and final activation
-// after payment (step 4).
+// once the payment method is confirmed (step 4).
 enum RegistrationStatus {
     PENDING_EMAIL_VERIFICATION
     EMAIL_VERIFIED
@@ -64,11 +67,29 @@ model PendingRegistration {
     // - billingCycle: 'MONTHLY' | 'YEARLY' — determines the price calculation.
     // - appliedPromoCode: last-applied code (plaintext, only for UI display;
     //   validation runs fresh every time via PromoCodesService).
-    configJson        Json?
-    billingCycle      String?
-    appliedPromoCode  String?
-    checkoutSessionId String?
-    checkoutStartedAt DateTime?
+    configJson       Json?
+    billingCycle     String?
+    appliedPromoCode String?
+
+    // Billing details (step 4), which the subscriber is created with. The
+    // address is required before a payment method is set up; the tax
+    // identifiers stay optional.
+    addressLine1 String?
+    addressLine2 String?
+    postalCode   String?
+    city         String?
+    country      String? // ISO 3166-1 alpha-2
+    vatId        String?
+    taxNumber    String?
+
+    // The payment gateway's session for the payment method. A session id is
+    // unique only within the gateway account that opened it, so the account
+    // is kept beside it; the customer the gateway created is reused when the
+    // step is repeated.
+    checkoutSessionId      String?
+    checkoutGatewayAccount String?
+    gatewayCustomerRef     String?
+    checkoutStartedAt      DateTime?
 
     expiresAt DateTime
     createdAt DateTime @default(now())
@@ -76,21 +97,5 @@ model PendingRegistration {
 
     @@index([status, expiresAt])
     @@index([tenantSlug])
-}
-
-// PaymentEventLog — idempotency key for payment webhooks.
-// Prevents a doubly delivered webhook (Stripe at-least-once) from triggering
-// the final activation more than once. `eventId` is the provider event ID
-// (Stripe `event.id`), `tryClaim` uses a @unique INSERT as race protection.
-model PaymentEventLog {
-    id          String   @id @default(cuid())
-    eventId     String   @unique
-    provider    String
-    sessionId   String?
-    status      String
-    payload     Json?
-    processedAt DateTime @default(now())
-
-    @@index([sessionId])
-    @@index([status, processedAt])
+    @@index([checkoutGatewayAccount, checkoutSessionId])
 }

package/prisma-fragments/11-subscription-bundle.prisma

@@ -29,6 +29,23 @@ model SubscriptionBundle {
     // only at `minimumTermEndsAt`.
     minimumTermEndsAt DateTime?
 
+    // The rhythm this booking is billed in, and the window it is billed for.
+    //
+    // A bundle may run in a shorter rhythm than its plan but never a longer
+    // one, so a yearly bundle exists only beside a yearly plan. Its periods end
+    // on the day the plan's do: the first one is short, from the booking to the
+    // next occurrence of that day, and every one after it runs anchor to
+    // anchor. Aligned at booking rather than trimmed at the end, because a trim
+    // means somebody was committed to more than they received.
+    //
+    // Null on a booking made before these columns existed, and on one whose
+    // plan has no period at all — a trial, or a subscription awaiting sales.
+    // Readers fall back to the plan's cycle, which is what every booking used
+    // before this.
+    billingCycle       String?
+    currentPeriodStart DateTime?
+    currentPeriodEnd   DateTime?
+
     // Cancellation: requested at `canceledAt`, effective at
     // `canceledEffectiveAt` (period/term end). Both null = active booking.
     canceledAt          DateTime?