@saasicat/spec 1.0.0-rc.24 → 1.0.0-rc.26

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@saasicat/spec",
-  "version": "1.0.0-rc.24",
+  "version": "1.0.0-rc.26",
   "description": "Language-neutral spec of the SaaS platform: JSON Schemas, OpenAPI contract, Prisma fragments, acceptance scenarios.",
   "type": "module",
   "main": "./index.cjs",

package/prisma-fragments/05-bundle.prisma

@@ -90,9 +90,10 @@ model BundleVersion {
     bundle              Bundle               @relation(fields: [bundleId], references: [id], onDelete: Cascade)
     baseVersion         BundleVersion?       @relation("BundleVersionLineage", fields: [baseVersionId], references: [id])
     derivedVersions     BundleVersion[]      @relation("BundleVersionLineage")
-    // Standalone add-on bookings pinned to this version (see
-    // 11-subscription-bundle.prisma).
-    subscriptionBundles SubscriptionBundle[]
+    // Standalone add-on bookings pinned to this version, and the ones set to
+    // continue on it at the end of their term (see 11-subscription-bundle.prisma).
+    subscriptionBundles        SubscriptionBundle[] @relation("SubscriptionBundleVersion")
+    subscriptionBundlesPending SubscriptionBundle[] @relation("SubscriptionBundlePendingVersion")
 
     @@unique([bundleId, version])
     @@index([bundleId, supersededAt])

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

@@ -47,6 +47,13 @@ model SubscriptionContract {
     // what was agreed.
     partiesMigrated    Boolean @default(false)
 
+    // The tax treatment the installation's tax adapter decided when the
+    // contract was concluded: its kind, rate and note, with the adapter's name
+    // and version (ADR 0013). Null where no adapter was asked — an installation
+    // without one, a contract from before, or a path that does not ask one
+    // yet; each invoice then takes the adapter's answer when it is issued.
+    taxTreatment Json?
+
     status         SubscriptionContractStatus @default(active)
     effectiveFrom  DateTime
     effectiveUntil DateTime?
@@ -66,6 +73,7 @@ model SubscriptionContract {
 
     lineItems     ContractLineItem[]
     ledgerEntries SubscriberLedgerEntry[] // see 15-subscriber-ledger.prisma
+    invoices      SubscriptionInvoice[]     // see 20-subscription-invoice.prisma
 
     createdAt DateTime @default(now())
     updatedAt DateTime @updatedAt
@@ -124,6 +132,7 @@ model ContractLineItem {
 
     contract      SubscriptionContract    @relation(fields: [contractId], references: [id], onDelete: Cascade)
     ledgerEntries SubscriberLedgerEntry[] // see 15-subscriber-ledger.prisma
+    invoiceLines  SubscriptionInvoiceLine[] // see 20-subscription-invoice.prisma
 
     @@index([contractId, kind])
     @@index([sourceVersionId])

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

@@ -81,6 +81,12 @@ model PendingRegistration {
     country      String? // ISO 3166-1 alpha-2
     vatId        String?
     taxNumber    String?
+    // Whether the sign-up is a business, which a tax adapter decides from; and
+    // the check of `vatId` made in step 4, outside any transaction, where the
+    // adapter needed a validated number. The subscriber takes the check over
+    // when it is created, so its first contract is decided from it.
+    business   Boolean?
+    vatIdCheck Json?
 
     // 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

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

@@ -46,6 +46,14 @@ model SubscriptionBundle {
     currentPeriodStart DateTime?
     currentPeriodEnd   DateTime?
 
+    // A switch to a newer version of the add-on that takes something away,
+    // taken for the end of the booking's running term: the version it continues
+    // on, and from when. Both null, or both set — `constraints.postgres.sql`
+    // holds them to that. The platform's quarter-hourly run makes the switch at
+    // that moment and clears both.
+    pendingBundleVersionId    String?
+    pendingVersionEffectiveAt DateTime?
+
     // Cancellation: requested at `canceledAt`, effective at
     // `canceledEffectiveAt` (period/term end). Both null = active booking.
     canceledAt          DateTime?
@@ -56,11 +64,13 @@ model SubscriptionBundle {
 
     // The subscription this add-on is booked on. Restrict the BundleVersion so
     // a booked version cannot be hard-deleted from the catalog.
-    subscription  Subscription  @relation(fields: [subscriptionId], references: [id], onDelete: Cascade)
-    bundleVersion BundleVersion @relation(fields: [bundleVersionId], references: [id], onDelete: Restrict)
+    subscription         Subscription   @relation(fields: [subscriptionId], references: [id], onDelete: Cascade)
+    bundleVersion        BundleVersion  @relation("SubscriptionBundleVersion", fields: [bundleVersionId], references: [id], onDelete: Restrict)
+    pendingBundleVersion BundleVersion? @relation("SubscriptionBundlePendingVersion", fields: [pendingBundleVersionId], references: [id], onDelete: Restrict)
 
     @@index([subscriptionId])
     @@index([bundleVersionId])
     @@index([canceledEffectiveAt])
+    @@index([pendingVersionEffectiveAt])
     @@map("subscription_bundles")
 }

package/prisma-fragments/13-subscriber.prisma

@@ -1,5 +1,6 @@
 // =============================================================================
-// SaaS platform Prisma fragment: Subscriber, its tenants, its corrections
+// SaaS platform Prisma fragment: Subscriber, its tenants, its corrections,
+// the changes of its tax origin, the checks of its VAT id
 // =============================================================================
 //
 // REFERENCE SNIPPET — see 01-subscription.prisma for conventions.
@@ -32,6 +33,25 @@ model Subscriber {
     vatId     String?
     taxNumber String?
 
+    // The tax origin beside the country and the VAT id (ADR 0013): whether the
+    // subscriber is a business, as sign-up or the operator recorded it — null
+    // while nobody has said, and never derived from a tax identifier, since a
+    // business outside the European Union may have none. A change of the
+    // country, the business status or the VAT id is recorded in
+    // `SubscriberTaxOriginChange`.
+    business Boolean?
+
+    // Which recorded check of the VAT id counts now (`SubscriberVatIdCheck`):
+    // the latest completed one of the number the subscriber has. Null while
+    // none does — never checked, or the number corrected since. A reference
+    // without a relation: the check already points at its subscriber, and a
+    // key in both directions would tie each row to the other.
+    currentVatIdCheckId String?
+    // Since when the VAT id is held, set by the correction that wrote it; null
+    // while it is the one the subscriber was created with. A check completed
+    // before it does not count for the number.
+    vatIdSince          DateTime?
+
     // Contact details, which change at any time.
     addressLine1 String?
     addressLine2 String?
@@ -47,12 +67,15 @@ model Subscriber {
     createdAt DateTime @default(now())
     updatedAt DateTime @updatedAt
 
-    tenants        SubscriberTenant[]
-    corrections    SubscriberCorrection[]
-    contracts      SubscriptionContract[]
+    tenants             SubscriberTenant[]
+    corrections         SubscriberCorrection[]
+    taxOriginChanges    SubscriberTaxOriginChange[]
+    vatIdChecks         SubscriberVatIdCheck[]
+    contracts           SubscriptionContract[]
     paymentMethods      SubscriberPaymentMethod[] // see 14-payments.prisma
     paymentMethodSetups SubscriberPaymentMethodSetup[]
     ledgerEntries       SubscriberLedgerEntry[] // see 15-subscriber-ledger.prisma
+    invoices            SubscriptionInvoice[]   // see 20-subscription-invoice.prisma
 
     @@map("subscribers")
 }
@@ -76,11 +99,14 @@ model SubscriberTenant {
 }
 
 // A correction of a subscriber's legal identity: the values it replaced, the
-// values it wrote, why, and who made it. Only the fields that moved are in the
-// two JSON objects. Written in the same transaction as the change, and never
-// rewritten.
+// values it wrote, why, who made it, and when the write held the subscriber's
+// lock. Only the fields that moved are in the two JSON objects. Written in the
+// same transaction as the change, and never rewritten.
 model SubscriberCorrection {
     id           String   @id @default(uuid())
+    // The order the corrections were written in, numbered by the database at
+    // the write, and the order the list is read in. Never set by the platform.
+    seq          Int      @unique @default(autoincrement())
     subscriberId String
     previous     Json
     corrected    Json
@@ -90,6 +116,54 @@ model SubscriberCorrection {
 
     subscriber Subscriber @relation(fields: [subscriberId], references: [id], onDelete: Restrict)
 
-    @@index([subscriberId, correctedAt])
+    @@index([subscriberId, seq])
     @@map("subscriber_corrections")
 }
+
+// A change of a subscriber's tax origin — its country, whether it is a
+// business, its VAT id — whichever way it arrived: a contact change, a
+// correction of the legal identity, a change of the business status. The
+// values it replaced, the values it wrote, who made it, and when the write
+// held the subscriber's lock; only the fields that moved are in the two JSON
+// objects. Written in the same transaction as the change, never rewritten, and
+// applied from the subscriber's next invoice.
+model SubscriberTaxOriginChange {
+    id           String   @id @default(uuid())
+    // The order the changes were written in, numbered by the database at the
+    // write, and the order the list is read in. Never set by the platform.
+    seq          Int      @unique @default(autoincrement())
+    subscriberId String
+    previous     Json
+    changed      Json
+    changedBy    String
+    changedAt    DateTime
+    // Why: the reason of the correction or of the change of business status
+    // that made it; null for a change of the country with the contact details.
+    reason       String?
+
+    subscriber Subscriber @relation(fields: [subscriberId], references: [id], onDelete: Restrict)
+
+    @@index([subscriberId, seq])
+    @@map("subscriber_tax_origin_changes")
+}
+
+// A completed check of a subscriber's VAT id, as the service answered it: the
+// number checked, when the answer came, whether it found the number valid, the
+// service and its confirmation. Recorded for every check, whether it counts or
+// not, and never rewritten: a reverse charge rests on the confirmation that
+// held when the invoice was issued (ADR 0013).
+model SubscriberVatIdCheck {
+    id           String   @id @default(uuid())
+    subscriberId String
+    vatId        String
+    checkedAt    DateTime
+    valid        Boolean
+    service      String
+    confirmation Json
+    recordedAt   DateTime @default(now())
+
+    subscriber Subscriber @relation(fields: [subscriberId], references: [id], onDelete: Restrict)
+
+    @@index([subscriberId, checkedAt])
+    @@map("subscriber_vat_id_checks")
+}

package/prisma-fragments/15-subscriber-ledger.prisma

@@ -23,7 +23,7 @@
 //
 // `origin` and `source` are text holding a closed set, checked when a row is
 // read (`toSubscriberChargeRecord` in @saasicat/core):
-//   origin: activation | renewal | planChange | bundleBooking | credit | correction
+//   origin: activation | renewal | planChange | bundleBooking | bundleChange | credit | correction
 //   source: plan | bundle | discount
 //
 // Optional: adopt it where `tenantBilling.chargeJournal` is configured, which
@@ -57,6 +57,7 @@ model SubscriberLedgerEntry {
     subscriber       Subscriber           @relation(fields: [subscriberId], references: [id], onDelete: Restrict)
     contract         SubscriptionContract @relation(fields: [contractId], references: [id], onDelete: Restrict)
     contractLineItem ContractLineItem     @relation(fields: [contractLineItemId], references: [id], onDelete: Restrict)
+    invoiceLine      SubscriptionInvoiceLine? // see 20-subscription-invoice.prisma
 
     @@unique([subscriptionId, source, sourceRef, periodStart, origin])
     @@index([subscriberId, bookedAt])

package/prisma-fragments/17-subscription-notice.prisma

@@ -21,7 +21,8 @@
 // `subscriptionId` are kept as values, not as keys.
 //
 // `kind` is text holding a closed set: version-offered, version-retired,
-// version-retirement-reminder.
+// version-retirement-reminder, bundle-version-retired,
+// bundle-version-retirement-reminder.
 //
 // Optional: adopt it where `tenantBilling.versionNotices` is configured, which
 // refuses to start without a place to keep notices; a retirement needs it too.
@@ -37,7 +38,9 @@ model SubscriptionNotice {
     // What the notice is about — for version-offered, the id of the version
     // offered; for version-retired and version-retirement-reminder, the id of
     // the version retired, so a subscription is told of a version's retirement
-    // once and reminded of it once.
+    // once and reminded of it once; for bundle-version-retired and
+    // bundle-version-retirement-reminder, the id of the add-on version retired,
+    // so the subscription's booking of it is told once and reminded of it once.
     subject String
     // The notice as it was last handed to the application.
     content Json

package/prisma-fragments/19-bundle-version-retirement.prisma

@@ -0,0 +1,44 @@
+// =============================================================================
+// SaaS platform Prisma fragment: BundleVersionRetirement
+// =============================================================================
+//
+// REFERENCE SNIPPET — see 01-subscription.prisma for conventions.
+//
+// One row per add-on retirement an operator announces: an add-on version ended
+// for the bookings already on it, with the version of the same add-on they
+// continue on. Kept as evidence of what was announced, when and by whom, as
+// `version_retirements` is for a plan version.
+//
+// What it means for each booking it reaches — the date it takes effect, the
+// last day to cancel without the minimum term, and to whom and how that was
+// told — is a `subscription_notices` row of kind bundle-version-retired,
+// written in the same transaction: its subject is the retired add-on version,
+// its content names this row's id as `retirementId`.
+//
+// The versions are kept as values, not as keys: the record outlives the
+// catalogue entries it names, as the notices do (ADR 0012).
+//
+// Optional: adopt it where an operator may retire add-on versions
+// (`tenantBilling.orderlyRetirement` in config/saas.yaml). Without it, retiring
+// an add-on version is off; retiring a plan version is not affected.
+//
+// Contract: @saasicat/core (BundleVersionRetirementRepository).
+
+model BundleVersionRetirement {
+    id String @id @default(uuid())
+
+    retiredBundleVersionId String
+    retiredBundleKey       String
+    retiredVersion         Int
+
+    replacementBundleVersionId String
+    replacementBundleKey       String
+    replacementVersion         Int
+
+    announcedAt DateTime @default(now())
+    // Who announced it — an actor tag, as the audit log writes it.
+    announcedBy String
+
+    @@index([retiredBundleVersionId])
+    @@map("bundle_version_retirements")
+}

package/prisma-fragments/20-subscription-invoice.prisma

@@ -0,0 +1,145 @@
+// =============================================================================
+// SaaS platform Prisma fragment: SubscriptionInvoice
+// =============================================================================
+//
+// REFERENCE SNIPPET — see 01-subscription.prisma for conventions.
+//
+// The invoices issued from the charge journal (15-subscriber-ledger.prisma):
+// the charges a billing period opens with on one invoice, a charge that arises
+// later on an invoice of its own. An invoice copies everything it states when
+// it is issued — the issuer, the subscriber, the tax treatment the adapter
+// decided, the tax per rate — so a later change leaves it as it was. Nothing
+// updates or deletes an invoice; a correction is a cancellation invoice and its
+// replacement.
+//
+// A line invoices one charge, and a charge stands on one line: the unique
+// `chargeId` is what makes a second run issuing the same charges write
+// nothing, however many run at the same time.
+//
+// The number range is the table `subscription_invoice_numbers`, one row per
+// year holding the last number drawn. An invoice draws its number by raising
+// that row in the transaction that writes the invoice, so an invoice that
+// fails to be written leaves no gap, and two at the same time wait for each
+// other rather than drawing the same number. One installation is the range of
+// one issuer; the number is `<prefix>-<year>-<sequence>`.
+//
+// The days an invoice states — its issue date, its due date, the period its
+// charges cover — are calendar days in the installation's time zone, kept as
+// `date` columns; `issuedAt` is the instant it was issued.
+//
+// `origin` and `source` on a line are text holding the charge's closed sets,
+// checked when a row is read (`toSubscriptionInvoiceRecord` in @saasicat/core).
+//
+// Optional: adopt it, all four models together, where
+// `tenantBilling.chargeJournal.invoices` is configured, which needs the charge
+// journal.
+//
+// Contract: @saasicat/core (SubscriptionInvoiceRepository).
+
+model SubscriptionInvoice {
+    id             String @id @default(uuid())
+    number         String @unique
+    numberPrefix   String
+    numberYear     Int
+    numberSequence Int
+
+    tenantId       String
+    subscriberId   String
+    subscriptionId String
+    contractId     String
+
+    issuedAt           DateTime
+    issueDate          DateTime @db.Date
+    dueDate            DateTime @db.Date
+    servicePeriodFrom  DateTime @db.Date
+    servicePeriodUntil DateTime @db.Date
+
+    currency        String
+    // The parties as the invoice names them, copied when it was issued.
+    issuerParty     Json
+    subscriberParty Json
+    // The footer lines config/saas.yaml named on the issue date (SC-PRIC-077).
+    footer          Json    @default("[]")
+    // The adapter's treatment, with its name and version, and the tax per rate.
+    taxTreatment    Json
+    taxes           Json
+    totalNet        Decimal @db.Decimal(12, 2)
+    totalTax        Decimal @db.Decimal(12, 2)
+    totalGross      Decimal @db.Decimal(12, 2)
+
+    createdAt DateTime @default(now())
+
+    subscriber Subscriber                   @relation(fields: [subscriberId], references: [id], onDelete: Restrict)
+    contract   SubscriptionContract         @relation(fields: [contractId], references: [id], onDelete: Restrict)
+    lines      SubscriptionInvoiceLine[]
+    document   SubscriptionInvoiceDocument?
+    archive    SubscriptionInvoiceArchive?
+
+    @@unique([numberYear, numberSequence])
+    @@index([subscriberId, issuedAt])
+    @@index([subscriptionId])
+    @@map("subscription_invoices")
+}
+
+model SubscriptionInvoiceLine {
+    id                 String @id @default(uuid())
+    invoiceId          String
+    position           Int
+    chargeId           String @unique
+    contractLineItemId String
+
+    title  String
+    origin String
+    source String
+
+    periodFrom  DateTime @db.Date
+    periodUntil DateTime @db.Date
+
+    amountNet Decimal @db.Decimal(10, 2)
+    taxRate   Decimal @db.Decimal(5, 2)
+
+    invoice          SubscriptionInvoice   @relation(fields: [invoiceId], references: [id], onDelete: Restrict)
+    charge           SubscriberLedgerEntry @relation(fields: [chargeId], references: [id], onDelete: Restrict)
+    contractLineItem ContractLineItem      @relation(fields: [contractLineItemId], references: [id], onDelete: Restrict)
+
+    @@unique([invoiceId, position])
+    @@index([contractLineItemId])
+    @@map("subscription_invoice_lines")
+}
+
+// Where an invoice's document stands. The checksum is recorded once, before
+// the file is archived, and every later download is checked against it; the
+// archive's confirmation and the delivery are set once each. A rendering with
+// another checksum is refused rather than recorded over the first. A run claims
+// the mail before it sends it, so of several instances one does.
+model SubscriptionInvoiceDocument {
+    invoiceId         String    @id
+    // SHA-256 of the rendered file, 64 lower-case hex digits.
+    checksum          String
+    mediaType         String
+    fileName          String
+    // In bytes.
+    size              Int
+    renderedAt        DateTime
+    // Null while the invoice waits for its document.
+    archivedAt        DateTime?
+    // When the run mailing it took it on; null while no run holds it.
+    deliveryClaimedAt DateTime?
+    // Null until the invoice is handed to the mail.
+    deliveredAt       DateTime?
+    deliveredTo       String?
+
+    invoice SubscriptionInvoice @relation(fields: [invoiceId], references: [id], onDelete: Restrict)
+
+    @@index([archivedAt])
+    @@map("subscription_invoice_documents")
+}
+
+model SubscriptionInvoiceNumber {
+    // The year the numbers count in; the range restarts at 1 each year.
+    year Int @id
+    // The last number drawn in that year.
+    last Int
+
+    @@map("subscription_invoice_numbers")
+}

package/prisma-fragments/21-feature-withdrawal.prisma

@@ -0,0 +1,56 @@
+// =============================================================================
+// SaaS platform Prisma fragment: FeatureWithdrawal
+// =============================================================================
+//
+// REFERENCE SNIPPET — see 01-subscription.prisma for conventions.
+//
+// One row per feature withdrawn for a reason outside the platform: an external
+// service the feature depends on stopped, or a law took it away or changed it.
+// From `effectiveFrom` the platform grants the feature to nobody, until the
+// operator lifts the withdrawal from `liftedFrom`. Kept as evidence of what was
+// announced, why, when and by whom, and of the reductions the operator named.
+//
+// What it means for each subscription it reaches — which lines, what each is
+// reduced by — is a `subscription_notices` row of kind feature-withdrawn whose
+// subject is this row's id. Those are written once this row is: who it reaches
+// is read after it is recorded, so a change concluded while it was being
+// announced is reached, and `toldAt` is set in the transaction that writes
+// them. A row whose `toldAt` is still null is told by the next run.
+//
+// `reductions` is a JSON list of `{ kind, key, billingCycle, amountNet }`: the
+// net amount a plan or an add-on, by its key, is reduced by for one whole
+// period of that rhythm without the feature.
+//
+// At most ONE withdrawal of a feature is not lifted at a time. Prisma cannot
+// express a partial unique index; the one that holds it is in
+// sql/constraints.postgres.sql, and it is what makes two operators announcing
+// at the same moment land one withdrawal rather than two.
+//
+// Optional: adopt it where an operator may withdraw features. Without it,
+// withdrawing a feature is off.
+//
+// Contract: @saasicat/core (FeatureWithdrawalRepository).
+
+model FeatureWithdrawal {
+    id         String    @id @default(uuid())
+    featureKey String
+    // Why, in the operator's words, shown to the subscribers as written.
+    reason     String
+
+    effectiveFrom DateTime
+    // Null until the operator lifts it.
+    liftedFrom    DateTime?
+
+    reductions Json @default("[]")
+
+    announcedAt DateTime @default(now())
+    // Who announced it, and who lifted it — actor tags, as the audit log writes them.
+    announcedBy String
+    liftedAt    DateTime?
+    liftedBy    String?
+    // When the subscriptions it reaches were told; null until then.
+    toldAt      DateTime?
+
+    @@index([featureKey])
+    @@map("feature_withdrawals")
+}

package/prisma-fragments/22-subscription-invoice-archive.prisma

@@ -0,0 +1,34 @@
+// =============================================================================
+// SaaSiCat platform Prisma fragment: SubscriptionInvoiceArchive
+// =============================================================================
+//
+// REFERENCE SNIPPET — see 01-subscription.prisma for conventions.
+//
+// The database archive of the invoices' documents (20-subscription-invoice.prisma):
+// one file per invoice, under its invoice, with the checksum recorded when it
+// was rendered. A row is written once and never changed: the migration
+// `1.0-an-invoice-document-is-archived.postgres.sql` installs a trigger that
+// refuses every UPDATE and DELETE, whoever asks. Keep it, with its database
+// backups, as long as the law asks — in Germany 8 years from the end of the
+// calendar year an invoice was issued in — and in the European Union.
+//
+// Optional: adopt it where the invoices' documents are kept in the database,
+// as `persistence.entitlement.subscriptionInvoiceArchive` keeps them. An
+// installation that archives elsewhere, such as object storage with a
+// retention lock, binds its own `InvoiceArchivePort` instead.
+//
+// Contract: @saasicat/core (InvoiceArchivePort).
+
+model SubscriptionInvoiceArchive {
+    invoiceId  String   @id
+    // SHA-256 of `content`, 64 lower-case hex digits.
+    checksum   String
+    mediaType  String
+    fileName   String
+    content    Bytes
+    archivedAt DateTime
+
+    invoice SubscriptionInvoice @relation(fields: [invoiceId], references: [id], onDelete: Restrict)
+
+    @@map("subscription_invoice_archive")
+}

package/prisma-fragments/README.md

@@ -28,25 +28,30 @@ regenerated after fragment changes (`tests/reference-sql-drift.test.js`).
 
 ## Files
 
-| File                                                                 | Models                                                                                |
-| -------------------------------------------------------------------- | ------------------------------------------------------------------------------------- |
-| [`01-subscription.prisma`](01-subscription.prisma)                   | `Subscription`, `CheckoutOffer` + Enums                                               |
-| [`02-promo-code.prisma`](02-promo-code.prisma)                       | `PromoCode`, `PromoCodeRedemption`, `PromoCodeHold`, `PromoCodeValidationLog` + Enums |
-| [`03-plan-versions.prisma`](03-plan-versions.prisma)                 | `Plan`, `PlanVersion`                                                                 |
-| [`04-audit-log.prisma`](04-audit-log.prisma)                         | `AuditLog`                                                                            |
-| [`05-bundle.prisma`](05-bundle.prisma)                               | `Bundle`, `BundleVersion`                                                             |
-| [`06-catalog-entries.prisma`](06-catalog-entries.prisma)             | Capability, feature, quota and marketing catalog models                               |
-| [`07-promotion.prisma`](07-promotion.prisma)                         | `Promotion`                                                                           |
-| [`08-subscription-contract.prisma`](08-subscription-contract.prisma) | `SubscriptionContract`, `ContractLineItem`                                            |
-| [`09-pending-registration.prisma`](09-pending-registration.prisma)   | `PendingRegistration` + `RegistrationStatus`                                          |
-| [`10-super-admin.prisma`](10-super-admin.prisma)                     | `SuperAdminUser`, `SuperAdminMfa`                                                     |
-| [`11-subscription-bundle.prisma`](11-subscription-bundle.prisma)     | `SubscriptionBundle`                                                                  |
-| [`12-applied-settings.prisma`](12-applied-settings.prisma)           | `AppliedSettings`, `SettingsChange`                                                   |
-| [`13-subscriber.prisma`](13-subscriber.prisma)                       | `Subscriber`, `SubscriberTenant`, `SubscriberCorrection`                              |
-| [`14-payments.prisma`](14-payments.prisma)                           | `SubscriberPaymentMethod`, `SubscriberPaymentMethodSetup`, `PaymentEventLog`          |
-| [`15-subscriber-ledger.prisma`](15-subscriber-ledger.prisma)         | `SubscriberLedgerEntry`                                                               |
-| [`16-maintenance-window.prisma`](16-maintenance-window.prisma)       | `MaintenanceWindow`                                                                   |
-| [`17-subscription-notice.prisma`](17-subscription-notice.prisma)     | `SubscriptionNotice`                                                                  |
+| File                                                                               | Models                                                                                                        |
+| ---------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------- |
+| [`01-subscription.prisma`](01-subscription.prisma)                                 | `Subscription`, `CheckoutOffer` + Enums                                                                       |
+| [`02-promo-code.prisma`](02-promo-code.prisma)                                     | `PromoCode`, `PromoCodeRedemption`, `PromoCodeHold`, `PromoCodeValidationLog` + Enums                         |
+| [`03-plan-versions.prisma`](03-plan-versions.prisma)                               | `Plan`, `PlanVersion`                                                                                         |
+| [`04-audit-log.prisma`](04-audit-log.prisma)                                       | `AuditLog`                                                                                                    |
+| [`05-bundle.prisma`](05-bundle.prisma)                                             | `Bundle`, `BundleVersion`                                                                                     |
+| [`06-catalog-entries.prisma`](06-catalog-entries.prisma)                           | Capability, feature, quota and marketing catalog models                                                       |
+| [`07-promotion.prisma`](07-promotion.prisma)                                       | `Promotion`                                                                                                   |
+| [`08-subscription-contract.prisma`](08-subscription-contract.prisma)               | `SubscriptionContract`, `ContractLineItem`                                                                    |
+| [`09-pending-registration.prisma`](09-pending-registration.prisma)                 | `PendingRegistration` + `RegistrationStatus`                                                                  |
+| [`10-super-admin.prisma`](10-super-admin.prisma)                                   | `SuperAdminUser`, `SuperAdminMfa`                                                                             |
+| [`11-subscription-bundle.prisma`](11-subscription-bundle.prisma)                   | `SubscriptionBundle`                                                                                          |
+| [`12-applied-settings.prisma`](12-applied-settings.prisma)                         | `AppliedSettings`, `SettingsChange`                                                                           |
+| [`13-subscriber.prisma`](13-subscriber.prisma)                                     | `Subscriber`, `SubscriberTenant`, `SubscriberCorrection`, `SubscriberTaxOriginChange`, `SubscriberVatIdCheck` |
+| [`14-payments.prisma`](14-payments.prisma)                                         | `SubscriberPaymentMethod`, `SubscriberPaymentMethodSetup`, `PaymentEventLog`                                  |
+| [`15-subscriber-ledger.prisma`](15-subscriber-ledger.prisma)                       | `SubscriberLedgerEntry`                                                                                       |
+| [`16-maintenance-window.prisma`](16-maintenance-window.prisma)                     | `MaintenanceWindow`                                                                                           |
+| [`17-subscription-notice.prisma`](17-subscription-notice.prisma)                   | `SubscriptionNotice`                                                                                          |
+| [`18-version-retirement.prisma`](18-version-retirement.prisma)                     | `VersionRetirement`                                                                                           |
+| [`19-bundle-version-retirement.prisma`](19-bundle-version-retirement.prisma)       | `BundleVersionRetirement`                                                                                     |
+| [`20-subscription-invoice.prisma`](20-subscription-invoice.prisma)                 | `SubscriptionInvoice`, `SubscriptionInvoiceLine`, `SubscriptionInvoiceNumber`, `SubscriptionInvoiceDocument`  |
+| [`21-feature-withdrawal.prisma`](21-feature-withdrawal.prisma)                     | `FeatureWithdrawal`                                                                                           |
+| [`22-subscription-invoice-archive.prisma`](22-subscription-invoice-archive.prisma) | `SubscriptionInvoiceArchive`                                                                                  |
 
 ## How the consumer uses the fragments
 
@@ -102,7 +107,8 @@ from ever being deleted.
 `quota_catalog_entries`, `marketing_projections`, `marketing_settings`,
 `promotions`, `subscription_contracts`, `contract_line_items`,
 `super_admin_users`, `super_admin_mfa`, `subscription_bundles`, `subscribers`,
-`subscriber_tenants`, `subscriber_corrections`, `subscriber_payment_methods`,
+`subscriber_tenants`, `subscriber_corrections`, `subscriber_tax_origin_changes`,
+`subscriber_vat_id_checks`, `subscriber_payment_methods`,
 `subscriber_payment_method_setups`.
 `PendingRegistration` and `PaymentEventLog` carry no `@@map` and keep Prisma's
 default names, `"PendingRegistration"` and `"PaymentEventLog"`.

package/schemas/admin-manifest.schema.json

@@ -142,7 +142,8 @@
                         "platformEmail": { "$ref": "#/$defs/StandardPageDef" },
                         "platformEmailHistory": { "$ref": "#/$defs/StandardPageDef" },
                         "settings": { "$ref": "#/$defs/StandardPageDef" },
-                        "maintenance": { "$ref": "#/$defs/StandardPageDef" }
+                        "maintenance": { "$ref": "#/$defs/StandardPageDef" },
+                        "featureWithdrawals": { "$ref": "#/$defs/StandardPageDef" }
                     }
                 },
                 "projectPages": {