@saasicat/spec 1.0.0-rc.5 → 1.0.0-rc.7

package/README.md

@@ -83,5 +83,6 @@ pnpm add @saasicat/spec
 ## Next
 
 - [Data model](../../docs/explanation/data-model.md) — the tables the fragments declare
-- [From capability to contract](../../docs/explanation/capability-to-contract.md) — what the schemas describe
+- [From capability to contract](../../docs/explanation/capability-to-contract.md) — what the schemas
+  describe
 - [Codegen](../../docs/explanation/adr/0006-spec-to-types-codegen.md) — how types are derived from them

package/admin-api.openapi.yaml

@@ -29,7 +29,7 @@ openapi: 3.1.0
 
 info:
     title: SaaS Platform SuperAdmin API
-    version: 1.0.0-rc.5
+    version: 1.0.0-rc.7
     description: |
         Read and write operations for platform administration:
         tenants, users, subscriptions, promo codes, audit log,
@@ -1391,10 +1391,8 @@ components:
         # ────────── Catalog V2 (DTO = SSOT: packages/nest/src/catalog/dto/*) ──────────
         CatalogPlanCreate:
             type: object
-            required: [projectKey, planKey, label]
+            required: [planKey, label]
             properties:
-                projectKey:
-                    { type: string, pattern: '^[a-z][a-z0-9-]*$', description: 'kebab-case' }
                 planKey:
                     {
                         type: string,
@@ -1435,9 +1433,8 @@ components:
 
         CatalogBundleCreate:
             type: object
-            required: [projectKey, bundleKey, label]
+            required: [bundleKey, label]
             properties:
-                projectKey: { type: string, pattern: '^[a-z][a-z0-9-]*$' }
                 bundleKey: { type: string, pattern: '^[A-Z][A-Z0-9_]*$', description: 'no hyphen' }
                 label: { type: string, minLength: 1, maxLength: 120 }
                 description: { type: string, maxLength: 2000 }
@@ -1495,9 +1492,8 @@ components:
 
         CatalogMarketingProjectionCreate:
             type: object
-            required: [projectKey, targetType, targetVersionId, displayLabel, description]
+            required: [targetType, targetVersionId, displayLabel, description]
             properties:
-                projectKey: { type: string, pattern: '^[a-z][a-z0-9-]*$' }
                 targetType: { type: string, enum: [PLAN, BUNDLE] }
                 targetVersionId: { type: string }
                 locale: { type: string, pattern: '^[a-z]{2}(-[A-Z]{2})?$', default: de }
@@ -1613,9 +1609,8 @@ components:
 
         CatalogMarketingSettingsUpdate:
             type: object
-            required: [projectKey, activeLocales]
+            required: [activeLocales]
             properties:
-                projectKey: { type: string, pattern: '^[a-z][a-z0-9-]*$' }
                 activeLocales:
                     type: array
                     uniqueItems: true
@@ -1623,9 +1618,8 @@ components:
 
         CatalogPromotionCreate:
             type: object
-            required: [projectKey, internalLabel, type, value, validFrom, validTo]
+            required: [internalLabel, type, value, validFrom, validTo]
             properties:
-                projectKey: { type: string, pattern: '^[a-z][a-z0-9-]*$' }
                 internalLabel: { type: string, maxLength: 120 }
                 type: { type: string, enum: [percent, amount, intro, freeMonths] }
                 value:
@@ -1698,10 +1692,15 @@ components:
         # ────────── Plan-Catalog (mirror of plans.yaml) ──────────
         PlanCatalog:
             type: object
-            required: [schemaVersion, projectKey, currency, vatRate, plans]
+            required: [schemaVersion, app, currency, vatRate, plans]
             properties:
                 schemaVersion: { type: integer, const: 1 }
-                projectKey: { type: string, description: 'Project key of the app (kebab-case)' }
+                app:
+                    type: object
+                    required: [name]
+                    description: 'App identity — the only place the application is named'
+                    properties:
+                        name: { type: string, minLength: 1 }
                 currency: { type: string, pattern: '^[A-Z]{3}$' }
                 vatRate: { type: number, format: decimal, description: 'in percent' }
                 features:

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@saasicat/spec",
-  "version": "1.0.0-rc.5",
+  "version": "1.0.0-rc.7",
   "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

@@ -61,12 +61,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
@@ -171,8 +201,7 @@ model SubscriptionPaymentMethod {
 // -----------------------------------------------------------------------------
 
 model CheckoutOffer {
-    id         String @id @default(uuid())
-    projectKey String
+    id String @id @default(uuid())
 
     planKey       String
     planVersionId String?
@@ -197,6 +226,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'
@@ -268,21 +264,25 @@ model MarketingProjection {
     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

@@ -25,9 +25,8 @@ enum ContractLineItemKind {
 }
 
 model SubscriptionContract {
-    id         String @id @default(uuid())
-    projectKey String
-    tenantId   String
+    id       String @id @default(uuid())
+    tenantId String
 
     status         SubscriptionContractStatus @default(active)
     effectiveFrom  DateTime
@@ -54,7 +53,7 @@ model SubscriptionContract {
     // tenant Tenant @relation(fields: [tenantId], references: [id], onDelete: Cascade)
 
     @@index([tenantId, status, effectiveFrom])
-    @@index([projectKey, status])
+    @@index([status])
     @@index([originalOfferId])
     @@map("subscription_contracts")
 }

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?

package/schemas/plan-catalog.schema.json

@@ -4,22 +4,17 @@
     "title": "PlanCatalog",
     "description": "Language-neutral definition of a plan catalog + app identity for a SaaS app. Maintained by the consumer as a YAML/JSON file (`config/saas.yaml`) and mirrored into platform tables at backend boot.",
     "type": "object",
-    "required": ["schemaVersion", "projectKey", "currency", "vatRate"],
+    "required": ["schemaVersion", "app", "currency", "vatRate"],
     "additionalProperties": false,
     "properties": {
         "schemaVersion": {
             "type": "integer",
             "const": 1
         },
-        "projectKey": {
-            "type": "string",
-            "pattern": "^[a-z][a-z0-9-]{1,30}$",
-            "description": "Unique key of the consuming project. Cross-audit marker."
-        },
         "app": {
             "type": "object",
             "additionalProperties": false,
-            "description": "App identity block (branding + version). Consumed by AdminPublicBootController + AdminManifestConfigFactory.",
+            "description": "App identity block (branding + version). One installation serves one application, so this is the only place it is named. Consumed by AdminPublicBootController + AdminManifestConfigFactory.",
             "required": ["name"],
             "properties": {
                 "name": {

package/sql/1.0-remove-project-key.postgres.sql

@@ -0,0 +1,203 @@
+-- =============================================================================
+-- SaaSiCat 1.0 — remove `projectKey` from the catalogue tables.
+-- =============================================================================
+--
+-- project-key-history: this file names the retired identifier because dropping
+-- it is what it does.
+--
+-- One installation serves one application, so a plan key, a bundle key, a
+-- feature key and a quota key are unique for the installation. The column that
+-- suggested otherwise never had a second value to hold: nothing in the platform
+-- could configure a second project, and `subscriptions.tenantId` is unique
+-- installation-wide, so two applications in one database was never a shape this
+-- model could carry.
+--
+-- Run this against an existing database, inside the transaction it opens. It is
+-- a one-way door — the values are dropped, not archived — but it is safe to run
+-- again: a table whose column has already gone is skipped, so a second run does
+-- nothing rather than failing.
+--
+--   psql "$DATABASE_URL" -f 1.0-remove-project-key.postgres.sql
+--
+-- The first statement is a guard. If the affected tables between them hold rows
+-- under more than one project, the migration STOPS and names the table each key
+-- came from, rather than merging rows nobody meant to merge — two `STANDARD`
+-- plans would otherwise collide on the new unique index, and which of them
+-- survives is not a decision a migration should take.
+--
+-- The question is asked across the tables and not once per table. A per-table
+-- count is one where `plans` holds only `alpha` and `bundles` only `beta`, and
+-- that is a two-project installation whose evidence this migration would drop.
+--
+-- Applies to a database created from `reference-schema.postgres.sql` at 0.27 or
+-- any release before 1.0.
+
+BEGIN;
+
+DO $$
+DECLARE
+    affected CONSTANT text[] := ARRAY[
+        'plans',
+        'bundles',
+        'capability_catalog_entries',
+        'feature_catalog_entries',
+        'quota_catalog_entries',
+        'marketing_projections',
+        'marketing_settings',
+        'promotions',
+        'checkout_offers',
+        'subscription_contracts'
+    ];
+    target text;
+    keys_here text[];
+    -- Every key seen anywhere, with the table it came from, so the message can
+    -- say where the disagreement is rather than only that there is one.
+    seen text[] := ARRAY[]::text[];
+    witnesses text[] := ARRAY[]::text[];
+BEGIN
+    FOREACH target IN ARRAY affected LOOP
+        IF to_regclass(format('%I', target)) IS NULL THEN
+            CONTINUE;  -- an installation that never adopted this fragment
+        END IF;
+        -- A table that has already been migrated says nothing, and asking it
+        -- would raise `column "projectKey" does not exist`. Everything below
+        -- this block is written with IF EXISTS / IF NOT EXISTS, so with this
+        -- check the whole file is a no-op on a second run rather than an error
+        -- — which is what a deploy that retries, or a container that restarts,
+        -- needs it to be.
+        IF NOT EXISTS (
+            SELECT 1 FROM information_schema.columns
+            WHERE table_schema = current_schema()
+              AND table_name = target
+              AND column_name = 'projectKey'
+        ) THEN
+            CONTINUE;
+        END IF;
+        EXECUTE format('SELECT array_agg(DISTINCT "projectKey") FROM %I', target)
+            INTO keys_here;
+        IF keys_here IS NULL THEN
+            CONTINUE;  -- an empty table says nothing about the installation
+        END IF;
+        seen := ARRAY(SELECT DISTINCT unnest(seen || keys_here) ORDER BY 1);
+        witnesses := witnesses || format('%s: %s', target, array_to_string(keys_here, ', '));
+    END LOOP;
+
+    IF array_length(seen, 1) > 1 THEN
+        RAISE EXCEPTION
+            'The catalogue holds rows under % different project keys (%). Removing the column '
+            'would merge them, and a duplicate key would then collide on the new unique index. '
+            'Per table: %. Decide which rows belong to this installation and delete the rest, '
+            'then run this migration again.',
+            array_length(seen, 1),
+            array_to_string(seen, ', '),
+            array_to_string(witnesses, ' | ');
+    END IF;
+END $$;
+
+-- ─── The indexes that carried the column ───
+
+DROP INDEX IF EXISTS "checkout_offers_projectKey_status_idx";
+DROP INDEX IF EXISTS "plans_projectKey_deletedAt_idx";
+DROP INDEX IF EXISTS "plans_projectKey_planKey_key";
+DROP INDEX IF EXISTS "bundles_projectKey_deletedAt_idx";
+DROP INDEX IF EXISTS "bundles_projectKey_bundleKey_key";
+DROP INDEX IF EXISTS "capability_catalog_entries_projectKey_codeStatus_idx";
+DROP INDEX IF EXISTS "capability_catalog_entries_projectKey_featureKey_idx";
+DROP INDEX IF EXISTS "capability_catalog_entries_projectKey_capabilityKey_key";
+DROP INDEX IF EXISTS "feature_catalog_entries_projectKey_discoveryStatus_idx";
+DROP INDEX IF EXISTS "feature_catalog_entries_projectKey_plannedOnly_idx";
+DROP INDEX IF EXISTS "feature_catalog_entries_projectKey_featureKey_key";
+DROP INDEX IF EXISTS "quota_catalog_entries_projectKey_discoveryStatus_idx";
+DROP INDEX IF EXISTS "quota_catalog_entries_projectKey_quotaKey_key";
+DROP INDEX IF EXISTS "marketing_projections_projectKey_targetType_locale_priority_idx";
+DROP INDEX IF EXISTS "marketing_settings_projectKey_key";
+DROP INDEX IF EXISTS "promotions_projectKey_targetType_validFrom_validTo_idx";
+DROP INDEX IF EXISTS "subscription_contracts_projectKey_status_idx";
+
+-- ─── The column, the tightened uniques, and the shrunken lookup indexes ───
+--
+-- Per table, and only where the table is there. The Prisma fragments are
+-- adopted à la carte — `saasicat schema check` reports what an app did not take
+-- — and an unconditional `ALTER TABLE "bundles"` raises `relation does not
+-- exist` on an app that never adopted bundles, which rolls back everything,
+-- including the tables it could have migrated. `IF EXISTS` on the column does
+-- not help when it is the relation that is missing.
+--
+-- One list, so a table and what happens to it cannot drift apart.
+
+DO $$
+DECLARE
+    step record;
+    statement text;
+BEGIN
+    FOR step IN
+        SELECT * FROM (VALUES
+            ('plans', ARRAY[
+                'ALTER TABLE "plans" DROP COLUMN IF EXISTS "projectKey"',
+                'CREATE UNIQUE INDEX IF NOT EXISTS "plans_planKey_key" ON "plans"("planKey")',
+                'CREATE INDEX IF NOT EXISTS "plans_deletedAt_idx" ON "plans"("deletedAt")'
+            ]),
+            ('bundles', ARRAY[
+                'ALTER TABLE "bundles" DROP COLUMN IF EXISTS "projectKey"',
+                'CREATE UNIQUE INDEX IF NOT EXISTS "bundles_bundleKey_key" ON "bundles"("bundleKey")',
+                'CREATE INDEX IF NOT EXISTS "bundles_deletedAt_idx" ON "bundles"("deletedAt")'
+            ]),
+            ('capability_catalog_entries', ARRAY[
+                'ALTER TABLE "capability_catalog_entries" DROP COLUMN IF EXISTS "projectKey"',
+                'CREATE UNIQUE INDEX IF NOT EXISTS "capability_catalog_entries_capabilityKey_key" ON "capability_catalog_entries"("capabilityKey")',
+                'CREATE INDEX IF NOT EXISTS "capability_catalog_entries_codeStatus_idx" ON "capability_catalog_entries"("codeStatus")',
+                'CREATE INDEX IF NOT EXISTS "capability_catalog_entries_featureKey_idx" ON "capability_catalog_entries"("featureKey")'
+            ]),
+            ('feature_catalog_entries', ARRAY[
+                'ALTER TABLE "feature_catalog_entries" DROP COLUMN IF EXISTS "projectKey"',
+                'CREATE UNIQUE INDEX IF NOT EXISTS "feature_catalog_entries_featureKey_key" ON "feature_catalog_entries"("featureKey")',
+                'CREATE INDEX IF NOT EXISTS "feature_catalog_entries_discoveryStatus_idx" ON "feature_catalog_entries"("discoveryStatus")',
+                'CREATE INDEX IF NOT EXISTS "feature_catalog_entries_plannedOnly_idx" ON "feature_catalog_entries"("plannedOnly")'
+            ]),
+            ('quota_catalog_entries', ARRAY[
+                'ALTER TABLE "quota_catalog_entries" DROP COLUMN IF EXISTS "projectKey"',
+                'CREATE UNIQUE INDEX IF NOT EXISTS "quota_catalog_entries_quotaKey_key" ON "quota_catalog_entries"("quotaKey")',
+                'CREATE INDEX IF NOT EXISTS "quota_catalog_entries_discoveryStatus_idx" ON "quota_catalog_entries"("discoveryStatus")'
+            ]),
+            ('marketing_projections', ARRAY[
+                'ALTER TABLE "marketing_projections" DROP COLUMN IF EXISTS "projectKey"',
+                'CREATE INDEX IF NOT EXISTS "marketing_projections_targetType_locale_priority_idx" ON "marketing_projections"("targetType", "locale", "priority")'
+            ]),
+            ('promotions', ARRAY[
+                'ALTER TABLE "promotions" DROP COLUMN IF EXISTS "projectKey"',
+                'CREATE INDEX IF NOT EXISTS "promotions_targetType_validFrom_validTo_idx" ON "promotions"("targetType", "validFrom", "validTo")'
+            ]),
+            ('checkout_offers', ARRAY[
+                'ALTER TABLE "checkout_offers" DROP COLUMN IF EXISTS "projectKey"',
+                'CREATE INDEX IF NOT EXISTS "checkout_offers_status_idx" ON "checkout_offers"("status")'
+            ]),
+            ('subscription_contracts', ARRAY[
+                'ALTER TABLE "subscription_contracts" DROP COLUMN IF EXISTS "projectKey"',
+                'CREATE INDEX IF NOT EXISTS "subscription_contracts_status_idx" ON "subscription_contracts"("status")'
+            ]),
+            -- `marketing_settings` loses the column and gains the identity that
+            -- replaces it: one row, under a constant primary key. The CHECK is
+            -- what actually holds it. A default only applies where the caller
+            -- omits the id and a primary key accepts every distinct value, so
+            -- without it a consumer writing the row directly could make as many
+            -- as it liked — which is what the comment claiming otherwise was
+            -- worth.
+            ('marketing_settings', ARRAY[
+                'ALTER TABLE "marketing_settings" DROP COLUMN IF EXISTS "projectKey"',
+                'ALTER TABLE "marketing_settings" ALTER COLUMN "id" SET DEFAULT ''marketing-settings''',
+                'UPDATE "marketing_settings" SET "id" = ''marketing-settings''',
+                'ALTER TABLE "marketing_settings" DROP CONSTRAINT IF EXISTS "marketing_settings_is_a_singleton"',
+                'ALTER TABLE "marketing_settings" ADD CONSTRAINT "marketing_settings_is_a_singleton" CHECK ("id" = ''marketing-settings'')'
+            ])
+        ) AS t(relname, statements)
+    LOOP
+        IF to_regclass(format('%I', step.relname)) IS NULL THEN
+            CONTINUE;  -- a fragment this installation never adopted
+        END IF;
+        FOREACH statement IN ARRAY step.statements LOOP
+            EXECUTE statement;
+        END LOOP;
+    END LOOP;
+END $$;
+
+COMMIT;

package/sql/constraints.postgres.sql

@@ -17,3 +17,22 @@ CREATE UNIQUE INDEX IF NOT EXISTS plan_versions_draft_per_plan
 
 CREATE UNIQUE INDEX IF NOT EXISTS bundle_versions_draft_per_bundle
     ON bundle_versions ("bundleId") WHERE "publishedAt" IS NULL;
+
+-- `marketing_settings` holds at most ONE row.
+--
+-- The Prisma DSL cannot say this, and the constant default on `id` does not: a
+-- default applies only where the caller omits the value, and a primary key
+-- accepts every distinct one. A consumer writing the row directly could make as
+-- many as it liked, and the repository would then read one and ignore the rest.
+--
+-- `ADD CONSTRAINT` has no `IF NOT EXISTS`, and this file is applied again on
+-- every deployment — so it is dropped first. Two plain statements rather than a
+-- dollar-quoted `DO` block on purpose: every consumer of this file splits it at
+-- the statement separator, and a dollar-quoted body would need each of those
+-- splitters to become a SQL lexer. For the same reason no comment in this file
+-- may contain that separator — one here did, and three splitters cut the
+-- sentence in half.
+ALTER TABLE marketing_settings
+    DROP CONSTRAINT IF EXISTS marketing_settings_is_a_singleton;
+ALTER TABLE marketing_settings
+    ADD CONSTRAINT marketing_settings_is_a_singleton CHECK ("id" = 'marketing-settings');

package/sql/reference-schema.postgres.sql

@@ -60,8 +60,11 @@ CREATE TABLE "subscriptions" (
     "trialEndsAt" TIMESTAMP(3),
     "startedAt" TIMESTAMP(3),
     "canceledAt" TIMESTAMP(3),
+    "canceledEffectiveAt" TIMESTAMP(3),
     "currentPeriodStart" TIMESTAMP(3),
     "currentPeriodEnd" TIMESTAMP(3),
+    "minimumTermUntil" TIMESTAMP(3),
+    "billingAnchorDay" INTEGER,
     "planVersionId" TEXT NOT NULL,
     "pendingPlanVersionId" TEXT,
     "pendingPlanVersionEffectiveAt" TIMESTAMP(3),
@@ -111,7 +114,6 @@ CREATE TABLE "subscription_payment_methods" (
 -- CreateTable
 CREATE TABLE "checkout_offers" (
     "id" TEXT NOT NULL,
-    "projectKey" TEXT NOT NULL,
     "planKey" TEXT NOT NULL,
     "planVersionId" TEXT,
     "billingCycle" TEXT NOT NULL,
@@ -197,7 +199,6 @@ CREATE TABLE "promo_code_validation_logs" (
 -- CreateTable
 CREATE TABLE "plans" (
     "id" TEXT NOT NULL,
-    "projectKey" TEXT NOT NULL,
     "planKey" TEXT NOT NULL,
     "label" TEXT NOT NULL,
     "description" TEXT,
@@ -257,7 +258,6 @@ CREATE TABLE "audit_logs" (
 -- CreateTable
 CREATE TABLE "bundles" (
     "id" TEXT NOT NULL,
-    "projectKey" TEXT NOT NULL,
     "bundleKey" TEXT NOT NULL,
     "label" TEXT NOT NULL,
     "description" TEXT,
@@ -302,7 +302,6 @@ CREATE TABLE "bundle_versions" (
 -- CreateTable
 CREATE TABLE "capability_catalog_entries" (
     "id" TEXT NOT NULL,
-    "projectKey" TEXT NOT NULL,
     "capabilityKey" TEXT NOT NULL,
     "label" TEXT NOT NULL,
     "description" TEXT,
@@ -327,7 +326,6 @@ CREATE TABLE "capability_catalog_entries" (
 -- CreateTable
 CREATE TABLE "feature_catalog_entries" (
     "id" TEXT NOT NULL,
-    "projectKey" TEXT NOT NULL,
     "featureKey" TEXT NOT NULL,
     "label" TEXT NOT NULL,
     "description" TEXT,
@@ -356,7 +354,6 @@ CREATE TABLE "feature_catalog_entries" (
 -- CreateTable
 CREATE TABLE "quota_catalog_entries" (
     "id" TEXT NOT NULL,
-    "projectKey" TEXT NOT NULL,
     "quotaKey" TEXT NOT NULL,
     "label" TEXT NOT NULL,
     "description" TEXT,
@@ -382,7 +379,6 @@ CREATE TABLE "quota_catalog_entries" (
 -- CreateTable
 CREATE TABLE "marketing_projections" (
     "id" TEXT NOT NULL,
-    "projectKey" TEXT NOT NULL,
     "targetType" TEXT NOT NULL,
     "targetVersionId" TEXT NOT NULL,
     "locale" TEXT NOT NULL DEFAULT 'de',
@@ -405,8 +401,7 @@ CREATE TABLE "marketing_projections" (
 
 -- CreateTable
 CREATE TABLE "marketing_settings" (
-    "id" TEXT NOT NULL,
-    "projectKey" TEXT NOT NULL,
+    "id" TEXT NOT NULL DEFAULT 'marketing-settings',
     "activeLocales" JSONB NOT NULL DEFAULT '[]',
     "createdAt" TIMESTAMP(3) NOT NULL DEFAULT CURRENT_TIMESTAMP,
     "updatedAt" TIMESTAMP(3) NOT NULL,
@@ -417,7 +412,6 @@ CREATE TABLE "marketing_settings" (
 -- CreateTable
 CREATE TABLE "promotions" (
     "id" TEXT NOT NULL,
-    "projectKey" TEXT NOT NULL,
     "internalLabel" TEXT NOT NULL,
     "type" TEXT NOT NULL,
     "value" JSONB NOT NULL,
@@ -441,7 +435,6 @@ CREATE TABLE "promotions" (
 -- CreateTable
 CREATE TABLE "subscription_contracts" (
     "id" TEXT NOT NULL,
-    "projectKey" TEXT NOT NULL,
     "tenantId" TEXT NOT NULL,
     "status" "SubscriptionContractStatus" NOT NULL DEFAULT 'active',
     "effectiveFrom" TIMESTAMP(3) NOT NULL,
@@ -562,6 +555,9 @@ CREATE TABLE "subscription_bundles" (
     "bundleVersionId" TEXT NOT NULL,
     "startedAt" TIMESTAMP(3) NOT NULL,
     "minimumTermEndsAt" TIMESTAMP(3),
+    "billingCycle" TEXT,
+    "currentPeriodStart" TIMESTAMP(3),
+    "currentPeriodEnd" TIMESTAMP(3),
     "canceledAt" TIMESTAMP(3),
     "canceledEffectiveAt" TIMESTAMP(3),
     "createdAt" TIMESTAMP(3) NOT NULL DEFAULT CURRENT_TIMESTAMP,
@@ -589,7 +585,7 @@ CREATE INDEX "subscriptions_currentPeriodEnd_idx" ON "subscriptions"("currentPer
 CREATE UNIQUE INDEX "subscription_payment_methods_subscriptionId_key" ON "subscription_payment_methods"("subscriptionId");
 
 -- CreateIndex
-CREATE INDEX "checkout_offers_projectKey_status_idx" ON "checkout_offers"("projectKey", "status");
+CREATE INDEX "checkout_offers_status_idx" ON "checkout_offers"("status");
 
 -- CreateIndex
 CREATE UNIQUE INDEX "promo_codes_code_key" ON "promo_codes"("code");
@@ -622,10 +618,10 @@ CREATE INDEX "promo_code_validation_logs_ipHash_createdAt_idx" ON "promo_code_va
 CREATE INDEX "promo_code_validation_logs_sessionId_createdAt_idx" ON "promo_code_validation_logs"("sessionId", "createdAt");
 
 -- CreateIndex
-CREATE INDEX "plans_projectKey_deletedAt_idx" ON "plans"("projectKey", "deletedAt");
+CREATE INDEX "plans_deletedAt_idx" ON "plans"("deletedAt");
 
 -- CreateIndex
-CREATE UNIQUE INDEX "plans_projectKey_planKey_key" ON "plans"("projectKey", "planKey");
+CREATE UNIQUE INDEX "plans_planKey_key" ON "plans"("planKey");
 
 -- CreateIndex
 CREATE INDEX "plan_versions_planId_supersededAt_idx" ON "plan_versions"("planId", "supersededAt");
@@ -652,10 +648,10 @@ CREATE INDEX "audit_logs_entity_action_createdAt_idx" ON "audit_logs"("entity",
 CREATE INDEX "audit_logs_actorTag_createdAt_idx" ON "audit_logs"("actorTag", "createdAt");
 
 -- CreateIndex
-CREATE INDEX "bundles_projectKey_deletedAt_idx" ON "bundles"("projectKey", "deletedAt");
+CREATE INDEX "bundles_deletedAt_idx" ON "bundles"("deletedAt");
 
 -- CreateIndex
-CREATE UNIQUE INDEX "bundles_projectKey_bundleKey_key" ON "bundles"("projectKey", "bundleKey");
+CREATE UNIQUE INDEX "bundles_bundleKey_key" ON "bundles"("bundleKey");
 
 -- CreateIndex
 CREATE INDEX "bundle_versions_bundleId_supersededAt_idx" ON "bundle_versions"("bundleId", "supersededAt");
@@ -670,46 +666,43 @@ CREATE INDEX "bundle_versions_bundleId_validFrom_idx" ON "bundle_versions"("bund
 CREATE UNIQUE INDEX "bundle_versions_bundleId_version_key" ON "bundle_versions"("bundleId", "version");
 
 -- CreateIndex
-CREATE INDEX "capability_catalog_entries_projectKey_codeStatus_idx" ON "capability_catalog_entries"("projectKey", "codeStatus");
+CREATE INDEX "capability_catalog_entries_codeStatus_idx" ON "capability_catalog_entries"("codeStatus");
 
 -- CreateIndex
-CREATE INDEX "capability_catalog_entries_projectKey_featureKey_idx" ON "capability_catalog_entries"("projectKey", "featureKey");
+CREATE INDEX "capability_catalog_entries_featureKey_idx" ON "capability_catalog_entries"("featureKey");
 
 -- CreateIndex
-CREATE UNIQUE INDEX "capability_catalog_entries_projectKey_capabilityKey_key" ON "capability_catalog_entries"("projectKey", "capabilityKey");
+CREATE UNIQUE INDEX "capability_catalog_entries_capabilityKey_key" ON "capability_catalog_entries"("capabilityKey");
 
 -- CreateIndex
-CREATE INDEX "feature_catalog_entries_projectKey_discoveryStatus_idx" ON "feature_catalog_entries"("projectKey", "discoveryStatus");
+CREATE INDEX "feature_catalog_entries_discoveryStatus_idx" ON "feature_catalog_entries"("discoveryStatus");
 
 -- CreateIndex
-CREATE INDEX "feature_catalog_entries_projectKey_plannedOnly_idx" ON "feature_catalog_entries"("projectKey", "plannedOnly");
+CREATE INDEX "feature_catalog_entries_plannedOnly_idx" ON "feature_catalog_entries"("plannedOnly");
 
 -- CreateIndex
-CREATE UNIQUE INDEX "feature_catalog_entries_projectKey_featureKey_key" ON "feature_catalog_entries"("projectKey", "featureKey");
+CREATE UNIQUE INDEX "feature_catalog_entries_featureKey_key" ON "feature_catalog_entries"("featureKey");
 
 -- CreateIndex
-CREATE INDEX "quota_catalog_entries_projectKey_discoveryStatus_idx" ON "quota_catalog_entries"("projectKey", "discoveryStatus");
+CREATE INDEX "quota_catalog_entries_discoveryStatus_idx" ON "quota_catalog_entries"("discoveryStatus");
 
 -- CreateIndex
-CREATE UNIQUE INDEX "quota_catalog_entries_projectKey_quotaKey_key" ON "quota_catalog_entries"("projectKey", "quotaKey");
+CREATE UNIQUE INDEX "quota_catalog_entries_quotaKey_key" ON "quota_catalog_entries"("quotaKey");
 
 -- CreateIndex
-CREATE INDEX "marketing_projections_projectKey_targetType_locale_priority_idx" ON "marketing_projections"("projectKey", "targetType", "locale", "priority");
+CREATE INDEX "marketing_projections_targetType_locale_priority_idx" ON "marketing_projections"("targetType", "locale", "priority");
 
 -- CreateIndex
 CREATE UNIQUE INDEX "marketing_projections_targetType_targetVersionId_locale_key" ON "marketing_projections"("targetType", "targetVersionId", "locale");
 
 -- CreateIndex
-CREATE UNIQUE INDEX "marketing_settings_projectKey_key" ON "marketing_settings"("projectKey");
-
--- CreateIndex
-CREATE INDEX "promotions_projectKey_targetType_validFrom_validTo_idx" ON "promotions"("projectKey", "targetType", "validFrom", "validTo");
+CREATE INDEX "promotions_targetType_validFrom_validTo_idx" ON "promotions"("targetType", "validFrom", "validTo");
 
 -- CreateIndex
 CREATE INDEX "subscription_contracts_tenantId_status_effectiveFrom_idx" ON "subscription_contracts"("tenantId", "status", "effectiveFrom");
 
 -- CreateIndex
-CREATE INDEX "subscription_contracts_projectKey_status_idx" ON "subscription_contracts"("projectKey", "status");
+CREATE INDEX "subscription_contracts_status_idx" ON "subscription_contracts"("status");
 
 -- CreateIndex
 CREATE INDEX "subscription_contracts_originalOfferId_idx" ON "subscription_contracts"("originalOfferId");
@@ -808,3 +801,22 @@ CREATE UNIQUE INDEX IF NOT EXISTS plan_versions_draft_per_plan
 
 CREATE UNIQUE INDEX IF NOT EXISTS bundle_versions_draft_per_bundle
     ON bundle_versions ("bundleId") WHERE "publishedAt" IS NULL;
+
+-- `marketing_settings` holds at most ONE row.
+--
+-- The Prisma DSL cannot say this, and the constant default on `id` does not: a
+-- default applies only where the caller omits the value, and a primary key
+-- accepts every distinct one. A consumer writing the row directly could make as
+-- many as it liked, and the repository would then read one and ignore the rest.
+--
+-- `ADD CONSTRAINT` has no `IF NOT EXISTS`, and this file is applied again on
+-- every deployment — so it is dropped first. Two plain statements rather than a
+-- dollar-quoted `DO` block on purpose: every consumer of this file splits it at
+-- the statement separator, and a dollar-quoted body would need each of those
+-- splitters to become a SQL lexer. For the same reason no comment in this file
+-- may contain that separator — one here did, and three splitters cut the
+-- sentence in half.
+ALTER TABLE marketing_settings
+    DROP CONSTRAINT IF EXISTS marketing_settings_is_a_singleton;
+ALTER TABLE marketing_settings
+    ADD CONSTRAINT marketing_settings_is_a_singleton CHECK ("id" = 'marketing-settings');